JSON-RPC 호출

JSON-RPC는 무상태, 경량 RPC(원격 프로시저 호출) 프로토콜로, HTTP 뿐 아니라 TCP, WebSocket 등을 통해 실행될 수 있습니다. JSON을 데이터 형식으로 사용합니다.

튜토리얼에 앞서

  • API 호출에 사용되는 x-chain-id 값은 8217 (Mainnet) 또는 1001 (Kairos)입니다.
  • API 호출에 필요한 필수 파라미터는 각 예시에 설명됩니다.

API 호출 시 사용자가 입력해야 하는 값은 중괄호 1개({})로 표시합니다. 사용자가 입력해야 하는 값은 아래 테이블과 같습니다.

항목 값 비고
chain-id 8217 또는 1001 Kaia 메인넷 또는 Kairos
access-key-id 인증 아이디 KAS Console > [Security] > [Credential]에서 발급받은 accessKeyId
secret-access-key 인증 비밀번호 KAS Console > [Security] > [Credential]에서 발급받은 secretAccessKey
krn (optional) 계정 저장소의 ID 기본 계정 저장소 사용 시 불필요

API 인증 키가 있으면 모든 KAS 서비스를 사용할 수 있으며 Wallet API를 호출해 만든 Kaia 계정에 대한 모든 권한을 소유합니다. 모든 권한에는 Kaia 계정의 자산(KAIA 등) 이동이나 트랜잭션 전송 및 실행 권한이 포함됩니다. 만약 API 인증 키에 타인이 접근한다면 Kaia 계정 권한을 탈취당해 원치 않는 트랜잭션이 발생할 수 있습니다.

danger

KAS/Kaia 계정 보안을 위해 KAS API 인증 키(Secret Access Key)를 타인과 함부로 공유하지 말고 주의해 관리하십시오.

info

KAS SDK(caver-js/caver-java extension) 설치, 실행에 관한 자세한 내용은 KAS SDK를 확인하십시오.
Kaia Node에서 Kaia 계정 정보를 확인하려면 계정 저장소와 계정을 생성하고 사용할 계정을 선택해야 합니다.
계정 저장소 생성, 계정 생성, 계정 선택에 관한 자세한 내용은 Getting Started를 확인하십시오.

이 예제에서는 Kaia 계정 관리를 위한 API 몇 가지를 호출해보고 웹소켓 사용에 대해 설명하겠습니다.

가장 최근에 생성된 블록 번호 확인

Node API로 여러분 계정의 잔고, 계정 키 타입 등 계정에 관한 가장 최신 정보를 확인하려면 Kaia상에 있는 가장 최신 블록의 블록 번호를 알아야합니다. 이를 위해 JSON-RPC 요청 { "method": "klay_blockNumber", "id": 1 }을 보내고 최신의 블록 번호를 요청합니다.

info

Node API에 관한 더 자세한 내용은 다음을 확인하십시오.

API 호출

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 는 임의의 값입니다.
  • params , jsonrpc 는 생략 가능합니다.
info

API 호출에 관한 더 자세한 내용은 다음을 확인하십시오.

API 응답

API가 성공적으로 실행되면 다음과 같은 응답을 받습니다.

cURLJavaScriptJava
Copy
Copied
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x5d39"
}
Copy
Copied
0x5d39;
Copy
Copied
0x5d39
  • result 는 16진수로 표현된 블록 번호값입니다.

Kaia JSON-RPC API에 관한 더 자세한 내용은 다음을 확인하십시오.
이 API에 관한 자세한 내용은 다음을 확인하십시오.
이 문서 혹은 KAS에 관한 문의는 개발자 포럼을 방문해 도움 받으십시오.

EOA로 Kaia 계정 정보 확인

API 호출

블록 번호와 Kaia 계정 주소(EOA)를 입력하고 계정 정보를 조회하는 JSON-RPC 함수 klay_getAccount를 실행합니다. klay_getAccount는 주소(필수)와 블록번호/태그(필수 또는 선택) 파라미터를 받습니다. curl 등 HTTP 방식으로 직접 RPC를 호출할 경우 블록번호/태그는 필수 파라미터입니다.

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 Kairos; 8217 if Kaia Mainnet

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 는 임의의 값입니다.
  • jsonrpc 는 생략 가능합니다.
  • Kaia 계정 주소값 0x3111a0577f322e8fb54f78d9982a26ae7ca0f722 은 예시값입니다.
  • SDK(caver-js, caver-java)는 구현에 따라 블록번호/태그를 생략 가능합니다. 이 경우 "latest" 태그가 사용됩니다.
info

API 호출에 관한 더 자세한 내용은 다음을 확인하십시오.

warning

Node API는 매번 다른 Kaia 엔드포인트 노드를 호출하며 블록 번호에 pending을 입력할 경우 결과값이 기대와 다를 수 있습니다.

API 응답

API가 성공적으로 실행되면 다음과 같이 입력한 EOA를 가지고 있는 Kaia 계정 정보를 나타내는 응답을 받습니다.

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
}

Kaia JSON-RPC API에 관한 더 자세한 내용은 다음을 확인하십시오.
이 API에 관한 자세한 내용은 다음을 확인하십시오.
이 문서 혹은 KAS에 관한 문의는 개발자 포럼을 방문해 도움 받으십시오.

WebSocket 연결

WebSocket을 사용하면 특정 데이터를 얻기 위해 반복해서 요청을 할 필요없이 갱신된 결과를 받아올 수 있습니다. wscat과 같은 WebSocket 커맨드라인 툴을 설치해 사용해보세요.

WebSocket 연결을 위해서는 다음과 같이 요청을 보냅니다.

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

각 부분에 대한 설명은 다음과 같습니다:

  • {accessKeyId}와 {secretAccessKey}: API를 호출하는 주체가 KAS 회원이 맞는지 증명하는 API 인증 키입니다.
  • node-api.klaytnapi.com: Node API의 기본 URL입니다.
  • v1/ws/open: WebSocket 연결을 위한 엔드포인트입니다.
  • chain-id: 쿼리 파라미터로 전달되는 chain ID로, Kairos는 1001, Kaia Mainnet은 8217입니다.

구독 API - klay_subscribe

WebSocket에 연결되었을 때 유의미하게 사용할 수 있는 것은 구독형(Subscription) API들로, 특정 이벤트를 감지하면서 새로운 데이터를 즉시 반환합니다. Kaia의 경우 대표적으로 klay_subscribe가 있습니다.

klay_subscribe를 사용하면 특정 이벤트에 대한 구독을 생성합니다.

파라미터는 newHeads 또는 logs로, newHeads는 블록체인에 새로운 블록이 추가될 때마다 알림을 보내며, logs는 새 블록에 추가된 로그들을 반환합니다.

요청 예시는 다음과 같습니다.

Copy
Copied
wscat -c http://localhost:8552

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

응답은 아래와 같습니다.

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

KAS에서 현재 지원하는 Node API 목록

위에서 안내한 방식으로 Kaia의 다른 JSON-RPC API도 KAS에서 호출할 수 있습니다. 단, 현재 KAS는 일부 Node API만을 지원합니다. 사용할 수 있는 RPC 메소드는 KAS Console Service > Node 페이지에서 확인하실 수 있습니다.

이 API에 관한 자세한 내용은 다음을 확인하십시오. 이 문서 혹은 KAS에 관한 문의는 개발자 포럼을 방문해 도움 받으십시오.