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 Kaia account which was created by calling Wallet API via this API Auth Key. The rights here include accessing and transferring all the assets (KAIA, etc.) of or sending a transaction from a Kaia account. If you shared your API Auth Key with any unauthorized personnel, your Kaia account could be compromised and might cause unwanted transaction execution.

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.

//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="

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

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

For inquires about this document or KAS, please visit KAS Developers 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 Kaia 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 Kaia account list created through KAS.

Query Parameter

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 KAS Developers 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 Kaia accounts. If you want to use a Kaia 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 has the following format:

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

//KRN example for Kaia 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 (Kaia Testnet, Kairos). Toward the last part, RayKim is the name of the account pool that you created. A Kaia 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 Kaia 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 kei (unit of KAIA) from the account (EOA) 0x5bb85d4032354E88020595AFAFC081C24098202e in the RayKim account pool to the account 0x2F87Ba64de5526F7880F21481Effbf950f70005c.

For inquires about this document or KAS, please visit KAS Developers 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 Kaia through KAS. When calling an API to send transactions to Kaia, enter your fee-payer account address in the fee_payer parameter.

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 KAIA.

For inquires about this document or KAS, please visit KAS Developers 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 DApp 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:

• Node API Reference
• Token History API Reference
• Wallet API Reference
• Anchor API Reference

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