Getting Started

이 페이지는 Token History API에 관한 간단한 예제를 소개합니다.

Scenario

Alice가 Token History API를 사용하여 그녀의 최근 KLAY 전송내역(보낸 내역 + 받은 내역) 10개를 조회하려고 합니다. Alice의 정보는 다음과 같습니다.

  • 블록체인 네트워크: Cypress

  • EOA 주소: 0x60871ee4e48040892e95630ead8ad5fd44d4b34e

  • 조회하려는 거래내역 개수: 10

  • Access Key: alice-access-key

  • Secret: alice-secret-string

The API to Use

GET /klay/transfer

KLAY 전송내역은 GET /klay/transfer로 조회할 수 있습니다. 해당 API는 다음과 같은 Query Parameter들을 받습니다.

Name

Description

Required

Data Type

eoaAddress

EOA 주소 필터

Yes

string

txHash

트랜잭션 해시

No

string

cursor

트랜잭션 오프셋

No

string

size

반환되는 아이템 개수

No

integer

Alice가 조회하려는 내역은 0x60871e...d4b34e 주소의 최신 거래내역 10개이므로 다음과 같은 URL을 준비합니다.

/klay/trasfer?size=10&eoaAddress=0x60871ee4e48040892e95630ead8ad5fd44d4b34e

Required Headers

GET /klay/transfer는 다음 헤더값을 필요로 합니다.

Name

Value

Authorization

Basic {base64-encoded-credential}

X-KRN

krn:{chain-id}:th

Authorization

Token History API를 비롯해 KAS에서 제공하는 모든 API를 사용하려는 사용자는 사용 자격을 증명해야 합니다. KAS API는 Basic Auth를 사용하며 사용자는 매 요청마다 Basic {base64-encoded-credential}을 Authorization 헤더로 제출합니다. 다음은 Alice가 Javascript로 {base64-encoded-credential}을 생성할 경우의 예시입니다.

let accessKey = 'alice-access-key';
let secretString = 'alice-string-string';
let credential = btoa(`${accessKey}:${secretKey}`));
// credential === 'YWxpY2UtYWNjZXNzLWtleTphbGljZS1zdHJpbmctc3RyaW5n'

Chain ID: chain-id

체인 아이디는 Token History API에서 지원하는 블록체인 네트워크 아이디입니다. 허용되는 체인 아이디는 다음과 같습니다.

Network

Chain ID

Baobab: Klaytn Testnet

1001

Cypress: Klaytn Mainnet

8217

Alice는 Cypress의 KLAY 내역을 조회하므로 "X-Chain-Id: 8217"을 사용합니다.

KRN (KAS Resource Name): KRN

KAS는 각 API가 제공하는 서비스와 리소스를 식별하는 고유 식별자 KRN을 정의합니다. KAS에서 사용할 수 있는 서비스와 서비스가 생성/조회/변경/삭제할 수 있는 모든 리소스는 고유의 KRN을 가집니다.

Token History API는 두개의 KRN을 사용하는데 각각 Token History API 서비스를 식별하는 krn:{chain-id}:th, Token History API가 관리하는 리소스인 Preset을 식별하는 krn:{chain-id}:th:{account-id}:preset:{resource-id}입니다.

Token History API는 서비스로 분류되어 krn:{chain-id}:th KRN을 사용합니다. Token History API 중 Preset을 조회/변경/삭제하는 일부 API들은 krn:{chain-id}:th:{account-id}:preset:{resource-id} KRN을 사용합니다.

사용자는 호출하려는 API에 따라 적합한 KRN을 사용하셔야 합니다. Alice의 경우 GET /klay/transfer를 Cypress를 대상으로 호출하므로 "X-KRN: krn:8217:th"를 사용합니다.

Calling the API

모든 준비는 끝났습니다. 이제 다음과 같이 Token History API를 호출합니다. Token History API의 Base Endpoint는 https://th-api.beta.klaytn.io/v1 입니다.

cURL

$ curl -X GET "https://th.api.kas.io/v1/klay/transfer?size=10&eoaAddress=0x60871ee4e48040892e95630ead8ad5fd44d4b34e" \
-u "alice-access-key:alice-secret-string" \
-H "X-KRN: krn:8217:th"

Node.js

const request = require('request');
let accessKey = 'alice-access-key';
let secretString = 'alice-string-string';
let credential = btoa(`${accessKey}:${secretKey}`));
let krn = 'krn:8217:th';
let base = 'https://th-api.beta.klaytn.io/v1';
let call = `${base}/klay/transfer?size=10&eoaAddress=0x60871ee4e48040892e95630ead8ad5fd44d4b34e`;
let options = {
uri: `${base}${call}`,
method: 'GET',
headers: {
'Authorization': `Basic ${credential}`,
'X-KRN': krn,
}
};
request(options, function(error, response, body) {
// read response
})

Response

요청이 성공하면 다음 결과를 받게됩니다.

{
"nextCursor": "z2o87adeLbW4Aqm53gpq6VbGZg3JmE5vodrwD9XKmY5vMl4Gkw9PZO1NoBpV8LR83y0Edb3Aar7eKQqzJWDg6X2xOe1P27l4kzY0xQa8LNABMWv0VJQ6MpNlr9O1xBDE",
"items": [
{
"fee": 1660500000000000,
"from": "0x60871ee4e48040892e95630ead8ad5fd44d4b34e",
"status": 1,
"timestamp": 1590047290,
"to": "0xce8e5299113ff9cda1694d8af242fd175fcbcbf4",
"transactionHash": "0x44f4fa9304f40392a712cf1e4e925405ecc27269031479c05b149ef39612ef70",
"transactionIndex": 2849691700000000000,
"typeInt": 49,
"value": 100000
},
//...
]
}

Query Param에 따라 위 결과 중 items에 포함되는 거래내역은 최대 10개(size=10)로 제한됩니다.

The Rest of the API Spec

GET /klay/transfer 외에 다른 API에 관한 자세한 정보는 API Specification에서 확인하십시오.