Skip to main content

Advanced API Reference

This document describes Coinbase Node's Advanced API.

This API supplements the native Ethereum API. The Coinbase Node Advanced API simplifies access to blockchain data by offering data cuts which are hard to get via native Ethereum API methods, and offer aggregated and filtered data in one API call. The Advanced API provides access to token balances for accounts, transactions and transfers for accounts, smart contract event logs, and more.

API constraints:

  • Only Ethereum Mainnet and Goerli Testnet are supported in this version of the API. Ethereum L2 chains and other protocols will be supported incrementally.
  • This version of the API only supports ETH, ERC-20 and ERC-721 tokens.

Definitions

  • balance: Amount of a token, for Ethereum this is the amount of ETH in wei. For NFTs this is the number of NFTs.
  • contract: Also known as a "smart contract". A program that runs on a blockchain. Contracts are a type of account that have a balance and can send transactions.
  • contract address: The hash associated with a contract address. This page lists the most common tokens, where you can also find the associated addresses.
  • transaction: A cryptographically signed instruction that updates the state of the network. The action must be initiated by an externally-owned address, e.g. an account managed by a human.
  • internal transaction: An unsigned message carried out by a smart contract. A series of internal transactions originate from a transaction.
  • transfer: Refers to "token transfer", a transaction that transfers ERC-20 (Ethereum) or ERC-721 (NFT) tokens.
  • allowance: Also known as "access permissions to tokens". Allows a third party to carry out transactions of a given amount with a user's tokens.

Servers

The Advanced API supports the following blockchain networks:

NameEndpoint
Ethereum Mainnethttps://mainnet.ethereum.coinbasecloud.net
Goerli Testnethttps://goerli.ethereum.coinbasecloud.net

Authentication:

This endpoint uses HTTP Basic Auth.

To authenticate to this API:

  • Create a project in the Coinbase Cloud Console
  • Grab your project-specific API Access Token username and password from the project overview page
  • Include your username and password as auth in each HTTP request

Methods

coinbaseCloud_getBalances​

Get balance for multiple account addresses across one or more tokens within a single blockchain and network. The balance incorporates transactions, internal transfers and all supported token transfers. Supports ERC-20 and ERC-721. This API is meant to be our primary API to get balances. A more simple and lower latency API that just fetches balance for a single address and token is getSingleBalance.

Use cases:

  • Get balances for one or many addresses in a single call
  • Get balances for all the tokens an account address may hold
  • Get balances for all the tokens a contract may hold

Parameters​

NameTypeDescription
addressAndContractListAddressAndContract[]REQUIRED. List of account or contract addresses and token identifiers. For Ethereum the token identifier is the token contract address. Maximum limit of 100 addresses per request.

Returns​

TypeDescription
MultiTokenBalance[]A list of balance amounts for the given token identifiers and block range in which the balances were computed. Note that the start block is always genesis for this method.

Examples​

USDC & DAI (ERC-20)​

Retrieve balances for USDC and DAI. Note that this example shows how the Advanced API normalizes input and accepts long, mixed-case addresses.

curl https://mainnet.ethereum.coinbasecloud.net \
-u username:password \
-X POST \
-H 'Content-Type: application/json' \
-d '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "coinbaseCloud_getBalances",
  "params": {
    "addressAndContractList": [
      {
        "address": "0x00000000DF0635793e91d4f8e7426dbd9ed08471186f428D",
        "contract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
      },
      {
        "address": "0xdf0635793e91d4f8e7426dbd9ed08471186f428d",
        "contract": "0x6b175474e89094c44da98b954eedeac495271d0f"
      }
    ]
  }
}'
NFT (ERC-721)​
curl https://mainnet.ethereum.coinbasecloud.net \
-u username:password \
-X POST \
-H 'Content-Type: application/json' \
-d '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "coinbaseCloud_getBalances",
  "params": {
    "addressAndContractList": [
      {
        "address": "0xa3e90da6c1d5ea0b1b4e881d1eaaaaaaf3c25cc2",
        "contract": "0x5180db8F5c931aaE63c74266b211F580155ecac8"
      }
    ]
  }
}'

coinbaseCloud_getSingleBalance​

Get an accurate balance for a single token and a single account address. The balance takes into account transactions, internal transfers, and any supported token transfers. The caller can expect low latency from this method compared to the getBalances method.

Use cases:

  • Get balances for an account address or a contract

Parameters​

NameTypeDescription
addressStringREQUIRED. An account address or a contract address.
contractStringREQUIRED. Token identifier. For Ethereum the token identifier is the token contract address.

Returns​

TypeDescription
SingleBalanceBalance of the native cryptocurrency (ETH, BTC, etc.) for the blockchain and network: Amount and unit (e.g. Wei, satoshi). Balance is returned in the smallest possible unit. Currently only Wei. 1 ETH = 10^18 Wei.

Examples​

USDC (ERC-20)​

Retrieve balances for USDC. Note that this example shows how Advanced APIs normalize input and accept a long, mixed-case address.

curl https://mainnet.ethereum.coinbasecloud.net \
-u username:password \
-X POST \
-H 'Content-Type: application/json' \
-d '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "coinbaseCloud_getSingleBalance",
  "params": {
    "address": "0x00000000DF0635793e91d4f8e7426dbd9ed08471186f428D",
    "contract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
  }
}'
NFT (ERC-721)​

Retrieve NFT tokens.

curl https://mainnet.ethereum.coinbasecloud.net \
-u username:password \
-X POST \
-H 'Content-Type: application/json' \
-d '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "coinbaseCloud_getSingleBalance",
  "params": {
    "address": "0xa3e90da6c1d5ea0b1b4e881d1eaaaaaaf3c25cc2",
    "contract": "0x5180db8F5c931aaE63c74266b211F580155ecac8"
  }
}'

coinbaseCloud_getTokenAllowances​

Get allowances for a specified owner and spender across one or more tokens within a single blockchain and network.

Use cases:

  • Get allowance given to another account for one or more tokens
  • Get allowances for all the tokens an account address may hold

Parameters​

NameTypeDescription
allowancesAllowance[]REQUIRED. List of owner addresses, spender addresses, and token identifiers. For Ethereum, the token identifier is the token contract address. Maximum limit of 100 allowances per request.

Returns​

TypeDescription
TokenAllowance[]List of allowances, including owner address, spender address, the block range in which the balances were computed (start block is genesis), and a list of allowance information.

Examples​

USDT (ERC-20)​

Retrieve token allowances for USDT.

curl https://mainnet.ethereum.coinbasecloud.net \
-u username:password \
-X POST \
-H 'Content-Type: application/json' \
-d '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "coinbaseCloud_getTokenAllowances",
  "params": {
    "allowances": [
      {
        "owner": "0xa646147bda82a866eba03568f363fc9c90185c6e",
        "spender": "0xadd0e097b961572b2a1f5de572c622eef97e3d82",
        "contracts": [
          "0xdac17f958d2ee523a2206206994597c13d831ec7"
        ]
      }
    ]
  }
}'

coinbaseCloud_getTransactionsByAddress​

Get external transactions, internal transactions (triggered by smart contracts) and token transfers for a given address. Includes activity from and to the input address. Transactions are returned in reverse chronological order.

This API guarantees that all relevant transactions and transfers for a single block are returned in a single call.

Parameters​

NameTypeDescription
addressStringREQUIRED. Account address.
blockStartStringREQUIRED. Start of block range to scan for transactions.
blockEndStringEnd of block range to scan for transactions. Defaults to latest.
addressFilterStringFilter transactions by SENDER_ONLY, RECEIVER_ONLY, or SENDER_OR_RECEIVER. Defaults to SENDER_OR_RECEIVER.
sortStringThe sorting preference, use asc to sort by ascending and desc to sort by descending. The default is desc. Tip: Specify a smaller blockStart and blockEnd range for faster search results.
pageSizeIntegerThe number of transactions displayed per page. The default and max value are 1000. See Handle pagination.
pageNumberIntegerThe integer page number, if pagination is enabled. It starts with 1. See Handle pagination.

Returns​

TypeDescription
Transaction[]A list of transactions found for the address.

Examples​

ERC-20​

Retrieve transactions for ERC-20 tokens.

curl https://mainnet.ethereum.coinbasecloud.net \
-u username:password \
-X POST \
-H 'Content-Type: application/json' \
-d '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "coinbaseCloud_getTransactionsByAddress",
  "params": {
    "address": "0xcAfB10eE663f465f9d10588AC44eD20eD608C11e",
    "blockStart": "0x40f400",
    "blockEnd": "0xdc3501",
    "addressFilter": "SENDER_OR_RECEIVER"
  }
}'

coinbaseCloud_getTokenTransfersByAddress​

Get token transfers for a given address (in reverse chronological order). Includes activity from and to the input address.

Parameters​

NameTypeDescription
addressStringREQUIRED. Account address.
blockStartStringREQUIRED. Inclusive of specified block.
blockEndStringInclusive of specified block. Defaults to latest.
addressFilterStringFilter transactions by SENDER_ONLY, RECEIVER_ONLY, or SENDER_OR_RECEIVER. Defaults to SENDER_OR_RECEIVER.
sortStringThe sorting preference, use asc to sort by ascending and desc to sort by descending. The default is desc. Tip: Specify a smaller blockStart and blockEnd range for faster search results.
pageSizeIntegerThe number of transactions displayed per page. The default and max value are 1000. See Handle pagination.
pageNumberIntegerThe integer page number, if pagination is enabled. It starts with 1. See Handle pagination.

Returns​

TypeDescription
TokenTransfersByAddressA list of token transfers found for the address.

Examples​

ERC-20 and ERC-721 token transfers​

Return all ERC-20 and ERC-721 token transfers to the burn wallet.

curl https://mainnet.ethereum.coinbasecloud.net \
-u username:password \
-X POST \
-H 'Content-Type: application/json' \
-d '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "coinbaseCloud_getTokenTransfersByAddress",
  "params": {
    "address": "0x0000000000000000000000000000000000000000",
    "blockStart": "0x1",
    "blockEnd": "0x16bc50",
    "addressFilter": "RECEIVER_ONLY"
  }
}'
ERC-721 token transfers​

Return all ERC-721 token transfers to or from a given address.

curl https://mainnet.ethereum.coinbasecloud.net \
-u username:password \
-X POST \
-H 'Content-Type: application/json' \
-d '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "coinbaseCloud_getTokenTransfersByAddress",
  "params": {
    "address": "0x7be8076f4ea4a4ad08075c2508e481d6c946d12b",
    "blockStart": "0x1",
    "blockEnd": "0xdb0db3",
    "addressFilter": "SENDER_OR_RECEIVER"
  }
}'

coinbaseCloud_getTransactionByHash​

Get detailed information about a transaction, including all internal transactions and token transfers that were triggered by the transaction.

Use cases:

  • Get complete data for a transaction
  • Get all the internal transactions and token transfers triggered by a transaction

Constraints:

  • Static calls among smart contracts can result in zero balance transfers in Ethereum. Such transfers are excluded from the output.
  • This method doesn't currently support pagination. All the data for the transaction will be returned in a single call.

Parameters​

NameTypeDescription
transactionHashStringREQUIRED. Transaction hash.

Returns​

TypeDescription
TransactionThe given transaction with all associated internal transactions and token transfers.

Examples​

ETH transfer​
curl https://mainnet.ethereum.coinbasecloud.net \
-u username:password \
-X POST \
-H 'Content-Type: application/json' \
-d '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "coinbaseCloud_getTransactionByHash",
  "params": {
    "transactionHash": "0x2be70b2bcff662ba941c3f3c7706ef2c674d0d0ea4a13a91543cbe18862063d4"
  }
}'
ERC-721 transfer​
curl https://mainnet.ethereum.coinbasecloud.net \
-u username:password \
-X POST \
-H 'Content-Type: application/json' \
-d '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "coinbaseCloud_getTransactionByHash",
  "params": {
    "transactionHash": "0x30eda1f9a9d1ec16be8802d2332c7696bd25897eab15ad0269f8e73ed9a9e2b9"
  }
}'
ERC-20 swap​

Return transactions resulting from an ERC-20 swap.

curl https://mainnet.ethereum.coinbasecloud.net \
-u username:password \
-X POST \
-H 'Content-Type: application/json' \
-d '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "coinbaseCloud_getTransactionByHash",
  "params": {
    "transactionHash": "0xf21640da131e6cabb14fa291d0d95ca08a8c5aadb6548c5234f11dd8361b3693"
  }
}'
ERC-721 sale​

Return transactions resulting from an ERC-721 sale.

curl https://mainnet.ethereum.coinbasecloud.net \
-u username:password \
-X POST \
-H 'Content-Type: application/json' \
-d '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "coinbaseCloud_getTransactionByHash",
  "params": {
    "transactionHash": "0x48db4231fb7de49b624f0860fed5f459ca7231ff1f22ef58f00c1cefd6e454ef"
  }
}'

coinbaseCloud_getTokenStandardEvents​

Get events triggered by the given token contract. The event data is returned in an easy-to-read format. Only supports events defined by Ethereum standards for ERC-20 and ERC-721 tokens.

Different event types will return different event data.

Parameters​

NameTypeDescription
contractStringREQUIRED. The token contract.
blockStartStringREQUIRED. Start of block range to scan for transactions.
blockEndStringEnd of block range to scan for transactions. Defaults to latest.
eventSignatureHashesString[]List of event signature hashes. Defaults to all standard events for ERC-20/ERC-721 (Transfer, Approval, ApprovalForAll)
sortStringThe sorting preference, use asc to sort by ascending and desc to sort by descending. The default is desc. Tip: Specify a smaller blockStart and blockEnd range for faster search results.
pageSizeIntegerThe number of transactions displayed per page. The default and max value are 1000. See Handle pagination.
pageNumberIntegerThe integer page number, if pagination is enabled. It starts with 1. See Handle pagination.

Returns​

TypeDescription
TokenStandardEventsA list of parent transactions in the given block range, each with a sub-list of events that occurred as part of the parent transaction. Note: The output does not specify the token type (ERC20 vs ERC721).

Examples​

ERC 721​

Retrieve events triggered by the token contract address.

curl https://mainnet.ethereum.coinbasecloud.net \
-u username:password \
-X POST \
-H 'Content-Type: application/json' \
-d '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "coinbaseCloud_getTokenStandardEvents",
  "params": {
    "contract": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
    "blockStart": "0x1",
    "blockEnd": "0xf19ddf",
    "eventSignatureHashes": [
      "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
    ]
  }
}'

coinbaseCloud_getTokenMetadata​

Get metadata for the given token contract address.

Constraints:

  • Only ERC20 and ERC721 token standards are supported. More (e.g. ERC1155) will be added incrementally.

Parameters​

NameTypeDescription
contractStringREQUIRED. The token contract.

Returns​

TypeDescription
TokenContractMetadataToken metadata (ERC-20 or ERC-721) based on the input.

Examples​

USDC (ERC-20)​

Retrieve token metadata for USDC.

curl https://mainnet.ethereum.coinbasecloud.net \
-u username:password \
-X POST \
-H 'Content-Type: application/json' \
-d '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "coinbaseCloud_getTokenMetadata",
  "params": {
    "contract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
  }
}'
NFT (ERC-721)​

Retrieve token metadata for an NFT.

curl https://mainnet.ethereum.coinbasecloud.net \
-u username:password \
-X POST \
-H 'Content-Type: application/json' \
-d '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "coinbaseCloud_getTokenMetadata",
  "params": {
    "contract": "0x1A92f7381B9F03921564a437210bB9396471050C"
  }
}'

Types

AddressAndContract​

Properties​

NameTypeDescription
addressStringREQUIRED. Account address.
contractStringREQUIRED. Token identifier.

Example​

JSON
{
  "address": "0x00000000DF0635793e91d4f8e7426dbd9ed08471186f428D",
  "contract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
}

MultiTokenBalance​

Properties​

NameTypeDescription
blockHeightStringREQUIRED. The end block in which the balances were computed. The start block is genesis.
addressStringREQUIRED. Account address.
nativeAmountStringREQUIRED. Balance of the native cryptocurrency (ETH, BTC, etc) for the blockchain and network. Balance is returned in the smallest possible unit. 1 ETH = 10^18 Wei.
nativeUnitStringREQUIRED. Unit the balance is returned in. Currently Wei-only.
tokenBalancesTokenBalance[]REQUIRED. The token balances.

Example​

JSON
{
  "blockHeight": "0xea6204",
  "address": "0xdf0635793e91d4f8e7426dbd9ed08471186f428d",
  "nativeAmount": "0x1a06c95fd28d60",
  "nativeUnit": "Wei",
  "tokenBalances": [
    {
      "contract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "amount": "0x579dd3c7",
      "decimals": 6
    },
    {
      "contract": "0x6b175474e89094c44da98b954eedeac495271d0f",
      "amount": "0x7b5053643c5fcb0c",
      "decimals": 18
    }
  ]
}

SingleBalance​

Properties​

NameTypeDescription
blockHeightStringREQUIRED. The end block in which the balances were computed. The start block is genesis.
addressStringREQUIRED. Account address.
nativeAmountStringREQUIRED. Balance of the native cryptocurrency (ETH, BTC, etc) for the blockchain and network. Balance is returned in the smallest possible unit. 1 ETH = 10^18 Wei.
nativeUnitStringREQUIRED. Unit the balance is returned in. Currently Wei-only.
tokenBalanceTokenBalanceThe token balance.

Example​

JSON
{
  "blockHeight": "0xea620e",
  "address": "0xdf0635793e91d4f8e7426dbd9ed08471186f428d",
  "nativeAmount": "0x1a06c95fd28d60",
  "nativeUnit": "Wei",
  "tokenBalance": {
    "contract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "amount": "0x579dd3c7",
    "decimals": 6
  }
}

Allowance​

Properties​

NameTypeDescription
ownerStringREQUIRED. The owner address.
spenderStringREQUIRED. The spender address.
contractsString[]REQUIRED. List of contract addresses.

Example​

JSON
{
  "owner": "0xa646147bda82a866eba03568f363fc9c90185c6e",
  "spender": "0xadd0e097b961572b2a1f5de572c622eef97e3d82",
  "contracts": [
    "0xdac17f958d2ee523a2206206994597c13d831ec7"
  ]
}

TokenAllowance​

Properties​

NameTypeDescription
blockHeightStringREQUIRED. The end block in which the balances were computed. The start block is genesis.
ownerStringREQUIRED. The owner address.
spenderStringREQUIRED. The spender address.
tokenAllowancesTokenBalance[]REQUIRED. List of token balances.

Example​

JSON
{
  "blockHeight": "0xea613d",
  "owner": "0xa646147bda82a866eba03568f363fc9c90185c6e",
  "spender": "0xadd0e097b961572b2a1f5de572c622eef97e3d82",
  "tokenAllowances": [
    {
      "contract": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      "amount": "411256436224324320870982430867023952481793415358246197400146659",
      "decimals": 6
    }
  ]
}

Transaction​

Properties​

NameTypeDescription
transactionHashStringREQUIRED. The transaction hash.
transactionIndexStringREQUIRED. The transaction index.
fromStringREQUIRED. The origin address.
toStringREQUIRED. The destination address.
valueStringREQUIRED. The value in native blockchain currency.
gasLimitStringREQUIRED. The maximum gas limit of a transaction.
gasPriceStringREQUIRED. Transaction's cost per unit of gas in native blockchain currency.
gasUsedStringREQUIRED. Amount of gas actually used in transaction.
cumulativeGasUsedStringREQUIRED. Total amount of gas used in the block of the transaction.
statusStringREQUIRED. "1": Success, "0": Fail, Other return codes: Unknown.
inputStringREQUIRED. Transaction's input data.
nonceStringREQUIRED. Transaction's nonce.
blockHashStringREQUIRED. The block hash.
blockNumberStringREQUIRED. the block number.
blockTimestampStringREQUIRED. Timestamp of when block was mined.
internalTransactionsInternalTransaction[]List of internal transactions.
tokenTransfersTokenTransfer[]List of token transfers.

Example​

JSON
{
  "transactionHash": "0x07160e2164087a3812abbe5e74109be176b0650bbe4be44f4e280fe3ee221a6d",
  "transactionIndex": "0x3d",
  "from": "0x3cd751e6b0078be393132286c442345e5dc49699",
  "to": "0x912a523a10e052900b571889b07ff4f2fd86e029",
  "value": "0x23047718e2a9800",
  "gasLimit": "0x5208",
  "gasPrice": "0x82c6fff33",
  "gasUsed": "0x5208",
  "cumulativeGasUsed": "0x443cc1",
  "status": "0x1",
  "input": "0x",
  "nonce": "0x686b29",
  "blockHash": "0x2c52d4bb68c6e56272974d21bd5afc7a01ec33093249d9d5ec0b74048a8389d5",
  "blockNumber": "0xdc3501",
  "blockTimestamp": "0x6238ccde"
}

TokenTransfersByAddress​

Properties​

NameTypeDescription
tokenTransfersTokenTransfer[]REQUIRED. List of token transfers.

Example​

JSON
{
  "tokenTransfers": [
    {
      "tokenAddress": "0x7789d991d2552f94066a9b273cd65c8cd763c227",
      "tokenType": "erc20",
      "from": "0xa044efd7b193444ced74a521a6104f7920d436fd",
      "to": "0x0000000000000000000000000000000000000000",
      "value": "0x3",
      "transactionHash": "0xa3ee71f1a4b50f4ea1dc163d6a8419ed4c3f17768e190a9602548724dea67486",
      "transactionIndex": "0x5",
      "blockHash": "0x496788c88b61a1c74a2f06af3e42ac7eba356a938de86e492084229c33ae90e0",
      "blockNumber": "0x165e2c",
      "blockTimestamp": "0x572c3095"
    },
    {
      "tokenAddress": "0xd25753116e068eeb7a1f8d11370aa6794c73728c",
      "tokenType": "erc20",
      "from": "0xd25753116e068eeb7a1f8d11370aa6794c73728c",
      "to": "0x0000000000000000000000000000000000000000",
      "value": "0x0",
      "transactionHash": "0x1b7b06f8bef5e032183dfed1f733dbd3fa54c496c470fa6c849c47da0ea2233f",
      "transactionIndex": "0x13",
      "blockHash": "0x138efe004f40abeb4b00ca68034add511f9313dc3cfea66b574133c7ceeebf59",
      "blockNumber": "0x15ee0e",
      "blockTimestamp": "0x5725e384"
    },
    {
      "...": "output truncated."
    }
  ]
}

TokenStandardEvents​

Properties​

NameTypeDescription
eventsTokenEvent[]REQUIRED. List of token events.

Example​

JSON
{
  "events": [
    {
      "transactionHash": "0x39874e4397b79c40e9331e9295c91c89549964065ecd007cf1387ae422979ca1",
      "transactionIndex": "0x82",
      "data": {
        "data": "0",
        "from": "0xd4fb8a295c9ddc47063f4c83bab973e6140a42d8",
        "name": "Transfer",
        "to": "0x66362b929c1a9aaf14c51aab9b455ad7fb8268c4"
      },
      "eventType": "Transfer",
      "signature": "Transfer(address, address, uint256)",
      "signatureHash": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
      "blockHash": "0x2d833e257a32eb8b8fe1aa0ed2962b0db9bf9a7e0d6edbd679a5ef9d136c60e5",
      "blockNumber": "0xf19d33",
      "blockTimestamp": "0x63598e0b"
    },
    {
      "...": "output truncated."
    }
  ]
}

TokenContractMetadata​

Properties​

NameTypeDescription
blockHeightStringREQUIRED. The end block in which the balances were computed. The start block is genesis.
tokenMetadataTokenMetadataREQUIRED. Metadata for a token.

Example​

JSON
{
  "blockHeight": "0xea62cc",
  "tokenMetadata": {
    "name": "USD Coin",
    "symbol": "USDC",
    "totalSupply": "0x9e6738b1ff926e",
    "decimals": 6
  }
}

TokenBalance​

Properties​

NameTypeDescription
contractStringREQUIRED. Token identifier.
amountStringREQUIRED. Balance Amount (For ERC-721 it is the number of tokens).
decimalsIntegerREQUIRED. Unit (decimals for ERC-20).

Example​

JSON
{
  "contract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "amount": "0x579dd3c7",
  "decimals": 6
}

InternalTransaction​

Properties​

NameTypeDescription
traceTypeStringREQUIRED. Type of internal transaction, e.g. CREATE, CALL, CALLCODE, DELEGATECALL, SUICIDE
fromStringREQUIRED. The origin address.
toStringREQUIRED. The destination address.
valueStringREQUIRED. The value in native blockchain currency.
gasLimitStringThe maximum gas limit of a transaction.

Example​

JSON
{
  "traceType": "CALL_0",
  "from": "0x00000000a50bb64b4bbeceb18715748dface08af",
  "to": "0x7f268357a8c2552623316e2562d90e642bb538e5",
  "value": "0x2386f26fc10000",
  "gasLimit": "0x3196d"
}

TokenTransfer​

Properties​

NameTypeDescription
tokenAddressStringREQUIRED. Address location for the token contract
tokenTypeStringREQUIRED. "erc20" or "erc721"
fromStringREQUIRED. The origin address.
toStringREQUIRED. The destination address.
valueStringREQUIRED. For ERC-20, gives quantity of tokens transferred. For ERC-721, gives list of token IDs of the token transferred
transactionHashStringREQUIRED. The transaction's identifying hash
transactionIndexStringREQUIRED. The transaction's index position
blockHashStringREQUIRED. The block hash.
blockNumberStringREQUIRED. the block number.
blockTimestampStringREQUIRED. Timestamp of when block was mined.

Example​

JSON
{
  "tokenAddress": "0x0da642e3ed481b119cc212b6f1c9bef04e3211ab",
  "tokenType": "erc721",
  "from": "0xaf5760607ead7e0a152f8b9987e95174fc32af70",
  "to": "0xf88ad3b265a92acfc9f7157f927950dc5317cae5",
  "tokenID": "1081",
  "value": "0x0",
  "transactionHash": "0xdd0971856280e6e4db0ce31072b9780c4c3f96d70351d5b7ef3edf924583d2c6",
  "transactionIndex": "0x60",
  "blockHash": "0x496788c88b61a1c74a2f06af3e42ac7eba356a938de86e492084229c33ae90e0",
  "blockNumber": "0x165e2c",
  "blockTimestamp": "0x572c3095"
}

TokenEvent​

Properties​

NameTypeDescription
transactionHashStringREQUIRED. The transaction hash.
transactionIndexStringThe transaction index.
dataTokenEventDataREQUIRED. Data returned for specific transaction. Returns different properties based on event type, see examples.
eventTypeStringREQUIRED. Transfer (ERC-20 and ERC-721), Approval (ERC-20 and ERC-721), or ApprovalForAll (ERC-721 only). Defaults to hashed signature if not one of the previous.
signatureStringREQUIRED. Method signature for the event type
signatureHashStringREQUIRED. Hash of the event signature
blockHashStringREQUIRED. The block hash.
blockNumberStringREQUIRED. the block number.
blockTimestampStringREQUIRED. Timestamp of when block was mined.

Example​

JSON
{
  "transactionHash": "0xe11f4b1dd9fbd62b5a4afe11a6f6289e4d90ba5aaf04ce75ff2031b9ebe39fa5",
  "transactionIndex": "0x307830",
  "data": {
    "data": "514711238152814592",
    "from": "0x00000000003b3cc22af3ae1eac0440bcee416b40",
    "name": "Transfer",
    "to": "0x8aa34c7866da901b3b55d162821ef3dae87851f3"
  },
  "eventType": "Transfer",
  "signature": "Transfer(address, address, uint256)",
  "signatureHash": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
  "blockHash": "0x801b8afac89d96d9c6f054275bc9fc0274c831372603dc34aae7401931f58849",
  "blockNumber": "0xe04dbd",
  "blockTimestamp": "0x62702704"
}

TokenMetadata​

Properties​

NameTypeDescription
nameStringREQUIRED. Name of token
symbolStringREQUIRED. Symbol for token
totalSupplyStringREQUIRED. Total amount of token
decimalsIntegerNumber of decimals

Example​

JSON
{
  "name": "USD Coin",
  "symbol": "USDC",
  "totalSupply": "0x9e6738b1ff926e",
  "decimals": 6
}

TokenEventData​

Properties​

NameTypeDescription
dataStringFor ERC-20 this represents the value. For ERC-721 this represents the token id.
fromStringThe origin address.
nameStringREQUIRED. Name of the event type, e.g. Transfer, Approval.
toStringThe destination address.
ownerStringToken owner address.
spenderStringToken spender address.
operatorStringToken operator address.
approvedBooleantrue when operator receives approval, false when approval is revoked.
topicsStringStringified array. topics[0] is the hashed event signature. Other entries in the array may include to and from addresses.

Example​

JSON
{
  "data": "514711238152814592",
  "from": "0x00000000003b3cc22af3ae1eac0440bcee416b40",
  "name": "Transfer",
  "to": "0x8aa34c7866da901b3b55d162821ef3dae87851f3"
}

Was this helpful?