Skip to main content

​
Description

The Transfers suite provides access to token transfer events produced by the TokenTransfersEngine. You can query all transfer types in one call via the unified endpoint, or use type-specific endpoints for a single asset kind. All endpoints share the same request shape (chain, block or time range, optional address filters, pagination) and return a consistent record format with lineage fields.

​
Endpoint Matrix

EndpointSummaryTransfer typesTypical use
POST /evm/transfers/token-transfersAll transfer types in one response; filter by transfer_typenative_tx, native_internal, erc20, erc721, erc1155Single request for mixed or full activity
POST /evm/transfers/native-transfersNative network token (e.g. ETH) onlynative_tx, native_internalGas and value flows
POST /evm/transfers/erc20-transfersERC-20 Transfer events onlyerc20Fungible token movements
POST /evm/transfers/erc721-transfersERC-721 Transfer/TransferSingle events onlyerc721NFT ownership changes
POST /evm/transfers/erc1155-transfersERC-1155 TransferSingle/Batch onlyerc1155Multi-token and semi-fungible transfers

​
Parameter Conventions

​
chain_id
number
required
Target EVM network. See Chain for supported values.
​
from_block
number
Starting block number (inclusive). Use with to_block.
​
to_block
number
Ending block number (inclusive). Use with from_block.
​
from_timestamp
string
Starting timestamp (ISO-8601). Use with to_timestamp; mutually exclusive with block range.
​
to_timestamp
string
Ending timestamp (ISO-8601). Use with from_timestamp.
​
from_address
string
Filter by sender address (hex, 20 bytes, no 0x prefix).
​
to_address
string
Filter by recipient address (hex, 20 bytes, no 0x prefix).
​
token_address
string
Filter by token contract (hex, 20 bytes). For native endpoint, omit or leave unset.
​
limit
number
default:"250"
Page size; max 1000. Stays under ~10 MB when combined with narrow ranges.
​
cursor
string
Pagination cursor from a previous response.

​
Usage Guidance

  • One type, one endpoint — Use /erc20-transfers, /erc721-transfers, /erc1155-transfers, or /native-transfers when you only need that asset type; aligns with Entities (tokens by type).
  • Mixed or “all” in one call — Use /token-transfers with optional transfer_type filter to get multiple or all types in a single request (one API call under PAYG).
  • Narrow by address — Use from_address / to_address and optionally token_address to reduce payload and cost.
  • Join with entities — Use token_address with ERC-20, ERC-721, or ERC-1155 token metadata for symbols and decimals.

​
Common Patterns

ERC-20 transfers for a wallet: 
{
  "chain_id": 1,
  "from_block": 12345678,
  "to_block": 12345999,
  "to_address": "0000000000000000000000000000000000000001",
  "limit": 250
}
NFT (ERC-721) transfers for a collection: 
{
  "chain_id": 1,
  "from_timestamp": "2025-01-01T00:00:00Z",
  "to_timestamp": "2025-01-31T23:59:59Z",
  "token_address": "bc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
  "limit": 250
}
Native ETH only (no token contract): 
{
  "chain_id": 1,
  "from_block": 12345678,
  "to_block": 12345999,
  "from_address": "0000000000000000000000000000000000000000",
  "limit": 250
}
All transfer types in one request: 
{
  "chain_id": 1,
  "from_block": 12345678,
  "to_block": 12345999,
  "limit": 250
}

​
Dataset & Relationships

  • Dataset ID: 0304 — blockdb_evm.b0304_token_transfers_v1
  • Transfers → Transactions: Join on (block_number, tx_index) to transactions
  • Transfers → Tokens: Join token_address to ERC-20, ERC-721, or ERC-1155 for metadata

​
See Also