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

Generate Operator

Create Operator Click the "Create" button on the KAS Console > Service > Anchor > Operator menu 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.
warning
To ensure smooth execution of the anchoring transaction, use useGlobalFeepayer.

info
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.

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.

Information of Created Operator

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 Developers 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

cURLJavaScriptJava

Copy

Copied

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

Copy

Copied

const query = caver.kas.anchor.queryOptions.constructFromObject({
  fromTimestamp: 1501576981,
  toTimestamp: 1601876982,
  size: 3,
  cursor: "",
});
const result = await caver.kas.anchor.getOperatorList(query);

Copy

Copied

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.

cURLJavaScriptJava

Copy

Copied

{
  "cursor": "",
  "items": [
    {
      "operator": "0x6945B46Add33ABD0576b4D99B4c86Fe28c0Ad026",
      "setting": {
        "useGlobalFeePayer": true,
        "useOperator": true
      }
    },
    {
      "operator": "0x60A4B9342D439ED9D2DbdFf08aB9ceE1eFb73D10",
      "setting": {
        "useGlobalFeePayer": true,
        "useOperator": true
      }
    },
    {
      "operator": "0x002909B4C40a874a5587aa0D15cc847F7E79aD76",
      "setting": {
        "useGlobalFeePayer": true,
        "useOperator": true
      }
    }
  ]
}

Copy

Copied

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

Copy

Copied

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 Developers 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.

cURLJavaScriptJava

Copy

Copied

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

Copy

Copied

const result = await caver.kas.anchor.getOperator(
  "0x371E04979132C23330eE777601C981453f7f542e"
);

Copy

Copied

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.

cURLJavaScriptJava

Copy

Copied

{
  "operator": "0x6945B46Add33ABD0576b4D99B4c86Fe28c0Ad026",
  "setting": {
    "useGlobalFeePayer": true,
    "useOperator": true
  }
}

Copy

Copied

Operator {
  createdAt: 1598596270,
  operator: '0x371E04979132C23330eE777601C981453f7f542e',
  setting: OperatorSetting { useGlobalFeePayer: true, useOperator: false }
}

Copy

Copied

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 Developers 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.
info
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.

cURLJavaScriptJava

Copy

Copied

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

Copy

Copied

const data = {
  id: "891825",
  custom_field: "This is test custom field for anchoring",
};
const result = await caver.kas.anchor.sendAnchoringData(
  "0xc8Aa073E2A924Fc469339Ff0cB2Ec4A7838888D0",
  data
);

Copy

Copied

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

info

For details about data anchoring, please visit here.

warning

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 prior to API calls.

API Response

A notification on whether the data anchoring is successful is returned as an API response.

cURLJavaScriptJava

Copy

Copied

{
  "status": "succeed"
}

Copy

Copied

AnchorBlockStatus { status: 'succeed' }

Copy

Copied

class AnchorBlockStatus {
    status: succeed
}

For details about this API, please visit here. For inquires about this document or KAS, please visit KAS Developers 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

cURLJavaScriptJava

Copy

Copied

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

Copy

Copied

const query = caver.kas.anchor.queryOptions.constructFromObject({
  fromTimestamp: 1501576981,
  toTimestamp: 1601876982,
  size: 3,
  cursor: "",
});
const result = await caver.kas.anchor.getAnchoringTransactionList(
  "0xc8Aa073E2A924Fc469339Ff0cB2Ec4A7838888D0",
  query
);

Copy

Copied

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.

cURLJavaScriptJava

Copy

Copied

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

Copy

Copied

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

Copy

Copied

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 Developers 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.

cURLJavaScriptJava

Copy

Copied

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

Copy

Copied

const result = await caver.kas.anchor.getAnchoringTransactionByTxHash(
  "0xc8Aa073E2A924Fc469339Ff0cB2Ec4A7838888D0",
  "0x9b67fb089d942af13db118932d62a605371978df754d1a97807df305d6a1a08f"
);

Copy

Copied

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.

cURLJavaScriptJava

Copy

Copied

{
  "payload": {
    "customField1": "field1",
    "customField2": "field2",
    "id": "c61cc0d0-5878-450e-bec8-bf73d6184798"
  },
  "transactionHash": "0x5aeb4ddc5d77b9ce977a87461573da00c0aed0ac59962892ecf58ec09296e79d"
}

Copy

Copied

AnchorBlockTransactions {
  payload: {
    custom_field: 'This is test custom field for anchoring',
    id: '891825'
  },
  transactionHash: '0x9b67fb089d942af13db118932d62a605371978df754d1a97807df305d6a1a08f'
}

Copy

Copied

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 Developers 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.

cURLJavaScriptJava

Copy

Copied

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

Copy

Copied

const result = await caver.kas.anchor.getAnchoringTransactionByPayloadId(
  "0xc8Aa073E2A924Fc469339Ff0cB2Ec4A7838888D0",
  "891825"
);

Copy

Copied

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.

cURLJavaScriptJava

Copy

Copied

{
  "payload": {
    "customField1": "field1",
    "customField2": "field2",
    "id": "c61cc0d0-5878-450e-bec8-bf73d6184798"
  },
  "transactionHash": "0x5aeb4ddc5d77b9ce977a87461573da00c0aed0ac59962892ecf58ec09296e79d"
}

Copy

Copied

AnchorBlockTransactions {
  payload: {
    custom_field: 'This is test custom field for anchoring',
    id: '891825'
  },
  transactionHash: '0x9b67fb089d942af13db118932d62a605371978df754d1a97807df305d6a1a08f'
}

Copy

Copied

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 Developers Forum.