Links

Anchor API

This page introduces how to anchor service chain data to Klaytn main chain with Anchor API.

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.
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.
For details about service chain, please visit here. For details about data anchoring of service chain, please visit here.

Create Operator

KAS Console - Service - Anchor - Operator

Click the “Create” button on the KAS Console - Service - Anchor - Operator menu. Click the button to display the screen for creating operators as follows.
Service - Anchor - Operator

Configure Transaction Fee Payments for Data Anchoring Transaction

For creating an operator on the KAS Console, set the account that would pay the anchoring transaction fee for data to be sent by the operator.
Create Operator and Configure Anchoring Transaction Fee
Parameter
Description
feepayer
User fee delegation payment account address. Used when paying data anchoring transaction fees using the fee-payer account.
useOperator
Whether the operator or KAS will pay data anchoring transaction fee (the transaction fee will be charged to the user)
useGlobalFeepayer
Whether the fee payer account provided by KAS first pays the bill (the transaction fee will be charged to the user later)
  • Use useGlobalFeepayer to send the data anchoring transaction even if the KLAY balance is insufficient.
  • An error will occur if all thee parameters are not set.
  • The data anchoring transaction fee will be delegated according to the following priorities if one or more parameters are entered.
To ensure smooth execution of the anchoring transaction, use useGlobalFeepayer.
To use feepayer, first create a Fee Delegation Account Pool and Fee Delegation Account. The fee-payer account address (address) and KRN value of the fee delegation Account Pool are required to use the feepayer.
The fee payment priority will be as follows if several parameters are used together to send anchoring transactions.
Priority
Parameter
the transaction fee payer
1
feepayer
User’s separate fee-payer account
2
useOperator
Operator
3
useGlobalFeepayer
KAS (transaction fee will be charged to the user later)
The account with higher priority will pay the anchoring transaction fee first if all three parameters are used. If the operator struggles to pay the transaction fee because of insufficient feepayer account balance, the operator that sends an anchoring transaction will directly pay the fee as it has the next priority.
The example of using feepayer and global_feepayer
  • Expected Results by Parameter Settings
useGlobalFeepayer
feepayer
useOperator
Priority
false
X
false
Error
true
X
false
KAS
false
X
true
Operator
true
X
true
Operator > KAS
false
O
false
User fee payer
false
O
true
User fee payer > Operator
true
O
true
User fee payer > Operator > KAS
true
O
false
User fee payer > KAS

Create Operator

Once the parameters are set, create an operator. The operator must have a different name from other operators on the current KAS account.
Operator You can check the created operator in the operator list. Or you can call all operator list search APIs and search.
For inquires about this document or KAS, please visit KAS Developer forum.

Get Operator List

API Request

Search for the list of created operators and setting values of each one. You may use the REST API or KAS SDKs (caver-js, caver-java extensions) for this.

Query Parameter

You can receive API response values with Cursor-based Pagination. The search range can also be set by second.
Parameter
Description
Example
Required or Not
size
the number of items in the API response (min=1, max=1000, default=100)
size=100
False
cursor
the cursor required to get the next batch of response items
cursor=J9Ag...VM6z
False
to-timestamp
Search Range: The last timestamp (sec)
to-timestamp=15921809920
False
from-timestamp
Search Range: The first timestamp (sec)
from-timestamp=1592360291
False
curl
javascript
java
curl --location --request GET "https://anchor-api.klaytnapi.com/v1/operator?&size=100&cursor=J9Ag...VM6z&from-timestamp=1592360291&to-timestamp=15991809920" \
-u {access-key-id}:{secret-access-key} \
--header "x-chain-id: {chain-id}"
const query = caver.kas.anchor.queryOptions.constructFromObject({ fromTimestamp: 1501576981, toTimestamp: 1601876982, size: 3, cursor: '' })
const result = await caver.kas.anchor.getOperatorList(query)
AnchorQueryOptions anchorQueryParams = new AnchorQueryOptions();
anchorQueryParams.setSize((long)3);
anchorQueryParams.setFromTimestamp((long)1592360291);
anchorQueryParams.setToTimestamp((long)15991809920);
Operators operators = caver.kas.anchor.getOperatorList(anchorQueryParams);
System.out.println(operators);
  • x-chain-id is the id of the chain to which the operator was registered.

API Response

Here is the response of the Operator List Search API.
curl
javascript
java
{
"cursor": "",
"items": [
{
"operator": "0x6945B46Add33ABD0576b4D99B4c86Fe28c0Ad026",
"setting": {
"useGlobalFeePayer": true,
"useOperator": true
}
},
{
"operator": "0x60A4B9342D439ED9D2DbdFf08aB9ceE1eFb73D10",
"setting": {
"useGlobalFeePayer": true,
"useOperator": true
}
},
{
"operator": "0x002909B4C40a874a5587aa0D15cc847F7E79aD76",
"setting": {
"useGlobalFeePayer": true,
"useOperator": true
}
}
]
}
Operators {
cursor: 'eyJjcmVhdGVkX2F0IjoxNTk4NTk2MTMzLCJkb2NfaWQiOiJrcm46MTAwMTphbmNob3I6OGU3NmQwMDMtZDZkZC00Mjc4LThkMDUtNTE3MmQ4ZjAxMGNhOm9wZXJhdG9yLXBvb2w6ZGVmYXVsdDoweDAwODBFNDZEOEEwZmUxNGY4Mjk3OUM3MWNEZTM1QzhEN0MyYmZmOTAiLCJycG4iOiJrcm46MTAwMTphbmNob3I6OGU3NmQwMDMtZDZkZC00Mjc4LThkMDUtNTE3MmQ4ZjAxMGNhOm9wZXJhdG9yLXBvb2w6ZGVmYXVsdCIsInR5cGUiOiJPUFIifQ==',
items: [
Operator {
createdAt: 1598596270,
operator: '0x371E04979132C23330eE777601C981453f7f542e',
setting: OperatorSetting { useGlobalFeePayer: true, useOperator: false }
},
Operator {
createdAt: 1598596140,
operator: '0xFb1f3B40BD102323d18ADC308D5B1bA91701156d',
setting: OperatorSetting { useGlobalFeePayer: true, useOperator: false }
},
Operator {
createdAt: 1598596133,
operator: '0x0080E46D8A0fe14f82979C71cDe35C8D7C2bff90',
setting: OperatorSetting { useGlobalFeePayer: true, useOperator: false }
}
]
}
class Operators {
cursor:
items: [class Operator {
createdAt: 1597897525
operator: 0x0Ea563A80f5ea22C174030416E7fCdbeD920D5EB
setting: class OperatorSetting {
useGlobalFeePayer: true
useOperator: false
}
}, class Operator {
createdAt: 1597897530
operator: 0x60A4B9342D439ED9D2DbdFf08aB9ceE1eFb73D10
setting: class OperatorSetting {
useGlobalFeePayer: true
useOperator: false
}
}, class Operator {
createdAt: 1597897535
operator: 0x002909B4C40a874a5587aa0D15cc847F7E79aD76
setting: class OperatorSetting {
useGlobalFeePayer: true
useOperator: false
}
}]
}
For details about this API, please visit here. For inquires about this document or KAS, please visit KAS Developer forum.

Get Operator Information

Or you can search for the created operator information with the operator’s Klaytn account address (operator-id).

API Request

Search for the settings and account balance of the operator above. You may use the REST API or KAS SDKs (caver-js, caver-java extensions) for this.
curl
javascript
java
curl --location --request GET "https://anchor-api.klaytnapi.com/v1/operator/0x6945B46Add33ABD0576b4D99B4c86Fe28c0Ad026" \
-u {access-key-id}:{secret-access-key} \
--header "x-chain-id: {chain-id}"
const result = await caver.kas.anchor.getOperator('0x371E04979132C23330eE777601C981453f7f542e')
Operator operator = caver.kas.anchor.getOperator("0x0Ea563A80f5ea22C174030416E7fCdbeD920D5EB");
System.out.println(operator);
  • x-chain-id is the id of the chain to which the operator was registered.

API Response

The response example of this API is as follows.
curl
javascript
java
{
"operator": "0x6945B46Add33ABD0576b4D99B4c86Fe28c0Ad026",
"setting": {
"useGlobalFeePayer": true,
"useOperator": true
}
}
Operator {
createdAt: 1598596270,
operator: '0x371E04979132C23330eE777601C981453f7f542e',
setting: OperatorSetting { useGlobalFeePayer: true, useOperator: false }
}
class Operator {
createdAt: 1597897525
operator: 0x0Ea563A80f5ea22C174030416E7fCdbeD920D5EB
setting: class OperatorSetting {
useGlobalFeePayer: true
useOperator: false
}
}
For details about this API, please visit here. For inquires about this document or KAS, please visit KAS Developer forum.

Send Data Anchoring Transaction

A user must call the Data Anchoring API to anchor the service chain data to the main chain. Request for the data anchoring transaction with the Klaytn account address of the operator created above.

Payload

The “payload” is the “data itself to anchor to the main chain.” Here are examples of “custom_field1” and “custom_field2” entered in the following payload value. Enter the required data to anchor to the main chain in JSON format (key:value), similar to “custom_field1” and “custom_field2,” to use the payload.
Enter the string in the “id” field to Search Anchoring Transaction using the string.

API Request

Call the Data Anchoring API as follows. You may use the REST API or KAS SDKs (caver-js, caver-java extensions) for this.
curl
javascript
java
curl --location --request POST "https://anchor-api.klaytnapi.com/v1/anchor" \
-u {access-key-id}:{secret-access-key} \
--header "x-chain-id: {chain-id}" \
--header "Content-Type: application/json" \
--data-raw "{
"operator": "0x6945B46Add33ABD0576b4D99B4c86Fe28c0Ad026",
"payload": {
"id": "{$guid}",
"customField1": "field1",
"customField2": "field2"
}
}"
const data = { id: '891825', custom_field: 'This is test custom field for anchoring'}
const result = await caver.kas.anchor.sendAnchoringData('0xc8Aa073E2A924Fc469339Ff0cB2Ec4A7838888D0', data)
AnchorBlockPayload payload = new AnchorBlockPayload();
payload.put("id", Integer.toString(random.nextInt()));
payload.put("field", "1");
payload.put("filed2", 4);
AnchorBlockStatus response = caver.kas.anchor.sendAnchoringData(operatorID, payload);
System.out.println(response);
For details about data anchoring, please visit here.
If you want to use fee-delegation for sending this transaction, go to KAS Console - Anchor - Operator menu and configure fee-delegation. If you want to guarantee sending the anchoring transaction, please set UseGlobalFeePayer and use Anchor API.

API Response

A notification on whether the data anchoring is successful is returned as an API response.
curl
javascript
java
{
"status": "succeed"
}
AnchorBlockStatus { status: 'succeed' }
class AnchorBlockStatus {
status: succeed
}
For details about this API, please visit here. For inquires about this document or KAS, please visit KAS Developer forum. ㅏ

Get List of Anchoring Transaction by Operator Address

Search for the list of data anchoring transactions sent by this operator with the operator’s Klaytn account address.

API Request

Call the Anchoring Transaction Search API. You may use the REST API or KAS SDKs (caver-js, caver-java extensions) for this.

Query Parameter

You can receive API response values with Cursor-based Pagination. The search range can also be set by second.
Parameter
Description
Example
Required or Not
size
the number of items in the API response (min=1, max=1000, default=100)
size=100
False
cursor
the cursor required to get the next batch of response items
cursor=J9Ag...VM6z
False
to-timestamp
Search Range: The last timestamp (sec)
to-timestamp=15921809920
False
from-timestamp
Search Range: The first timestamp (sec)
from-timestamp=1592360291
False
curl
javascript
java
curl --location --request GET "https://anchor-api.klaytnapi.com/v1/operator/0x6945B46Add33ABD0576b4D99B4c86Fe28c0Ad026/tx?&size=100&cursor=J9Ag...VM6z&from-timestamp=1592360291&to-timestamp=15991809920" \
-u {access-key-id}:{secret-access-key} \
--header "x-chain-id: {chain-id}" \
--header "Content-Type: application/json" \
const query = caver.kas.anchor.queryOptions.constructFromObject({ fromTimestamp: 1501576981, toTimestamp: 1601876982, size: 3, cursor: '' })
const result = await caver.kas.anchor.getAnchoringTransactionList('0xc8Aa073E2A924Fc469339Ff0cB2Ec4A7838888D0', query)
AnchorQueryOptions anchorQueryParams = new AnchorQueryOptions();
anchorQueryParams.setSize((long)3);
anchorQueryParams.setFromTimestamp((long)1599142860);
anchorQueryParams.setToTimestamp((long)1599142845);
AnchorTransactions res = caver.kas.anchor.getAnchoringTransactionList(operatorID, anchorQueryParams);
System.out.println(res);

API Response

Here is the response of the Anchoring Data Search API.
curl
javascript
java
{
"cursor": "",
"items": [
{
"createdAt": 1599142860,
"payloadId": "c61cc0d0-5878-450e-bec8-bf73d6184798",
"transactionHash": "0x5aeb4ddc5d77b9ce977a87461573da00c0aed0ac59962892ecf58ec09296e79d"
},
{
"createdAt": 1599142859,
"payloadId": "d4f1a11f-4609-40f5-9d59-2313a5799508",
"transactionHash": "0x70f6f6745ad0b0f4ce5908f40d20a1f44bd34871e0428be782d84f9a53ea2ba0"
},
{
"createdAt": 1599142857,
"payloadId": "48b59825-82b2-4595-abfb-c465112618cc",
"transactionHash": "0x3f90cd2e02576fd85572ab76aff49b87b9cf3efb623f34bb8d6354ee1b88869f"
},
{
"createdAt": 1599142841,
"payloadId": "b315de34-52cb-41c0-9383-3260ceafd3b2",
"transactionHash": "0x8a73a00f04a1f6e8d8af101487bd35f8dbcce6fcb3ddd95059f42b8f7fbc3345"
}
]
}
AnchorTransactions {
cursor: 'eyJjcmVhdGVkX2F0IjoxNTk5NjEyNzg5LCJkb2NfaWQiOiJrcm46MTAwMTphbmNob3I6OGU3NmQwMDMtZDZkZC00Mjc4LThkMDUtNTE3MmQ4ZjAxMGNhOm9wZXJhdG9yLXBvb2w6ZGVmYXVsdDoweGM4QWEwNzNFMkE5MjRGYzQ2OTMzOUZmMGNCMkVjNEE3ODM4ODg4RDA6NTI3MzM5NDUzMiIsInF1ZXJ5X2lkIjoia3JuOjEwMDE6YW5jaG9yOjhlNzZkMDAzLWQ2ZGQtNDI3OC04ZDA1LTUxNzJkOGYwMTBjYTpvcGVyYXRvci1wb29sOmRlZmF1bHQ6QU5DSF9UWDoweGM4QWEwNzNFMkE5MjRGYzQ2OTMzOUZmMGNCMkVjNEE3ODM4ODg4RDAiLCJ0eXBlIjoiQU5DSF9UWCJ9',
items: [
AnchorTransaction {
createdAt: 1599626680,
payloadId: '5593367445',
transactionHash: '0x93607f7f3a0131f804d0b847c18311ccb8b9aa6526b21febf19db9759038b0a6'
},
AnchorTransaction {
createdAt: 1599614650,
payloadId: '6201274638',
transactionHash: '0x0bd1961ba478aae4d64ecb6b4d45fcd0edc76249bdcf7ef0d6feb0b4b1080591'
},
AnchorTransaction {
createdAt: 1599612789,
payloadId: '5273394532',
transactionHash: '0xd3b5de1c8e15be76491fffa58c241b292a714df91d611a26811bc0df906390b5'
}
]
}
class AnchorTransactions {
cursor: eyJjcmVhdGVkX2F0IjoxNTk4MzQ1ODYxLCJkb2NfaWQiOiJrcm46MTAwMTphbmNob3I6ZDVjMzQ2ZjUtYmI4MC00ZjQ1LTkwOTMtNTdlMjUyMDVjZGM4Om9wZXJhdG9yLXBvb2w6ZGVmYXVsdDoweDBFYTU2M0E4MGY1ZWEyMkMxNzQwMzA0MTZFN2ZDZGJlRDkyMEQ1RUI6Y3VzdG9tX2lkMTExMTE0IiwicXVlcnlfaWQiOiJrcm46MTAwMTphbmNob3I6ZDVjMzQ2ZjUtYmI4MC00ZjQ1LTkwOTMtNTdlMjUyMDVjZGM4Om9wZXJhdG9yLXBvb2w6ZGVmYXVsdDpBTkNIX1RYOjB4MEVhNTYzQTgwZjVlYTIyQzE3NDAzMDQxNkU3ZkNkYmVEOTIwRDVFQiIsInR5cGUiOiJBTkNIX1RYIn0=
items: [class AnchorTransaction {
createdAt: 1598345953
payloadId: 77777
transactionHash: 0xf2777b31f99d268eecc356409a45b2bf916cc63d629f270f21b3e197bc11e851
}, class AnchorTransaction {
createdAt: 1598345931
payloadId: custom_id111115
transactionHash: 0x534e9b6e40c483d5eec379a6bd034726daf78acb7d000b15c975606c5a7ad113
}, class AnchorTransaction {
createdAt: 1598345861
payloadId: custom_id111114
transactionHash: 0xb976f868b4b5f1208a24d783603ddb784d91d72b9643ddd64ded1e8444175dc3
}]
}
For details about this API, please visit here. For inquires about this document or KAS, please visit KAS Developer forum. ㅏ

Get Anchoring Transaction Information By Transaction Hash and Operator Address

You can use the transaction hash and operator address to search for payload details of anchoring transactions.

API Request

Call the Anchoring Transaction Details Search API. You may use the REST API or KAS SDKs (caver-js, caver-java extensions) for this.
curl
javascript
java
curl --location --request GET "https://anchor-api.klaytnapi.com/v1/operator/0x6945B46Add33ABD0576b4D99B4c86Fe28c0Ad026/tx/0xf7db6019fcb9621ed01baf7d27d2f8cfd58b9aa24e5a1e73276ed84e254b54c0" \
-u {access-key-id}:{secret-access-key} \
--header "x-chain-id: {chain-id}"
const result = await caver.kas.anchor.getAnchoringTransactionByTxHash('0xc8Aa073E2A924Fc469339Ff0cB2Ec4A7838888D0', '0x9b67fb089d942af13db118932d62a605371978df754d1a97807df305d6a1a08f')
String operatorID = "0x0Ea563A80f5ea22C174030416E7fCdbeD920D5EB";
String txHash = "0x74ee2fcf41b7bee3cb6ff0e9d5facb877cf9da178236d5ccc371318cbf09d6de";
AnchorTransactionDetail res = caver.kas.anchor.getAnchoringTransactionByTxHash(operatorID, txHash);
System.out.println(res);
API Response
Here is the response of the Anchoring Transaction Payload Details Search API.
curl
javascript
java
{
"payload": {
"customField1": "field1",
"customField2": "field2",
"id": "c61cc0d0-5878-450e-bec8-bf73d6184798"
},
"transactionHash": "0x5aeb4ddc5d77b9ce977a87461573da00c0aed0ac59962892ecf58ec09296e79d"
}
AnchorBlockTransactions {
payload: {
custom_field: 'This is test custom field for anchoring',
id: '891825'
},
transactionHash: '0x9b67fb089d942af13db118932d62a605371978df754d1a97807df305d6a1a08f'
}
class AnchorTransactionDetail {
payload: class AnchorBlockPayload {
{filed2=4.0, field=1}
}
transactionHash: 0x74ee2fcf41b7bee3cb6ff0e9d5facb877cf9da178236d5ccc371318cbf09d6de
}
For details about this API, please visit here. For inquires about this document or KAS, please visit KAS Developer forum.

Get Payload by Operator Address and Payload ID

You can use the payload ID and operator address to search for the payload details of anchoring transactions.

API Request

Call the Anchoring Transaction Details Search API. You may use the REST API or KAS SDKs (caver-js, caver-java extensions) for this.
curl
javascript
java
curl --location --request GET "https://anchor-api.klaytnapi.com/v1/operator/0x6945B46Add33ABD0576b4D99B4c86Fe28c0Ad026/payload/c61cc0d0-5878-450e-bec8-bf73d6184798" \
-u {access-key-id}:{secret-access-key} \
--header "x-chain-id: {chain-id}"
const result = await caver.kas.anchor.getAnchoringTransactionByPayloadId('0xc8Aa073E2A924Fc469339Ff0cB2Ec4A7838888D0', '891825')
String operatorID = "0x0Ea563A80f5ea22C174030416E7fCdbeD920D5EB";
String payloadId = "0xca0577c2f7f2537d499357c2bd08c72a808d7bb718a336b69fd37f640c73ba6d";
AnchorTransactionDetail res = caver.kas.anchor.getAnchoringTransactionByPayloadId(operatorID, payloadId);
API Response
Here is the response of the Anchoring Transaction Payload Details Search API.
curl
javascript
java
{
"payload": {
"customField1": "field1",
"customField2": "field2",
"id": "c61cc0d0-5878-450e-bec8-bf73d6184798"
},
"transactionHash": "0x5aeb4ddc5d77b9ce977a87461573da00c0aed0ac59962892ecf58ec09296e79d"
}
AnchorBlockTransactions {
payload: {
custom_field: 'This is test custom field for anchoring',
id: '891825'
},
transactionHash: '0x9b67fb089d942af13db118932d62a605371978df754d1a97807df305d6a1a08f'
}
class AnchorTransactionDetail {
payload: class AnchorBlockPayload {
{filed2=4.0, field=1}
}
transactionHash: 0x74ee2fcf41b7bee3cb6ff0e9d5facb877cf9da178236d5ccc371318cbf09d6de
}
For details about this API, please visit here. For inquires about this document or KAS, please visit KAS Developer forum.