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.

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.

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.

API Request

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}'

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();

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.

API Response

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x5d39"
}

0x5d39;

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.

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}'

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"
);

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.

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.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "accType": 1,
    "account": {
      "nonce": 4,
      "balance": "0x8d286271f52600",
      "humanReadable": false,
      "key": {
        "keyType": 1,
        "key": {}
      }
    }
  }
}

{
    accType: 1,
    account: {
        nonce: 4,
        balance: "0x8d286271f52600",
        humanReadable: false,
        key: { keyType: 1, key: {} }
    }
}

{
  "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:

< {"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.