NFT Transfers

Question it answers

“Give me every NFT transfer: by contract 0x…, by wallet 0x…, or for a single (contract, token_id).”

A single recipe serves all three access paths. It mirrors the on-chain subset of Moralis GET /nft/{address}/transfers (by contract), GET /{address}/nft/transfers (by wallet), and GET /nft/{address}/{token_id}/transfers (single token). It carries no off-chain enrichment: the source array has no collection metadata or address labels (see Fidelity gaps).

What you get

One row per NFT transfer, mapped straight from Moralis-indexed, normalized per-block onchain data:

Column	Description
`token_address`	The NFT contract that emitted the transfer
`token_id`	The token id, a `uint256` big decimal stored as text (never numeric); compare as strings
`from_address`, `to_address`	The two sides of the transfer
`amount`	The ERC-1155 quantity (`1` for ERC-721)
`contract_type`	`ERC721` or `ERC1155` (the emitted `tokenType`)
`initiated_by`	The address that initiated the transfer
`tx_hash`	Transaction that produced the transfer
`block_number`, `transaction_index`, `log_index`	On-chain ordering tuple
`block_timestamp`	Block time

Source

The transform reads one per-block array and lands one row per transfer: nftTokenTransfers Fields map straight from the source struct: tokenAddress, tokenId (as a string), fromAddress, toAddress, amount, tokenType (→ contract_type), and initiatedBy. There’s no price or metadata join; this is a flat event stream.

Destination

Destination	Table	Read pattern
ClickHouse (first-class)	`fact_nft_transfers`	Prefix scan on `(chain_id, token_address, token_id, block_number)`; by-wallet via `bloom_filter` skip indexes; read with `FINAL` or `sum(sign)`
Postgres	`nft_transfers`	Index on `(token_address, block_number DESC)`, `(token_address, token_id, block_number DESC)`, and `(from_address, …)` / `(to_address, …)`
MySQL	`nft_transfers`	Same composite indexes (ascending)

ClickHouse uses the collapsing log-table pattern (see the recipes overview) so chain reorganizations self-correct: the +1/−1 reorg pair for a row shares an identical key and collapses cleanly. The fact table’s sort key is contract-first, so by-contract is a prefix scan on token_address and by-token-id a prefix scan on (token_address, token_id). By-wallet reads are served by bloom_filter data-skipping indexes on from_address and to_address.

Full schema

Below is the complete read table this recipe produces. Keep the columns you need and drop the rest (see Schema & flexibility). token_id and amount are stored at full uint256 width: token_id as text (hash-derived ENS / ERC-1155 ids routinely exceed any SQL numeric precision), amount as a wide decimal.

ClickHouse, fact_nft_transfers

CREATE TABLE recipe_nft_transfers.fact_nft_transfers
(
    vendor_event_id     String,
    ingested_at         DateTime64(3),
    chain_id            UInt32,
    block_hash          String,
    block_number        UInt64,
    event_ts            DateTime64(3),
    token_address       String,
    token_id            String,        -- uint256 big decimal, NEVER numeric
    from_address        String,
    to_address          String,
    amount              String,        -- ERC-1155 quantity (1 for ERC-721)
    contract_type       LowCardinality(String),  -- ERC721 | ERC1155
    initiated_by        String,
    tx_hash             String,
    log_index           Nullable(UInt32),
    transaction_index   Nullable(Int32),
    sign                Int8,
    -- by-wallet skip indexes: prune granules that cannot contain the wallet.
    INDEX bf_from from_address TYPE bloom_filter(0.01) GRANULARITY 4,
    INDEX bf_to   to_address   TYPE bloom_filter(0.01) GRANULARITY 4
)
ENGINE = ReplicatedCollapsingMergeTree(
    '/clickhouse/tables/{database}/fact_nft_transfers', '{replica}', sign)
PARTITION BY (chain_id, toYYYYMM(event_ts))
ORDER BY (chain_id, token_address, token_id, block_number, vendor_event_id);

The sign column drives reorg collapsing: read with FINAL or sum(sign), never a bare WHERE sign = 1. A single-node setup can use CollapsingMergeTree(sign) without the replication path.

Postgres, nft_transfers

CREATE TABLE public.nft_transfers (
  position           BIGINT      NOT NULL,
  log_index          BIGINT,
  transaction_index  BIGINT,
  block_number       BIGINT      NOT NULL,
  block_timestamp    BIGINT      NOT NULL,    -- unix seconds
  tx_hash            TEXT        NOT NULL,
  vendor_event_id    TEXT        NOT NULL,
  token_address      TEXT        NOT NULL,
  token_id           TEXT        NOT NULL,    -- uint256 big decimal, NEVER numeric
  from_address       TEXT        NOT NULL,
  to_address         TEXT        NOT NULL,
  amount             NUMERIC(76, 0)  NOT NULL,
  contract_type      TEXT        NOT NULL,    -- ERC721 | ERC1155
  initiated_by       TEXT        NOT NULL
);

-- By-contract access (the recipe's primary purpose).
CREATE INDEX IF NOT EXISTS nft_transfers_token_block_idx
  ON public.nft_transfers (token_address, block_number DESC);
-- By-token-id access (single NFT provenance).
CREATE INDEX IF NOT EXISTS nft_transfers_token_id_block_idx
  ON public.nft_transfers (token_address, token_id, block_number DESC);
-- By-wallet access (either side).
CREATE INDEX IF NOT EXISTS nft_transfers_from_block_idx
  ON public.nft_transfers (from_address, block_number DESC);
CREATE INDEX IF NOT EXISTS nft_transfers_to_block_idx
  ON public.nft_transfers (to_address, block_number DESC);
-- Block-range helper.
CREATE INDEX IF NOT EXISTS nft_transfers_block_idx
  ON public.nft_transfers (block_number);

MySQL is the same shape with VARCHAR(80) for token_id and equivalent ascending composite keys. position is the block-level cursor used during backfill.

Example reads

All transfers of an NFT contract, newest first (ClickHouse):

SELECT block_number, token_id, from_address, to_address, amount, contract_type, tx_hash
FROM recipe_nft_transfers.fact_nft_transfers FINAL
WHERE chain_id = 1 AND token_address = lower('0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D')
ORDER BY block_number DESC
LIMIT 50;

Provenance of a single token (contract + token_id):

SELECT block_number, from_address, to_address, amount, tx_hash
FROM recipe_nft_transfers.fact_nft_transfers FINAL
WHERE chain_id = 1 AND token_address = lower('0xBC4C...') AND token_id = '1234'
ORDER BY block_number DESC
LIMIT 50;

All NFT transfers involving a wallet (either side), bloom-pruned:

SELECT block_number, token_address, token_id, from_address, to_address, amount
FROM recipe_nft_transfers.fact_nft_transfers FINAL
WHERE chain_id = 1
  AND (from_address = lower('0x...') OR to_address = lower('0x...'))
ORDER BY block_number DESC
LIMIT 50;

Modes

Shipped defaults: ClickHouse hybrid (backfill → realtime), Postgres / MySQL historical (one-shot backfill). For live/reorg-safe ingestion, use ClickHouse (see the overview).

The realtime reorg path needs a single-column UNIQUE on the position column, but position is block-level (many transfers share one block), so array-expanded transfer rows can only carry a composite unique. Run realtime / hybrid on ClickHouse: its log table corrects reorgs per-block via the collapsing companion table. The Postgres / MySQL shapes here are intended for historical backfill.

Multichain

The recipe is chain-parametrized: point it at any supported EVM chain or Solana. On Solana the same logIndex can be assigned to multiple events in one instruction, so the event identity is widened with (from_address, to_address, token_address, token_id, amount) to keep rows distinct; the transfer log it produces is identical in shape.

Fidelity gaps

The recipe lands only what the nftTokenTransfers array carries. Fields a Moralis NFT transfers endpoint surfaces that have no onchain source in this array are omitted:

Collection metadata (token_name, token_symbol): these come from the NFT contract / a metadata indexer, not the transfer event. Out of scope for a flat transfer log; see NFT Collection Metadata for the contract-metadata pattern.
Address labels / entity tags (from_address_label, to_address_entity, …): off-chain labels from a separate labelling service, not on-chain data.
value: the native value attached to the transfer transaction isn’t carried on the transfer event; omitted. amount (the ERC-1155 quantity) is present.
Pre/post NFT balances: the recipe omits the balance surface to stay a flat event stream.

Migrating from the REST API

This recipe replaces the wallet NFT transfers REST endpoint. Data Feeds are not 1:1 replicas of the old responses: you land the underlying data in your own database and reconstruct the response shape with a query. Below: what replaces the endpoint, the field mapping (exact = straight from the chain, calculated = derived from real trades, very close, add yourself = off-chain signal not in the feed), and the endpoint-specific gotchas.

GET /:address/nft/transfers

A wallet’s NFT transfer history. Replaced by this recipe’s nft_transfers table: a wallet’s transfers are the rows where it appears on either side, and the old endpoint’s contract_addresses, from_block/to_block, and order parameters become plain WHERE / ORDER BY clauses.

Reproducing the full REST response needs three recipes, not one. The transfer event carries no collection metadata or sale context. Run this recipe plus NFT Collection Metadata (token_name / token_symbol) and NFT Trades (last_sale) against the same database and join them.

`/:address/nft/transfers`	Data Feeds	Fidelity
`token_address`, `token_id`, `contract_type`	`nft_transfers.*`	exact
`from_address`, `to_address`, `amount`	`nft_transfers.*`	exact
`operator`	`nft_transfers.initiated_by`	exact
`transaction_hash`, `block_number`, `block_timestamp`, `transaction_index`, `log_index`	`nft_transfers.tx_hash` / `nft_transfers.*`	exact
`value` (tx native value), `transaction_type` (Single/Batch)	the `nftTokenTransfers` source array, not the flat table (or `nftTrades` for sale price)	exact
`token_name`, `token_symbol`	`nft_collection_metadata.*`	exact
`last_sale` (sale facts)	`nftTrades`	exact
`last_sale` USD values	`nftTrades` + price feed	calculated
`possible_spam`, `verified_collection`	add yourself	off-chain
`from/to_address_label`, `_entity`, `_entity_logo`	add yourself	off-chain

The reconstruction query (Postgres; adapt to your destination):

SELECT t.*,
       c.name AS token_name, c.symbol AS token_symbol,
       CASE WHEN t.from_address = lower('0xWALLET') THEN 'send' ELSE 'receive' END AS direction
FROM nft_transfers t
LEFT JOIN nft_collection_metadata c ON c.token_address = t.token_address
WHERE (t.from_address = lower('0xWALLET') OR t.to_address = lower('0xWALLET'))
ORDER BY t.block_number DESC, t.log_index DESC
LIMIT 100;

Gotchas

Direction is yours to derive: the feed has no send/receive flag; compare the wallet to from_address/to_address as above. The recipe indexes both sides, so the OR match stays fast.
The address labels and spam/verification flags are off-chain signals with no onchain source: drop them, bring your own lists, or layer in a label source.
token_id is a uint256 stored as text; compare as strings, never as numbers.
Backfill depth is your choice: transfers are an event list, not current state, so index only as much history as your app serves.

NFT Trades

Marketplace sales with price, the trade-priced complement to raw transfers.

NFT Marketplace

The use case these NFT recipes power.

Getting Started

Access Methods

Data APIs & Migration Guides

Streams

Gotchas & Troubleshooting

Concepts

Use Cases

Question it answers

What you get

Source

Destination

Full schema

Example reads

Modes

Multichain

Fidelity gaps

Migrating from the REST API

GET /:address/nft/transfers

NFT Trades

NFT Marketplace

​Question it answers

​What you get

​Source

​Destination

​Full schema

​Example reads

​Modes

​Multichain

​Fidelity gaps

​Migrating from the REST API

​GET /:address/nft/transfers

​Related

NFT Trades

NFT Marketplace

Question it answers

What you get

Source

Destination

Full schema

Example reads

Modes

Multichain

Fidelity gaps

Migrating from the REST API

GET /:address/nft/transfers

Related