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