Before Getting Started

  • API introduced in here should only be used with HTTP Request.
  • The x-chain-id value for calling the API is 8217 (Mainnet) or 1001 (Kairos).
  • 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 Kaia Mainnet or Kairos
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 Kaia account which was created by calling Wallet API via this API Auth Key. The rights here include accessing and transferring all the assets (KAIA, etc.) of or sending a transaction from a Kaia account. If you shared your API Auth Key with any unauthorized personnel, your Kaia 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/Kaia account.

Get Token History by Preset

Preset

Preset is information required for KAS to get transfer record of 1 or more tokens. Once a preset is registered on KAS Console, KAS keeps monitoring transfer history of several tokens in the preset so that the transfer history can be loaded at once when you search it. EOA, FT contract address, and NFT contract address can be registered to the preset. This API searches token transfer record according to information in a preset.

FT contract is a type of smart contract deployed to Kaia that allows users to issue, delete, and send Fungible Token (Fungible Token, FT). NFT contract is a type of smart contract deployed to Kaia that allows users to issue, delete, and send Non-fungible Token (Non-Fungible Token, NFT).

Presets must be registered on KAS console before using this API. Preset IDs of registered presets can be found on KAS console. For more details on how to create presets and check their IDs, refer to the following.

  • Preset Example 1: EOA Here is an example of preset with only EOA registered.
    Copy
    Copied
    {
"addresses": [
  "0xd0ea3e0eabaea095ea3ba231c043dbf8c0feb40a",
  "0xa308064ad41e46310b7e463b610ae642a5007086"
]
}

    If this API is called with only the preset is registered on KAS console, EOA (Kaia account address) that is registered to the preset receives only KAIA/NFT/FT transfer record as an API response. For example, KAIA transfer history of KAIA Transmission Transaction that from or to is 0xd0ea3e0eabaea095ea3ba231c043dbf8c0feb40a or 0xa308064ad41e46310b7e463b610ae642a5007086 are received only as responses.

    Here is an example of preset with only EOA registered.

  • Preset Example 2: FT Contract Address Here is an example of preset with only FT contract address registered.
    Copy
    Copied
    {
"ftContractAddresses": ["0x90d68ef8a262a4a54ed1632dd5a31afb4d35753d"]
}

    If this API is called with only the preset registered on KAS console, entire transfer history of FT token having 0x90d68ef8a262a4a54ed1632dd5a31afb4d35753d as its token contract address are received as responses.

  • Preset Example 3: EOA and FT Contract Address Here is an example of preset with EOA and FT contract address registered.
    Copy
    Copied
    {
"addresses": ["0xd0ea3e0eabaea095ea3ba231c043dbf8c0feb40a"],
"ftContractAddresses": ["0x90d68ef8a262a4a54ed1632dd5a31afb4d35753d"]
}

    If this API is called with only the preset registered on KAS console, entire transfer history of FT token (0x90d68ef8a262a4a54ed1632dd5a31afb4d35753d as its token contract address) that from or to is 0xd0ea3e0eabaea095ea3ba231c043dbf8c0feb40a are received as responses.

  • Preset Example 4: NFT Contract Address NFT contract addresses can be stored in a preset as with FT contract addresses.
    Copy
    Copied
    {
"nftContractAddresses": ["0x462e90a68328662163189c3b35fafeea3f6b29e8"]
}

    If this API is called with only the preset registered on KAS console, entire transfer history of NFT token having 0x90d68ef8a262a4a54ed1632dd5a31afb4d35753d as its token contract address are received as responses. NFT contract addresses can also be used together with EOA as shown in example 3.

All transactions are recorded in one blockchain and transfer details can be interpreted as transmission or reception according to sender (from) and receiver (to). Token History API stores blockchain transactions as transfer details and returns them in user-required formats.

API Request

Search token transfer history with the preset as follows.

Query Parameter

You can search transfer details by specifying type of transfer token, search range, response size, and a preset for searching. Also, you can receive API response values with Cursor-based Pagination.

Parameter Description Example Required or Not
kind ["klay", "ft", "nft"]
If no value was designated, use all 3 values
(KLAY has been renamed as KAIA in Kaia, but use "klay" for compatibility)		 kind=klay or kind=klay,ft,nft False
range Search range (block number or unix time)
Block number should be hexadecimal, unix time should be 10 digit number		 range=0x1,0x2 or range=1592360291,15991809920 False
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
presets Preset IDs to be used for searching presets=65,68 True
cURLJavaScriptJava
Copy
Copied
curl --location --request GET "https://th-api.klaytnapi.com/v2/transfer?kind=klay,ft,nft&presets=65,68&range=1592360291,15991809920" \
    --header "x-chain-id: {chain-id}" \
    -u {access-key-id}:{secret-access-key}
Copy
Copied
const query = {
  kind: [caver.kas.tokenHistory.queryOptions.kind.KLAY],
  size: 1,
  range: "1593529200,1599145200",
};
const result = await caver.kas.tokenHistory.getTransferHistory([80], query);
Copy
Copied
TokenHistoryQueryOptions options = new TokenHistoryQueryOptions();
options.setSize((long)1);
options.setRange("1584583000", "1584583388");
options.setKind("ft");

PageableTransfers result = caver.kas.tokenHistory.getTransferHistory(82, options);
System.out.println(result);

API Response

The following response will be received if the request was successful.

cURLJavaScriptJava
Copy
Copied
{
  "items": [
    {
      "transferType": "klay",
      "from": "0xfee21dec2936f4cf7714080559db1c53ce639e07",
      "fee": "0x2114b6e5980400",
      "status": 1,
      "to": "0xe33337cb6fbb68954fe1c3fde2b21f56586632cd",
      "transactionHash": "0xa0f6663d713bf173e9e2563f588ab11dc09df34970ae60c5e7bf5c383a8bc17c",
      "transactionIndex": 0,
      "typeInt": 48,
      "timestamp": 1596025548,
      "value": "0x218ae196b8d4f300000",
      "feePayer": "",
      "feeRatio": 10
    },
    {
      "transferType": "klay",
      "from": "0xe83d131a941b767594262f1e7d635260b2facc61",
      "fee": "0x2c0dbbfb37000",
      "status": 1,
      "to": "0xfee21dec2936f4cf7714080559db1c53ce639e07",
      "transactionHash": "0x61f1e0b317b0bbb2d29a58c1791b8290210188b5422f53b135f3cbb993140876",
      "transactionIndex": 0,
      "typeInt": 9,
      "timestamp": 1596025448,
      "value": "0x218ae3cf27fbef10000",
      "feePayer": "0x10f0eaa52a474f0605afbb8c17bb9189e6ed006c",
      "feeRatio": 10
    }
  ],
  "cursor": ""
}
Copy
Copied
PageableTransfers {
    items: [
        TransferItem {
            feePayer: '',
            feeRatio: 0,
            fee: '0x48ba158a44a00',
            from: '0x76c6b1f34562ed7a843786e1d7f57d0d7948a6f1',
            to: '0xbbe63781168c9e67e7a8b112425aa84c479f39aa',
            transactionHash: '0x063b947b7bc70356ace9644a30188541e345b28e532810d1b80c132882c742ad',
            transactionIndex: 0,
            transferType: 'klay',
            typeInt: 48,
            value: '0x0'
        }
    ],
    cursor: 'qrX1b6xwlmk9PJea2XLzoN30gKQAYGxbvro0Qk97dx5WAvJBpaKw6lPR1VLbVEzQV2P6XtYuNjgzVXe1DL4MGEbmO823NqYZWlk4rqdpVwm51B86ZD7EOM2WeDNBPQKE'
}
Copy
Copied
class PageableTransfers {
    items: class TransferArray {
        [class FtTransfer {
            contract: class FtContract {
                address: 0x770b5c4854497d7c5abe3e5d6ed2dbaf3eac2a77
                decimals: 18
                name: SummerToken_20200319110306
                symbol: JUN
                status: null
            }
            formattedValue: 0.00000001
            from: 0x4df3ee7caf91a7ab60a37815de3c6db4a008d8c0
            to: 0x278868807791af859cee547a016bd339eb86ec98
            transaction: class Transaction {
                feePayer:
                feeRatio: 0
                fee: 0x0
                from: 0x4df3ee7caf91a7ab60a37815de3c6db4a008d8c0
                timestamp: 1584583388
                transactionHash: 0xd3eb91c71f99ec7451f1908e147ffbfd1e25a9179837d025196825d7e6716200
                typeInt: 48
                value: 0x0
            }
            transferType: ft
            value: 0x2540be400
        }]
    }
    cursor: lv4WNYedqPJM1N38XZwpKq5JoQ9PmYledPZqmXb5r4V26Y81gx0lLWDRbEuOGWJ20rl40GTWyJav37MQAokw9ENGKzeBdpOgr2zLV0B7DOAx4avEGW6bkkLg7AOb53Za
}
info

typeInt variable is a value for identifying the transaction type. For details about the types of transactions, please visit here.

For details about this API, please visit here. For inquires about this document or KAS, please visit KAS Developers Forum.

Get Token History by Transaction Hash

Search the history of the token transfer with the transaction hash if there is a transaction hash value that has sent a token.

API Request

Search for the token transfer history based on the token hash as follows.

cURLJavaScriptJava
Copy
Copied
curl --location --request GET "https://th-api.klaytnapi.com/v2/transfer/tx/0x9fb236689b26fc8b8a938a8eb2b7e5a6afc1c7a837c61751f08eac7358db8d73" \
    --header "x-chain-id: {chain-id}" \
    -u {access-key-id}:{secret-access-key}
Copy
Copied
const result = await caver.kas.tokenHistory.getTransferHistoryByTxHash(
  "0x063b947b7bc70356ace9644a30188541e345b28e532810d1b80c132882c742ad"
);
Copy
Copied
String txHash = "0x617a56786f97c76f6d0573d36a624610f1bfb0029e8e8f7afc02c7262e9224fb";

Transfers transfers = caver.kas.tokenHistory.getTransferHistoryByTxHash(txHash);
System.out.println(transfers);
  • transaction-hash (0x9fb236689b2...ac7358db8d73) is a reuired input value and a 32-byte hash of transaction in the block.

API Response

The following response will be received if the request was successful.

cURLJavaScriptJava
Copy
Copied
{
  "items": [
    {
      "transferType": "ft",
      "transaction": {
        "from": "0x5bf30ff4a1a3a905531c5e1b52c635892a9fc28d",
        "fee": "0x48abe561cf400",
        "transactionHash": "0x9fb236689b26fc8b8a938a8eb2b7e5a6afc1c7a837c61751f08eac7358db8d73",
        "typeInt": 49,
        "timestamp": 1597649114,
        "value": "0x0",
        "feePayer": "0xacb22916b804ac088c61c8711ec196b518f2e7fc",
        "feeRatio": 10
      },
      "contract": {
        "address": "0xb1a7abe0c5a9e06cc7585a435e74976d2dee07f3",
        "name": "BlockchainPetToken",
        "symbol": "BPT",
        "decimals": 2
      },
      "from": "0x5bf30ff4a1a3a905531c5e1b52c635892a9fc28d",
      "to": "0xeb7f7926cc4f866cec135728d35a7531c1d12791",
      "value": "0x3e8",
      "formattedValue": "10"
    },
    {
      "transferType": "klay",
      "from": "0x5bf30ff4a1a3a905531c5e1b52c635892a9fc28d",
      "fee": "0x48abe561cf400",
      "status": 1,
      "to": "0xb1a7abe0c5a9e06cc7585a435e74976d2dee07f3",
      "transactionHash": "0x9fb236689b26fc8b8a938a8eb2b7e5a6afc1c7a837c61751f08eac7358db8d73",
      "transactionIndex": 1,
      "typeInt": 49,
      "timestamp": 1597649114,
      "value": "0x0",
      "feePayer": "0xacb22916b804ac088c61c8711ec196b518f2e7fc",
      "feeRatio": 10
    }
  ]
}
Copy
Copied
Transfers {
    items: [
        TransferItem {
            feePayer: '',
            feeRatio: 0,
            fee: '0x48ba158a44a00',
            from: '0x76c6b1f34562ed7a843786e1d7f57d0d7948a6f1',
            to: '0xbbe63781168c9e67e7a8b112425aa84c479f39aa',
            transactionHash: '0x063b947b7bc70356ace9644a30188541e345b28e532810d1b80c132882c742ad',
            transactionIndex: 0,
            transferType: 'klay',
            typeInt: 48,
            value: '0x0'
        }
    ]
}
Copy
Copied
class Transfers {
    items: class TransferArray {
        [class KlayTransfer {
            feePayer:
            feeRatio: 0
            fee: 0x0
            from: 0x74f630bfcf6f3e8d7523b39de821b876446adbd4
            to: 0x770b5c4854497d7c5abe3e5d6ed2dbaf3eac2a77
            transactionHash: 0x617a56786f97c76f6d0573d36a624610f1bfb0029e8e8f7afc02c7262e9224fb
            transactionIndex: 0
            transferType: klay
            typeInt: 48
            value: 0x0
        }, class FtTransfer {
            contract: class FtContract {
                address: 0x770b5c4854497d7c5abe3e5d6ed2dbaf3eac2a77
                decimals: 18
                name: SummerToken
                symbol: JUN
                status: null
            }
            formattedValue: 0.000000000000000001
            from: 0x74f630bfcf6f3e8d7523b39de821b876446adbd4
            to: 0xdc0586196d01579e08218bb46f861071241a3238
            transaction: class Transaction {
                feePayer:
                feeRatio: 0
                fee: 0x0
                from: 0x74f630bfcf6f3e8d7523b39de821b876446adbd4
                timestamp: 1584583410
                transactionHash: 0x617a56786f97c76f6d0573d36a624610f1bfb0029e8e8f7afc02c7262e9224fb
                typeInt: 48
                value: 0x0
            }
            transferType: ft
            value: 0x1
        }]
    }
}
info

"typeInt" variable is a value for identifying the transaction type. For details about the types of transactions, please visit here.

For details about this API, please visit here. For inquires about this document or KAS, please visit KAS Developers Forum.

Get Token History by EOA

Search for the token transfer history of a specific EOA.

API Request

Search for the token transfer history based on the EOA as follows.

Query Parameter

Users can search for transfer details by specifying the type of transfer token, search range, response size, and contract addresses (ca-filter). Also, you can receive API response values with Cursor-based Pagination.

Parameter Description Example Required or Not
kind ["klay", "ft", "nft"]
If no value was designated, use all 3 values
(KLAY has been renamed as KAIA in Kaia, but use "klay" for compatibility)		 kind=klay or kind=klay,ft,nft False
range Search range (block number or unix time)
Block number should be hexadecimal, unix time should be 10 digit number		 range=0x1,0x2 or range=1592360291,15991809920 False
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
ca-filter FT or NFT contract address to be searched ca-filter=0xc756...1118 False
cURLJavaScriptJava
Copy
Copied
curl --location --request GET "https://th-api.klaytnapi.com/v2/transfer/account/0xc060632ad88d0dec2bbc44bbea9d4c48c2ead48f?kind=klay,ft,nft&range=1592360291,15991809920" \
    --header "x-chain-id: {chain-id}" \
    -u {access-key-id}:{secret-access-key}
Copy
Copied
const query = {
  kind: [caver.kas.tokenHistory.queryOptions.kind.NFT],
  size: 1,
  range: "1593529200,1599145200",
  caFilter: "0xbbe63781168c9e67e7a8b112425aa84c479f39aa",
};
const result = await caver.kas.tokenHistory.getTransferHistoryByAccount(
  "0x76c6b1f34562ed7a843786e1d7f57d0d7948a6f1",
  query
);
Copy
Copied
String account = "0x74f630bfcf6f3e8d7523b39de821b876446adbd4";
String caFilter = "0xdb71dd9e38af6cb8fdd7cfe498c2337864d5a0f6";

TokenHistoryQueryOptions options = new TokenHistoryQueryOptions();
options.setKind("nft");
options.setRange("1584583430", "1584583500");
options.setSize((long)1);
options.setCaFilter(caFilter);

PageableTransfers transfers = caver.kas.tokenHistory.getTransferHistoryByAccount(account, options);
System.out.println(transfers);
  • address is the EOA used to search and a required input value.
  • In the example of API call, "0xc060...d48f" is a random value.

API Response

The following response will be received if the request was successful.

cURLJavaScriptJava
Copy
Copied
{
    "items": [
        {
            "transferType": "klay",
            "from": "0xc060632ad88d0dec2bbc44bbea9d4c48c2ead48f",
            "fee": "0x6b7cf1b09bc00",
            "status": 1,
            "to": "0xd07453030abc0e37ee81371e2505bf55e0be6440",
            "transactionHash": "0x8771b0bbf25c19dc0d4be3e4a536830a26f4a06e129b34f49b4ac765bf9d6185",
            "transactionIndex": 3,
            "typeInt": 48,
            "timestamp": 1598855708,
            "value": "0x0",
            "feePayer": "",
            "feeRatio": 10
        },
        {
            "transferType": "ft",
            "transaction": {
                "from": "0xc060632ad88d0dec2bbc44bbea9d4c48c2ead48f",
                "fee": "0x6b7cf1b09bc00",
                "transactionHash": "0x8d9c23f2a9381243062b5f5b15f9d4793942bc74d7f6a3ac9bbb294e693c1540",
                "typeInt": 48,
                "timestamp": 1582622881,
                "value": "0x0",
                "feePayer": "",
                "feeRatio": 10
            },
            "contract": {
                "address": "0x46f307b58bf05ff089ba23799fae0e518557f87c",
                "name": "Airbloc",
                "symbol": "ABL",
                "decimals": 18
            },
            "from": "0xd07453030abc0e37ee81371e2505bf55e0be6440",
            "to": "0xc060632ad88d0dec2bbc44bbea9d4c48c2ead48f",
            "value": "0xde0b6b3a7640000",
            "formattedValue": "1"
        },
        ...
        ,
        {
            "transferType": "klay",
            "from": "0xc060632ad88d0dec2bbc44bbea9d4c48c2ead48f",
            "fee": "0x449e582f0cc00",
            "status": 1,
            "to": "0xd07453030abc0e37ee81371e2505bf55e0be6440",
            "transactionHash": "0xc93453af98297b953afb34f8aed92ae2acc3d96cd5291e9fc43bfea1fedfc076",
            "transactionIndex": 0,
            "typeInt": 0,
            "timestamp": 1582254900,
            "value": "0x0",
            "feePayer": "",
            "feeRatio": 10
        }
    ],
    "cursor": "18G42d0gY531Z2pzqEVrDWMLmQ9kz2epXE8JZwadKGrOqW3oVRxN6PAJX73aKMgTKW6LBZJe2OvvT2nDL6Pxgb9m4YQv5AM0NlB17ePxoOK8vk74wbG6NaBAJlX309vK"
}
Copy
Copied
PageableTransfers {
    items: [
        TransferItem {
            from: '0x76c6b1f34562ed7a843786e1d7f57d0d7948a6f1',
            to: '0x88ab3cdbf31f856de69be569564b751a97ddf5d8',
            transferType: 'nft',
            contract: [FtContract],
            transaction: [Transaction],
            tokenId: '0x7b'
        }
    ],
    cursor: 'bk8XJaEYv0P46ZA8kXLewmDBJVOKWzQ3dL3wPG8EYJDxqN5O9r2M4B0jLBubuAx1AZdbeJ6EbypQlaKVWZbd7vX1kAeozgm6r0G1qEalMN59pPY7bgxvo29BwxN1oArm'
}
Copy
Copied
class PageableTransfers {
    items: class TransferArray {
        [class NftTransfer {
            contract: class NftContract {
                address: 0xdb71dd9e38af6cb8fdd7cfe498c2337864d5a0f6
                name: GX_CARD_20200319110355
                symbol: GXC
                status: null
            }
            from: 0x0000000000000000000000000000000000000000
            to: 0x74f630bfcf6f3e8d7523b39de821b876446adbd4
            transaction: class Transaction {
                feePayer:
                feeRatio: 0
                fee: 0x0
                from: 0x34d962ddf56101f2203fe4f5818b3b3117259489
                timestamp: 1584583438
                transactionHash: 0x233eb685f778d0ed1f5d081cc278943f9e9d60f2a1b215786250f5943088aa7f
                typeInt: 48
                value: 0x0
            }
            transferType: nft
            tokenId: 0xba873
        }]
    }
    cursor: OMxbp2v3Qq4DlQ94KGkxM15mAYgpNbO6XK6NXmYopkZJQrlOA7LVaMGy26ueuzroaED9KEZJyx842BW39zEebDP1dwq50vg8daz7qBPEJVrZ0w2WoeL3vwE815WXK0Z9
}
info

"typeInt" variable is a value for identifying the transaction type. For details about the types of transactions, please visit here.

For details about this API, please visit here. For inquires about this document or KAS, please visit KAS Developers Forum.