KAS API

This page introduces API authentication key, pagination, KRN, transaction fee delegation, and SDK for using KAS API.

API Authentication Key

API authentication keys are used to identify API users as KAS members. KAS uses the basic authentication method for authenticating APIs, and an authentication key consists of the authentication ID (AccessKey ID) and authentication password (Secret AccessKey).

//AccessKey ID and Secret AccessKey example
AccessKey ID: `KASKP6ZDZJ9TDH4OE825GB01`
Secret AccessKey: `UDGCqEA2wibbsHFj4VL3vgpltaSh1HvlMRLBauEL`

An API authentication key can be created on KAS Console - Security - Credential menu, and the authentication password (Secret AccessKey) and Authorization can only be checked once upon their creation. Therefore, it is necessary to copy or download Secret AccessKey and Authorization to a safe location for proper and safe management after its creation. Authorization (e.g., Basic S0FTS1A2WkRaSjh...), which can be checked after creating an authentication key, refers to a value encoded using the AccessKey ID and Secret AccessKey through the basic authentication method and used for the call header when calling APIs.

A KAS API Authentication Key (API Auth Key) provides access to all KAS services and all the rights to a Klaytn account which was created by calling Wallet API via this API Auth Key. The rights here include accessing and transferring all the assets (KLAY, etc.) of or sending a transaction from a Klaytn account. If you shared your API Auth Key with any unauthorized personnel, your Klaytn account could be compromised and might cause unwanted transaction execution.

DO NOT share your API Auth Key (Secret AccessKey or Authorization) with any unauthorized personnel. DO PUT efforts necessary to keep your API Auth Key safe for the security of your KAS/Klaytn account.

Authentication keys can be created through the KAS Console - Security - Credential menu. Up to two authentication keys can be created. For replacing an authentication key, delete the existing key first before creating a new one.

Here is an example of calling the KAS API using an authentication key. The authentication key must be inputted on the API call header using either of these methods.

curl

//An example of using AccessKey ID and Secret AccessKey in the API request header
curl --location --request POST "https://wallet-api.klaytnapi.com/v2/account" \
-u ${your_accessKeyId}:${your_secretAccessKey} \
--header "x-chain-id: 1001" \
--header "x-krn: krn:1001:wallet:b73717b4-2bad-4cbe-9517-951ca5af3a15:account-pool:Ray Kim"

//An example of using basic authorization in the API request header
curl --location --request POST "https://wallet-api.klaytnapi.com/v2/account" \
--header "x-chain-id: 1001" \
--header "Authorization: Basic S0FTS0pEVjNBMkpWTlNVVkJTNUlJOU04OlR5cGEwclRrRk1xVUpaSFFOUjdibEIxOStaYVF6ejV1MmZMbXpsS1I="

javascript

// Set chainId and authentication key to be used when using KAS API
caver.initKASAPI(1001, `${your_accessKeyId}`, `${your_secretAccessKey}`)

java

CaverExtKAS caver = new CaverExtKAS();
caver.initKASAPI(1001, your_accessKeyId, your_secretAccessKey);

For details about getting API authentication key, please visit here.

For inquires about this document or KAS, please visit Developer Forum.

Pagination

It can be difficult to import all the data when loading the data by calling the KAS API. For instance, it will be difficult to import all the data at once and access them afterward to search list of all accounts if your application manages thousands of Klaytn accounts. Hence, the API is called several times to load the specified number of data by batch, in which data is generally called by the page. Thus, it is called pagination.

KAS uses cursor-based pagination. The size refers to the number of data used for receiving an API response when a specific KAS API receives query parameters, while cursor is the data offset utilized to continue receipt when the API is called at another time.

Enter the size value when calling the API, and receive the desired number of data. Then, enter the cursor value included in the API response value as the query parameter when calling the API again to continue receiving other incoming data.

Here is an example of receiving an account list by batch with the pagination when calling the search API of Klaytn account list created through KAS.

Query Parameter

Parameter	Description	Example	Required
size	The number of items in the API response (min=1, max=1000, default=100)	size=100	False
cursor	The cursor required to get the next batch of response items	cursor=J9Ag...VM6z	False
to-timestamp	Search range: the last timestamp (sec)	to-timestamp=15921809920	False
from-timestamp	Search range: the first timestamp (sec)	from-timestamp=1592360291	False

The below shows an example of receiving the information of five Klaytn accounts when calling the API.

//API Request
//Request for the list of Klaytn account with the parameters: size=5, to-timestamp=0, from-timestamp=0
curl --location --request GET "https://wallet-api.klaytnapi.com/v2/account?size=5&cursor=&to-timestamp=0&to-timestamp=0" \
--header "x-chain-id: 1001" \
--header "Authorization: Basic S0FTSzEyMVdVQ1RZUldXTkVIU1pQOVRHOmtvZFplUlVybThNZ1gyNUY2VGxVV0NZNDZPSGJHdkgxRklsRnVMK1c="

• Enter 0 in from-timestamp and to-timestamp=, or leave them empty to cover the entire time range.

  • from-timestamp=1599703700 and to-timestamp= is a request to call all data after 1599703700 of the Unix time stamp.

  • from-timestamp= and to-timestamp=1599703700 is a request to call all data before 1599703700 of the Unix time stamp.

//API Response
{"cursor":"eyJBZGR...",
"items":[
  {"address":"0x34260b7096275Ae462D7e4A6680f80C60efAb4F9","chainId":1001,"createdAt":1599699464,"keyId":"krn:1001:wallet:68ec0e4b-0f61-4e6f-ae35-be865ab23187:account-pool:default:0x7432fd7d068cead43306aed3aa611b17413346c3ac737642e4bb2017afbafff1","krn":"krn:1001:wallet:68ec0e4b-0f61-4e6f-ae35-be865ab23187:account-pool:default","publicKey":"0x0425fe8fc3c1640343b4f53c070a34aa43965cb2f9cbc025924d6a77128773f873c100318cdfa6838d56f8f22b56e00d18cc81603acea337f422be60398124e276","updatedAt":1599699464},

  {"address":"0x408222F3c1bC86D8dcD2bE712AaE0237D4121add","chainId":1001,"createdAt":1599624601,"keyId":"krn:1001:wallet:68ec0e4b-0f61-4e6f-ae35-be865ab23187:account-pool:default:0x973b226e6c85383f743004449d330164f3413e0896294aee7bda16804c967167","krn":"krn:1001:wallet:68ec0e4b-0f61-4e6f-ae35-be865ab23187:account-pool:default","publicKey":"0x04e8769ff6c3182185b2cfa960d66a35be5d4a1d235b15e00da9c4e1427bed9cc8c7998932cabe379d01035556349a5cf89aa8b1e12b41dee778f6e52f0e425307","updatedAt":1599624601},

  {"address":"0xB6b2f59CBc670c9BF9d315a7cb4043043CD7050e","chainId":1001,"createdAt":1599624506,"keyId":"krn:1001:wallet:68ec0e4b-0f61-4e6f-ae35-be865ab23187:account-pool:default:0xd174851606b5763d10ce555fc388b633ec2b14d478d169824eefcaa7fc6814c6","krn":"krn:1001:wallet:68ec0e4b-0f61-4e6f-ae35-be865ab23187:account-pool:default","multiSigKeys":[{"publicKey":"0x04e8769ff6c3182185b2cfa960d66a35be5d4a1d235b15e00da9c4e1427bed9cc8c7998932cabe379d01035556349a5cf89aa8b1e12b41dee778f6e52f0e425307","weight":1}],"publicKey":"0x040e66b1d13c0c439cb9158c7f2e58b38aa8f79807ebd2e85e820323419d3948e7fa703187b7ace5ebaa72dd67692e8cd1d79b624a11ee8f2ef410eb03c249563b","threshold":1,"updatedAt":1599624615},

  {"address":"0x80f692366327b7e41Da457d6c18f19c1FEF323B9","chainId":1001,"createdAt":1599562386,"keyId":"krn:1001:wallet:68ec0e4b-0f61-4e6f-ae35-be865ab23187:account-pool:default:0xa1ad3cf3aaa6127f531bce1ff8d338dd9452bbba49514945a70a0099d9ac9a9e","krn":"krn:1001:wallet:68ec0e4b-0f61-4e6f-ae35-be865ab23187:account-pool:default","publicKey":"0x04214bf198bda41ac751fc8240c5a398e008983786d218828d65ede12aca12f60a49188ceb35712bc4b2f12219ba1877b514cd0af6b8d3dd54a6e6801ab2ef41a3","updatedAt":1599562386},

  {"address":"0x01605605C0452e1Df043eeB6367157B02C6b8aC0","chainId":1001,"createdAt":1599550406,"keyId":"krn:1001:wallet:68ec0e4b-0f61-4e6f-ae35-be865ab23187:account-pool:default:0x8e2d4eb20350f99fc0008a2361dcc8a136ef299603a028fb0e06041675acf11e","krn":"krn:1001:wallet:68ec0e4b-0f61-4e6f-ae35-be865ab23187:account-pool:default","publicKey":"0x0411f1667b88fb7742c7caf8c8434167cd5de7e8f7597b8705d8f60bb5d2af1bb45e5d1e1b9b037725fea363e3068a7a54b02a8b96a11f2934d7d86048512711a3","updatedAt":1599550406}
  ]
}

Then, use the cursor value, which has been received in the API response, to receive information of next three accounts from all other remained accounts excluding already-received five.

Here is an example of an API call for requesting information on three accounts.

//API Request
//Request for the list of Klaytn account with the parameters: size=3, cursor=eyJBZGR..., to-timestamp=0, from-timestamp=0
curl --location --request GET "https://wallet-api.klaytnapi.com/v2/account?size=3&cursor=eyJBZGR...&to-timestamp=0&to-timestamp=0" \
--header "x-chain-id: 1001" \
--header "Authorization: Basic S0FTSzEyMVdVQ1RZUldXTkVIU1pQOVRHOmtvZFplUlVybThNZ1gyNUY2VGxVV0NZNDZPSGJHdkgxRklsRnVMK1c="

//API Response
{"cursor":"eyJBZGR...",
"items":[
  {"address":"0xddFCd7fB9B2988600aD7EfAeE85BE848E236FDf6","chainId":1001,"createdAt":1599208594,"keyId":"krn:1001:wallet:68ec0e4b-0f61-4e6f-ae35-be865ab23187:account-pool:default:0x4ef5082037adc03a330d6469ffdaaeef193b48afac378e24ae992632bcaacb87","krn":"krn:1001:wallet:68ec0e4b-0f61-4e6f-ae35-be865ab23187:account-pool:default","multiSigKeys":[{"publicKey":"0x0420eafec3c250b10245918844520912cd751c12c00d6e4623bc84b9810dda2edd670dcc6051a8cc4b332adc4f3a36aeb2f6d3cae5ccbb6e90aae76aa7c24ce6ba","weight":3},{"publicKey":"0x04ba8182c1c3f2c07e43ba7ef20f23f5af6823156c35e51780fe71e79d228c2882c35e111a3b05db5d151ebfe8453fcca2c9990088c96dfded7026ee9715454fba","weight":1}],"publicKey":"0x04ba8182c1c3f2c07e43ba7ef20f23f5af6823156c35e51780fe71e79d228c2882c35e111a3b05db5d151ebfe8453fcca2c9990088c96dfded7026ee9715454fba","threshold":4,"updatedAt":1599208600},

  {"address":"0xD299765ECF82dB95b2F6441Fcb3a237A9C33c4f0","chainId":1001,"createdAt":1599208593,"keyId":"krn:1001:wallet:68ec0e4b-0f61-4e6f-ae35-be865ab23187:account-pool:default:0xfbaa7735188691a29b56138f2a558a2b1078b6ca46a3a46c5245b68b24c54214","krn":"krn:1001:wallet:68ec0e4b-0f61-4e6f-ae35-be865ab23187:account-pool:default","publicKey":"0x0420eafec3c250b10245918844520912cd751c12c00d6e4623bc84b9810dda2edd670dcc6051a8cc4b332adc4f3a36aeb2f6d3cae5ccbb6e90aae76aa7c24ce6ba","updatedAt":1599208593},

  {"address":"0x72ef9D552A3AFa610Ec09B5fC24fef29EF6881a6","chainId":1001,"createdAt":1599208592,"keyId":"krn:1001:wallet:68ec0e4b-0f61-4e6f-ae35-be865ab23187:account-pool:default:0x8b513e031e15a504c2e18196624b72f51133462e1276b2738a46db3a8b91bbee","krn":"krn:1001:wallet:68ec0e4b-0f61-4e6f-ae35-be865ab23187:account-pool:default","publicKey":"0x047bcbd531e8598afdf749fe2475c8793c27681dd310074c346382f239a646d3778ab5f8ea4da7094551e3a8e548da560641445889311fa67563ab1416248582be","updatedAt":1599208592}
  ]
}

• If you set size less than the total number of response items, cursor is included in the response.

• If you get all data at once, cursor in the response is empty value.

As above, you can change size as the number of data you want to receive, change cursor as you receive a new value of it from the response, and call API again via using the updated size or cursor value to split the number of items in the response.

For inquires about this document or KAS, please visit Developer Forum.

KRN

KRN (KAS Resource Name) is a unique value for identifying all KAS resources. In KAS, these resources refer to all KAS resources (preset, account, fee-payer account, etc.) that you use. When you access a certain KAS resource, KAS internally uses KRN.

One of most frequently accessed KAS resources is account pool, which holds your Klaytn accounts. If you want to use a Klaytn account only with specific preferred account pool when calling the KAS API, you need to enter the KRN value of this pool on the API request header.

KRN Example

KRN has the following format:

krn:{chain-id}:{service-name}:{account-id}:{resource-type}:{resource-id}

Item	Description	Note
chain-id	ID of the chain that owns this resource	8217 (Klaytn mainnet) or 1001 (Klaytn testnet)
service-name	The name of the service offered via this resource	node, th, wallet, anchor
account-id	The identifier of KAS account
resource-type	Resource type	Types differ by service
resource-id	The identifier of the resource

//KRN example for Klaytn account pool
krn:1001:wallet:6698d79e-78ee-439a-815d-f293ec6ae736:account-pool:RayKim

The above is an example of a KRN value. In krn:1001, 1001 pertains to the chain ID (Klaytn testnet, Baobab). Toward the last part, RayKim is the name of the account pool that you created. A Klaytn account that utilizes the default account pool of KAS may also be made, and the name of the account pool will be set to default.

You can send transactions to Klaytn using the KAS API. Here, you can select a specific account pool and send transactions to accounts therein. To select a specific account in a specific account pool and send transactions using the KAS API, you must input the pool's KRN value.

curl --location --request POST "https://wallet-api.klaytnapi.com/v2/tx/value" \
-u ${your_accessKeyId}:${your_secretAccessKey} \
--header "x-chain-id: 1001" \
--header "x-krn: krn:1001:wallet:b73717b4-2bad-4cbe-9517-951ca5af3a15:account-pool:RayKim"
--header "Content-Type: application/json" \
--data-raw "{
  "from": "0x5bb85d4032354E88020595AFAFC081C24098202e",
  "value": "0x100",
  "to": "0x2F87Ba64de5526F7880F21481Effbf950f70005c",
  "memo": "memo",
  "nonce": 0,
  "gasLimit": 1000000,
  "submit": true
}"

The API call above will send 0x100 peb (unit of KLAY) from the account (EOA) 0x5bb85d4032354E88020595AFAFC081C24098202e in the RayKim account pool to the account 0x2F87Ba64de5526F7880F21481Effbf950f70005c.

For inquires about this document or KAS, please visit Developer Forum.

Transaction Fee Delegation

KAS offers two transaction fee delegation methods.

Using UserFeePayer

You may create a fee-payer account and pay the transaction fee using this account when your other account sends transactions to Klaytn through KAS. When calling an API to send transactions to Klaytn, enter your fee-payer account address in the fee_payer parameter.

The fee-payer account for KAS must also be created on the KAS Console. Any fee-payer account not created in KAS will not be managed in KAS.

For details about creating fee-payer account in KAS Console, please visit here.

Using GlobalFeePayer

KAS pays for transaction fees first and charges it to your KAS account later. With GlobalFeePayer, you can send fee-delegated transactions without opening and preparing a transaction fee-payer account and KLAY.

Do not put the fee_payer parameter itself when calling the API for sending fee-delegated transactions. KAS charges transaction fees to your KAS account later.

For details about creating fee-payer account in KAS Console, please visit here.

For inquires about this document or KAS, please visit Developer Forum.

SDK

KAS SDK (Software Development Kit) is a development tool provided to easily use KAS in various development environments. KAS SDK is an extension library of Caver and supports JavaScript and Java environment like Caver. If you develop BApp with KAS SDK, you can use both KAS function and existing Caver function through a single library.

KAS SDK (caver-js extension) and KAS SDK (caver-java extension) are the extension libraries of caver-js and caver-java, respectively. You can use KAS Node API, TokenHistory API, Wallet API, and Anchor API in your javascript/java environment via KAS SDK, along with the existing caver-js/caver-java functions.

For more information about KAS SDK, refer to here.

KAS API Error Codes

Please visit the below sites for KAS API error codes:

• Klaytn Node API Reference

• Token History API Reference

• Wallet API Reference

• Anchor API Reference

For inquires about this document or KAS, please visit Developer Forum.