JSON-RPC is a stateless, lightweight remote procedure call (RPC) protocol that can execute JSON-formatted data over HTTP, TCP, WebSocket, etc.

Before Getting Started

  • The x-chain-id value for calling the API is 8217 (Cypress) or 1001 (Baobab).
  • Essential parameters for calling APIs are described in individual examples.

Values that a user needs to enter for calling APIs will be represented with one pair of braces ({}). A user must enter the following values.

Item Description Note
chain-id 8217 or 1001 Cypress (Klaytn mainnet) or Baobab (Klaytn testnet)
access-key-id Auth ID accessKeyId obtained from KAS Console > Security > Credential
secret-access-key Auth Password secretAccessKey obtained from KAS Console > Security > Credential
krn (optional) ID of Account Pool Unnecessary when using Default Account Pool

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.

danger

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.

info

For details about KAS SDK (caver-js/caver-java extension) installation and execution, please visit KAS SDK. To check Klaytn account information through Klaytn Node, create an Account Pool and select an account to use. For more details on creating an Account Pool, account, and selecting an account, refer to Getting Started.

The following example calls some APIs for Klaytn account management and explains the use of WebSocket.

Check the Block Number of the Most Recent Block

The block number of the latest block on Klaytn is required for checking the account balance, key type, and other recent information on the account using Node API. To this end, a user must send the JSON-RPC request { "method": "klay_blockNumber", "id": 1 } for the latest block number.

info

For more details about Node API, please visit here.

API Request

cURLJavaScriptJava
Copy
Copied
curl --location --request POST 'https://node-api.klaytnapi.com/v1/klaytn' \
    -u {accessKeyId}:{secretAccessKey} \
    --header 'x-chain-id: {chain-id}' \
    --header 'Content-Type: application/json' \
    --data-raw '{"jsonrpc":"2.0","method":"klay_blockNumber","params":[],"id":1}'
Copy
Copied
const accessKeyId = "{accessKeyId}";
const secretAccessKey = "{secretAccessKey}";
const chainId = 1001;

const caver = new CaverExtKAS();
caver.initKASAPI(chainId, accessKeyId, secretAccessKey);
const blockNumber = await caver.rpc.klay.getBlockNumber();
Copy
Copied
String accessKey = "your accessKey";
String secretAccessKey = "your secret accessKey";

CaverExtKAS caver = new CaverExtKAS();
caver.initKASAPI(1001, accessKey, secretAccessKey);

Quantity response = caver.rpc.klay.getBlockNumber().send();
System.out.println(response.getValue());
/* call an appropriate method via caver.rpc */
  • id is a random value.
  • params and jsonrpc can be omitted.
info

For more details about API Request, please visit here.

API Response

The following response will be received if the API is successfully executed.

cURLJavaScriptJava
Copy
Copied
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x5d39"
}
Copy
Copied
0x5d39;
Copy
Copied
0x5d39
  • result is a block number value represented in hexadecimal.

For more details about Klaytn JSON-RPC API, please visit here. For details about this API, please visit here. For inquiries about this document or KAS, please visit KAS Developers Forum.

Get Klaytn account Information by EOA

API Request

Enter the block number and Klaytn EOA, and then, execute the JSON-RPC function, klay_getAccount, to search for account information. klay_getAccount then receives the address (required) and block number/tag (required or optional) parameters. The block number and tag parameters are needed if RPC is directly called through curl or other HTTP methods.

cURLJavaScriptJava
Copy
Copied
curl --location --request POST 'https://node-api.klaytnapi.com/v1/klaytn' \
    -u {accessKeyId}:{secretAccessKey} \
    --header 'x-chain-id: {chain-id}' \
    --header 'Content-Type: application/json' \
    --data-raw '{"jsonrpc":"2.0","method":"klay_getAccount","params":["0x3111a0577f322e8fb54f78d9982a26ae7ca0f722", "0x5d39"],"id":1}'
Copy
Copied
const accessKeyId = "{accessKeyId}";
const secretAccessKey = "{secretAccessKey}";
const chainId = 1001; // for Baobab; 8217 if Cypress

const caver = new CaverExtKAS();
caver.initKASAPI(chainId, accessKeyId, secretAccessKey);
const account = await caver.rpc.klay.getAccount(
  "0x3111a0577f322e8fb54f78d9982a26ae7ca0f722"
);
Copy
Copied
String accessKey = "your accessKey";
String secretAccessKey = "your secret accessKey";

CaverExtKAS caver = new CaverExtKAS();
caver.initKASAPI(1001, accessKey, secretAccessKey); // for Baobab; 8217 if Cypress

Account res = caver.rpc.klay.getAccount("0x3111a0577f322e8fb54f78d9982a26ae7ca0f722").send();
  • id is a random value.
  • jsonrpc can be omitted.
  • This is an example of Klaytn account address value: 0x3111a0577f322e8fb54f78d9982a26ae7ca0f722 .
  • According to the implementation of SDK (caver-js, caver-java), the block number/tag can be omitted. Here, the "latest" tag is used.
info

For more details about API Request, please visit here.

warning

Node API calls different Klaytn endpoint nodes each time, and the result value may be unexpected if pending is entered as the block number.

API Response

Once the API is successfully executed, the user will receive a response regarding the information of the Klaytn account that entered the EOA.

cURLJavaScriptJava
Copy
Copied
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "accType": 1,
    "account": {
      "nonce": 4,
      "balance": "0x8d286271f52600",
      "humanReadable": false,
      "key": {
        "keyType": 1,
        "key": {}
      }
    }
  }
}
Copy
Copied
{
    accType: 1,
    account: {
        nonce: 4,
        balance: "0x8d286271f52600",
        humanReadable: false,
        key: { keyType: 1, key: {} }
    }
}
Copy
Copied
{
  "id" : 15,
  "jsonrpc" : "2.0",
  "result" : {
    "accType" : 1,
    "account" : {
      "balance" : "0xc9072392f9847c64f37",
      "humanReadable" : false,
      "key" : {
        "type" : "0x01",
        "accountKey" : {
          "keyType" : 1,
          "key" : { }
        }
      },
      "nonce" : "18377",
      "type" : "EOA"
    }
  },
  "error" : null,
  "rawResponse" : null
}

For more details about Klaytn JSON-RPC API, please visit here. For details about this API, please visit here. For inquiries about this document or KAS, please visit KAS Developers Forum.

Connecting WebSocket

WebSocket helps you get the updated result without making repeated requests to get specific data. Try to install a WebSocket command line tool, wscat.

Request as follows for WebSocket connection.

wscat -c wss://{accessKeyId}:{secretAccessKey}@node-api.klaytnapi.com/v1/ws/open?chain-id=1001

Each part is explained as follows:

  • {accessKeyId} and {secretAccessKey}: Authentication key to verify membership of the API caller.
  • node-api.klaytnapi.com: Defaulf URL for Node API.
  • v1/ws/open: The endpoint connecting to WebSocket.
  • chain-id: Query parameter type; 1001 (Baobab) or 8217 (Cypress).

Subscription API - klay_subscribe

When connected to a WebSocket, Subscription APIs detect certain events and return new data immediately. In the case of Klaytn, a representative example is klay_subscribe.

Create a new subscription to specific events by using klay_subscribe.

Notification parameter type is newHeads or logs. newHeads notifies you of each block added to the blockchain. logs notifies you of logs included in new blocks.

The request sample is as follows:

wscat -c http://localhost:8552

{"jsonrpc":"2.0", "id": 1, "method": "klay_subscribe", "params": ["newHeads"]}

The response is shown below:

Copy
Copied
< {"jsonrpc":"2.0","id":1,"result":"0xee42e843560a107c80fc7b241bb99e2a"}
< {"jsonrpc":"2.0","method":"klay_subscription","params":{"subscription":"0xee42e843560a107c80fc7b241bb99e2a","result":{"parentHash":"0xb76aeee0d9cfd831be70c02ca00007debf2dfd0be511ddcf3230f9a9aaca7226","reward":"0xa86fd667c6a340c53cc5d796ba84dbe1f29cb2f7","stateRoot":"0xb249cabfea3601ee1f7aed542472510b0ffc495f964d227ca15190de6e5f9f1b","transactionsRoot":"0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470","receiptsRoot":"0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470","logsBloom":"0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000","blockScore":"0x1","number":"0x48c9863","gasUsed":"0x0","timestamp":"0x61a0392b","timestampFoS":"0x0","extraData":"0xd883010701846b6c617988676f312e31352e37856c696e757800000000000000f90164f85494571e53df607be97431a5bbefca1dffe5aef56f4d945cb1a7dccbd0dc446e3640898ede8820368554c89499fb17d324fa0e07f23b49d09028ac0919414db694b74ff9dea397fe9e231df545eb53fe2adf776cb2b841e69d51d827d04525c987b830666a2b901f5146fc89c6de0b053eda4b6ad843b50d74f7c71da7b1b0d912d230d04261d1132284ed0fc387794d669840afd4f01701f8c9b8412b84c3d3fcb6feed9ab4b089100b0fbdc0b7ac30306fc970fb7138b67d91ed3f7d6c2c3dd54c96257fdf2a1d0c89b46b9f13d7dd83a9f13f4c2524929485949500b841b72857a0912464986478ccce5fce5120bb84ce3e605e6867bf3140aee39dea821be908cf96b493e56cfdf70909e92ff26f953d9c558a6e8cd77867fce649129100b841462dc63b59d0026bbeac2c0543985a5aa168a69a669a7b9b92df342d63338cf80c032d06e93a1fae901824848f8d771e1635da9870a8f0e01ac4ab9194b8f8b801","governanceData":"0x","hash":"0x64ed8c397ed938d4f3134bc8ff3de1793534d2d4039e1c817941152a2bcc4d90"}}}
< {"jsonrpc":"2.0","method":"klay_subscription","params":{"subscription":"0xee42e843560a107c80fc7b241bb99e2a","result":{"parentHash":"0x64ed8c397ed938d4f3134bc8ff3de1793534d2d4039e1c817941152a2bcc4d90","reward":"0xa86fd667c6a340c53cc5d796ba84dbe1f29cb2f7","stateRoot":"0x12c5511da5f3de8d0a528ffc34b3dcd24351ad8f0af7f6a84bba4896c7cb0156","transactionsRoot":"0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470","receiptsRoot":"0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470","logsBloom":"0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000","blockScore":"0x1","number":"0x48c9864","gasUsed":"0x0","timestamp":"0x61a0392c","timestampFoS":"0x0","extraData":"0xd883010701846b6c617988676f312e31352e37856c696e757800000000000000f90164f85494571e53df607be97431a5bbefca1dffe5aef56f4d945cb1a7dccbd0dc446e3640898ede8820368554c89499fb17d324fa0e07f23b49d09028ac0919414db694b74ff9dea397fe9e231df545eb53fe2adf776cb2b8418ef714aa58e3953b5fbfb11c6b4c8aa8959193109d38f18d2dbdf95a582b515f6050641cbc719507346fee59ed4d1cacfd314a1e04f4f216c92469e8c57135b501f8c9b841f6095016c67bfdd7ef688dcfcc4bac24e13e436a217567146a8bc672c0a80074109e742f6583a9fa6d4a1443972859fab817a0cfefabd63a0171c2d85490e45b00b84197da6c03d252aad50d926aba2302c694b18b054374737696bc47f4ae70f1a7d320fbb1f14e213c0e1f0d2f20ea634b73b3459dc5c315761bff4e8bc952cec89a01b84167fd68b3df42a86f12167bac56f283e02500ba6ff805a0083b94a2b40272a8673ab958563dbdf832ce5df79459f843868db1fe37b2bb97d7c967babb9ab54f4801","governanceData":"0x","hash":"0x5ac45a79fc99cbc4ae726775735547b7b6c5d8f5dbf229c8cbfe90a21ff5e98b"}}} ...

List of Node API KAS Currently Supports

Other JSON-RPC APIs of Klaytn can be called through KAS using the same process. However, KAS only supports a few Node APIs currently. You can find the list of available RPC methods in KAS Console Service > Klaytn Node.

For more details regarding this API, please refer to here. For any inquiries regarding this document or KAS in general, please visit KAS Developers Forum.