Skip to main content

Transfers Examples

Worked walkthrough​

Find one suspicious transfer, then chase its receipt​

Use this when the user story is “I know funds moved, but I want the exact execution anchor behind that movement without dragging in the whole account history yet.”

Strategy

Stay narrow on movement first, then pivot once into execution history.

01POST /v0/transfers gives you the tight outgoing window and the specific movement worth chasing.

02jq lifts one receipt_id without dragging in the rest of the account history.

03POST /v0/receipt turns that movement into one execution anchor you can keep following in /tx.

What you're doing

  • Query a bounded outgoing transfer window for one account on mainnet.
  • Pull out one transfer that looks like the movement you care about.
  • Reuse its receipt_id in Transactions API to move from balance movement into execution history.
TRANSFERS_BASE_URL=https://transfers.main.fastnear.com
TX_BASE_URL=https://tx.main.fastnear.com
ACCOUNT_ID=YOUR_ACCOUNT_ID
FROM_TIMESTAMP_MS=1711929600000
TO_TIMESTAMP_MS=1712016000000

RECEIPT_ID="$(
  curl -s "$TRANSFERS_BASE_URL/v0/transfers" \
    -H 'content-type: application/json' \
    --data "$(jq -nc \
      --arg account_id "$ACCOUNT_ID" \
      --argjson from_timestamp_ms "$FROM_TIMESTAMP_MS" \
      --argjson to_timestamp_ms "$TO_TIMESTAMP_MS" '{
        account_id: $account_id,
        direction: "sender",
        from_timestamp_ms: $from_timestamp_ms,
        to_timestamp_ms: $to_timestamp_ms,
        desc: true,
        limit: 10
      }')" \
    | tee /tmp/transfers-window.json \
    | jq -r '.transfers[0].receipt_id'
)"

jq '{
  resume_token,
  transfers: [
    .transfers[]
    | {
        transaction_id,
        receipt_id,
        asset_id,
        amount,
        other_account_id,
        block_height
      }
  ]
}' /tmp/transfers-window.json

curl -s "$TX_BASE_URL/v0/receipt" \
  -H 'content-type: application/json' \
  --data "$(jq -nc --arg receipt_id "$RECEIPT_ID" '{receipt_id: $receipt_id}')" \
  | jq '{
      receipt_id: .receipt.receipt_id,
      transaction_hash: .receipt.transaction_hash,
      receiver_id: .receipt.receiver_id,
      tx_block_height: .receipt.tx_block_height
    }'

Why this next step?

The transfer query answers the first question quickly: did this account send funds in this window, and to whom? Looking up the receipt_id gives you the exact execution anchor for that movement without dragging in the whole account history yet. If you still need more rows afterward, keep paginating with the same resume_token and unchanged filters.

Common jobs​

Find outgoing transfers for one account in a narrow time window​

Start here

  • Query Transfers with the account, outgoing direction, and the tightest useful time filter.

Next page if needed

  • Narrow again by asset or amount if the response still contains unrelated transfers.

Stop when

  • You can answer who sent what, when, and in which asset.

Switch when

  • The user asks why the transfer happened or what other actions surrounded it. Move to Transactions API.

Keep paging through a transfer feed without losing your place​

Start here

  • Query Transfers for the first page of recent events, using the tightest stable filters you can.

Next page if needed

  • Reuse the exact returned resume_token to fetch the next page with the same filters.
  • Keep the filters unchanged while you paginate, or you are no longer looking at the same feed.

Stop when

  • You have enough pages to answer the requested feed, support review, or compliance check.

Switch when

  • The user asks for transaction metadata beyond transfer events.
  • The feed needs balances or holdings, not just movement. Move to FastNear API.

Escalate from transfer-only history to full transaction investigation​

Start here

Next page if needed

Stop when

  • You have identified the right transfer event and the right next API to open.

Switch when

Common mistakes​

  • Using Transfers API when the user really wants balances, holdings, or account summaries.
  • Treating transfer history as full execution history.
  • Reusing a resume_token with different filters.
  • Starting here for testnet questions; this API is mainnet-only today.