API 인증 키

API 인증 키는 API 사용자가 KAS 회원 본인이 맞는지 증명하기 위해 사용합니다. KAS에서 API 인증은 HTTP Basic 인증 방식을 사용하며 인증 키는 인증 ID(AccessKey ID)와 인증 비밀번호(Secret AccessKey)로 구성됩니다.

//AccessKey ID와 Secret AccessKey 예시
AccessKey ID: `KASKP6ZDZJ9TDH4OE825GB01`
Secret AccessKey: `UDGCqEA2wibbsHFj4VL3vgpltaSh1HvlMRLBauEL`

API 인증 키는 KAS Console > [Security] > [Credential] 메뉴에서 발급받으며, 인증 비밀번호인 Secret AccessKey와 Authorization은 최초 생성 시 한 번만 확인할 수 있습니다. 따라서, 최초 생성 시 반드시 Secret AccessKey와 Authorization을 안전한 곳에 복사 또는 다운로드해 관리해야 합니다. 인증 키 생성시 확인할 수 있는 Authorization (예: Basic S0FTS1A2WkRaSjh...)은 Basic 인증 방식을 이용하여 AccessKey ID와 Secret AccessKey를 인코딩한 값이며 API 호출 시 호출 헤더에 사용합니다.

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

아래는 인증 키를 사용해 KAS API를 호출하는 예시입니다. 인증 키를 API 호출 헤더에 입력해야 하며 입력하는 방식은 아래와 같이 크게 2가지가 있습니다.

//AccessKey ID와 Secret AccessKey로 API 호출 헤더를 구성한 예시
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"

//Basic Authorization으로 API 호출 헤더를 구성한 예시
curl --location --request POST "https://wallet-api.klaytnapi.com/v2/account" \
--header "x-chain-id: 1001" \
--header "Authorization: Basic S0FTS0pEVjNBMkpWTlNVVkJTNUlJOU04OlR5cGEwclRrRk1xVUpaSFFOUjdibEIxOStaYVF6ejV1MmZMbXpsS1I="

// KAS API를 사용할 때에 사용할 chainId와 인증 키를 세팅
caver.initKASAPI(1001, `${your_accessKeyId}`, `${your_secretAccessKey}`);

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

이 문서 혹은 KAS에 관한 문의는 개발자 포럼을 방문해 도움 받으십시오.

페이지네이션

KAS API를 호출해 데이터를 불러올 때 모든 데이터를 한 번에 가져오기 어려울 때가 있습니다. 예를 들어, 여러분의 애플리케이션이 수천 개의 Klaytn 계정을 관리할 때 모든 계정 목록을 조회하려면 데이터를 한 번에 가져오기 어렵고 가져와도 데이터에 접근하기 불편합니다. 따라서, API를 여러 번 호출하여 지정된 개수만큼 데이터를 분할하여 불러오는데, 보통 데이터를 페이지 단위로 나눠 불러오기 때문에 이를 페이지네이션(Pagination)이라고 합니다.

KAS는 커서(Cursor) 기반 페이지네이션을 사용합니다. 어떤 KAS API가 쿼리 파라미터를 받을 때 size는 API 응답으로 받을 데이터 개수, cursor는 다음번 API 호출 시 이어서 받고 싶은 데이터 위치(offset)입니다.

먼저 API를 호출할 때 size를 입력하고 원하는 개수만큼 데이터를 받습니다. 그리고 API 응답값에 포함된 cursor값을 API를 다시 호출할 때 쿼리 파라미터로 입력하면 방금 받은 데이터 이후의 데이터를 이어 받을 수 있습니다.

다음은 여러분의 KAS에서 생성했던 Klaytn 계정 목록을 조회하는 API를 호출 시 페이지네이션을 사용해 계정 목록을 나누어 받는 예시를 소개합니다.

쿼리 파라미터(Query Parameter) | 파라미터 이름 | 설명 | 예시 | 필수 | |-|-|-|-| | size | 응답 아이템 개수(min=1, max=1000, default=100) | size=100 | False | | cursor | 페이지네이션으로 다음 요청을 보낼 때 필요한 커서 | cursor=J9Ag...VM6z | False | | to-timestamp | 검색 범위: 마지막 시간의 타임스탬프(초단위) | to-timestamp=15921809920 | False | | from-timestamp | 검색 범위: 시작 시간의 타임스탬프(초단위) | from-timestamp=1592360291 | False |

아래는 API 1회 호출 시 Klaytn 계정 정보를 5개씩 나누어 받는 예시입니다.

//API 호출
//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="

• from-timestamp , to-timestamp 에 0을 입력하거나 값을 입력하지 않으면 모든 시간 범위를 포함합니다.
  • from-timestamp=1599703700 , to-timestamp= 은 Unix 타임스탬프 기준으로 "1599703700" 이후의 모든 데이터를 불러오는 요청입니다.
  • from-timestamp= , to-timestamp=1599703700 은 Unix 타임스탬프 기준으로 "1599703700" 이전의 모든 데이터를 불러오는 요청입니다.

//API 응답
{"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}
  ]
}

이제, API 응답으로 받은 cursor값을 사용해, 방금 받은 5개를 제외한 나머지 계정 정보들 중 3개만을 받습니다. 다음은 3개 계정 정보를 요청하는 API 호출 예시입니다.

//API 호출
//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 응답
{"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}
  ]
}

• size 를 불러올 수 있는 전체 데이터 개수보다 적게 설정하면 cursor 를 응답값으로 받습니다.
• 모든 데이터를 한 번에 다 받을 때 응답값의 cursor 는 빈 값입니다.

위와 같이, 받고 싶은 데이터 개수만큼 size 값을 바꾸고 cursor 값을 직전 응답값에서 받은 값으로 갱신해 API를 다시 호출하는 방식으로 데이터를 나눠 받을 수 있습니다.

이 문서 혹은 KAS에 관한 문의는 개발자 포럼을 방문해 도움 받으십시오.

KRN

KRN (KAS Resource Name)은 KAS 모든 리소스를 식별하기 위한 고유한 값입니다. KAS에서 리소스란 여러분이 실제로 사용하려는 KAS 서비스에서 사용하는 자원(Preset, 계정, 수수료 대납 계정 등)을 의미합니다. 따라서 KAS는 내부적으로 여러분이 어떤 KAS 리소스에 접근하려고 할 때 KRN을 사용합니다.

KAS를 사용할 때 가장 빈번하게 접근하는 KAS 리소스 중 하나는 계정 저장소입니다. 여러분의 Klaytn 계정은 계정 저장소에 저장되어 있는데, KAS API를 호출할 때 특정 저장소에 있는 Klaytn 계정만을 사용하려면 반드시 이 저장소의 KRN값을 API 호출 헤더에 사용하셔야 합니다.

KRN 값은 아래 포맷으로 구성됩니다.

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

//Klaytn 계정 저장소의 KRN 값 예시
krn:1001:wallet:6698d79e-78ee-439a-815d-f293ec6ae736:account-pool:RayKim

위 값은 KRN의 예시값입니다. krn:1001에서 1001은 체인 ID를 의미하며 여기서는 Klaytn 테스트넷인 Baobab을 의미합니다. 맨 마지막에 위치한 RayKim은 여러분이 만든 계정 저장소의 이름입니다. 여러분 자신만의 계정 저장소를 만들지 않고 KAS에서 기본 제공하는 계정 저장소에 Klaytn 계정을 만들 수도 있습니다. 이 때에는 계정 저장소 이름이 default가 됩니다.

여러분은 KAS API로 Klaytn에 트랜잭션을 보낼 수 있습니다. 이 때 특정 계정 저장소를 선택하고 이 저장소에 있는 계정으로 트랜잭션을 보낼 수 있습니다. 이렇게 특정 저장소의 특정 계정을 선택한 후 KAS API로 트랜잭션을 보내려면 이 저장소의 KRN값이 필요합니다.

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

위 API를 호출하면 RayKim이라는 계정 저장소에 있는 계정들 중에서 0x5bb85d4032354E88020595AFAFC081C24098202e라는 주소(EOA)를 가진 계정이 0x100만큼의 KLAY (단위:peb)를 0x2F87Ba64de5526F7880F21481Effbf950f70005c에게 전송합니다.

이 문서 혹은 KAS에 관한 문의는 개발자 포럼을 방문해 도움 받으십시오.

트랜잭션 전송 수수료 대납

KAS에서 제공하는 트랜잭션 전송 수수료 대납 방식은 2가지입니다.

UserFeePayer 사용

여러분의 수수료 대납 계정을 만들어서, 여러분의 다른 계정이 KAS로 Klaytn에 트랜잭션을 보낼 때 이 대납 계정으로 트랜잭션 수수료를 대신 납부하는 방식입니다. Klaytn에 트랜잭션을 전송하는 API를 호출할 때, feePayer 파라미터에 여러분이 준비한 대납 계정 주소를 입력합니다.

GlobalFeePayer 사용

KAS에서 여러분의 트랜잭션 수수료를 대신 납부하고, 추후 이 수수료만큼의 비용을 여러분 KAS 계정에 청구합니다. GlobalFeePayer란 KAS에서 제공하는 대납 계정이며 GlobalFeePayer를 사용하면 여러분이 트랜잭션 수수료 대납 계정과 수수료로 사용할 KLAY를 준비하지 않아도 수수료 대납 트랜잭션을 전송할 수 있습니다.

이 문서 혹은 KAS에 관한 문의는 개발자 포럼을 방문해 도움 받으십시오.

SDK

KAS SDK(Software Development Kit)는 여러 개발 환경에서 KAS를 쉽게 사용하도록 제공되는 개발 도구입니다. KAS SDK는 Caver의 확장 라이브러리이며 Caver와 마찬가지로 JavaScript와 Java 환경을 지원합니다. KAS SDK로 BApp을 개발하면 하나의 라이브러리를 통해 KAS 기능과 기존 Caver의 기능을 모두 사용할 수 있습니다.

KAS SDK(caver-js extension)와 KAS SDK(caver-java extension)는 각각 caver-js와 caver-java의 확장 라이브러리로 이를 사용해 기존의 caver-js/caver-java 기능을 사용함과 동시에 KAS의 Node API, TokenHistory API, Wallet API 그리고 Anchor API도 사용하실 수 있습니다.

KAS SDK에 관한 자세한 내용은 다음을 확인하십시오.

KAS API 에러 코드

KAS API 에러코드는 아래 각 API Reference를 확인하십시오

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

이 문서 혹은 KAS에 관한 문의는 개발자 포럼을 방문해 도움 받으십시오.