> Feedback: If these docs are stale, missing, or confusing, post sanitized feedback to `https://docs.tempo.xyz/api/feedback` with `source: "mcp"`, a short `message`, and any relevant `toolName`, `relatedResource`, or `client`. # Transfers Token movements from executing transactions. ## List transfers `GET /v1/transfers` List token transfer events across Tempo. ### Query parameters - `address` `string`: Only include transfers where this account is the sender or recipient. Use this shortcut by itself, not with `sender` or `recipient`. - `recipient` `string`: Match transfers sent to this recipient address (`to`). - `sender` `string`: Match transfers sent from this sender address (`from`). - `token` `string`: Match transfers for this TIP-20 token contract address. - `blockNumber.from` `integer`: Only include transfers at or after this block number. - `blockNumber.to` `integer`: Only include transfers at or before this block number. - `chainId` `string | number`: Which Tempo network to query. Use the alias `mainnet` or `testnet`, or a numeric chain id. Defaults to `mainnet` when omitted. - `cursor` `string`: Opaque keyset cursor from a previous response (`nextCursor`); pass it back verbatim to fetch the next page. Omit for the first (head) page. - `include` `string[]`: Comma-separated related resources to include, such as `token,memo,totalCount`. - `limit` `integer`: How many items to return per page (5–200, default 10). - `order` `string`: Sort order: `desc` for descending (the default), or `asc` for ascending. - `page` `integer`: Page number, 1-indexed (positional pagination for page-numbered access; `page=1` is the head page). Mutually exclusive with `cursor`, and `page × limit` must be at most 10000 rows — use cursor pagination for deeper traversal. Pages are positional, so rows arriving at the head of a live feed can shift page contents. - `timestamp.from` `string `: Only include transfers at or after this ISO 8601 timestamp. - `timestamp.to` `string `: Only include transfers at or before this ISO 8601 timestamp. ### Responses #### `200`: A page of token transfer events. Headers: - `RateLimit-Limit` `integer`: How many requests you may make in the current time window. Not sent on cached responses or `402` payment challenges. - `RateLimit-Remaining` `integer`: How many requests you have left in the current window before you are rate-limited. Not sent on cached responses or `402` payment challenges. - `RateLimit-Reset` `integer`: When the current window resets, as a Unix timestamp in seconds. Not sent on cached responses or `402` payment challenges. - `RateLimit-Scope` `string`: Which quota this request counted against (e.g. `data:read`). Not sent on cached responses or `402` payment challenges. - `tempo-request-id` `string`: A unique id for this request, returned on every response (and as `requestId` in error bodies). Include it when contacting support so we can find your request. Body (`application/json`): - `data` `object[]` _(required)_: The transfers in this page. - `attribution` `string`: The resolved MPP service name, when the transfer memo matches a known service fingerprint. Returned when you request `include=memo`. - `blockNumber` `integer` _(required)_: The block number where this transfer was recorded. - `id` `string` _(required)_: A stable resource ID for this transfer, built from `${transactionHash}-${logIndex}`. - `logIndex` `integer` _(required)_: The transfer event’s log index within the block. - `memo` `string`: The decoded text memo from the matching `TransferWithMemo` event, when one is present. Returned when you request `include=memo`. - `recipient` `string` _(required)_: The account address that received the tokens. - `sender` `string` _(required)_: The account address that sent the tokens. - `sourceToken` `object` _(required)_: The token and amount that moved. - `address` `string` _(required)_: The TIP-20 token contract address on Tempo. - `amount` `string` _(required)_: A non-negative whole number, given as a decimal string so very large token amounts keep full precision. Expressed in the smallest unit of the token. - `currency` `string`: The currency label for this token, such as `USD` for USD-denominated stablecoins. - `decimals` `integer`: The number of decimal places the token uses; Tempo stablecoins typically use 6. - `logoUri` `string`: A URL for the token’s logo image, when one is available. - `name` `string`: The token’s human-readable name. - `symbol` `string`: The short ticker symbol wallets and apps show for this token. - `verified` `boolean`: Whether this token is in Tempo’s curated verified token list. - `timestamp` `string ` _(required)_: The block timestamp when this transfer was recorded. - `transactionHash` `string` _(required)_: The hash of the transaction that emitted this transfer event. - `meta` `object`: Page-level resources you requested with `include`. - `totalCountCapped` `boolean` _(required)_: Whether `totalCount` hit the count cap. When true, `totalCount` is a lower bound rather than an exact total. - `totalCount` `integer` _(required)_: Number of rows matching the query, exact when `totalCountCapped` is false and a lower bound (at least this many, computed up to 10000) when `totalCountCapped` is true. Independent of pagination: use `nextCursor` to page, not this count. - `nextCursor` `string` _(required)_: Pass this back as the `cursor` query parameter to fetch the next page. `null` once you have reached the end of the list. #### `400`: Invalid request. Body (`application/json`): - `error` `object` _(required)_: What went wrong. - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`). - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields). - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation). - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors. - `message` `string` _(required)_: A human-readable explanation of what went wrong. - `requestId` `string` _(required)_: The id of this request — include it when contacting support. #### `401`: Missing or invalid API key. Body (`application/json`): - `error` `object` _(required)_: What went wrong. - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`). - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields). - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation). - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors. - `message` `string` _(required)_: A human-readable explanation of what went wrong. - `requestId` `string` _(required)_: The id of this request — include it when contacting support. #### `402`: Payment required. The request exceeded the free/anonymous quota and carried no valid MPP payment. The challenge is protocol-native (handled by mppx), not the JSON error envelope: read the `WWW-Authenticate` header on this response and retry with an `Authorization: Payment ` header; the successful paid response then carries a `Payment-Receipt` header. See the Authentication section. Headers: - `WWW-Authenticate` `string`: On a `402` response, the payment challenge to satisfy. Use it to build the `Authorization: Payment` credential and retry the request. #### `429`: Rate limit exceeded. Headers: - `RateLimit-Limit` `integer`: How many requests you may make in the current time window. Not sent on cached responses or `402` payment challenges. - `RateLimit-Remaining` `integer`: How many requests you have left in the current window before you are rate-limited. Not sent on cached responses or `402` payment challenges. - `RateLimit-Reset` `integer`: When the current window resets, as a Unix timestamp in seconds. Not sent on cached responses or `402` payment challenges. - `RateLimit-Scope` `string`: Which quota this request counted against (e.g. `data:read`). Not sent on cached responses or `402` payment challenges. - `tempo-request-id` `string`: A unique id for this request, returned on every response (and as `requestId` in error bodies). Include it when contacting support so we can find your request. - `Retry-After` `integer`: How many seconds to wait before trying again. Sent with `429` (rate-limited) responses. Body (`application/json`): - `error` `object` _(required)_: What went wrong. - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`). - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields). - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation). - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors. - `message` `string` _(required)_: A human-readable explanation of what went wrong. - `requestId` `string` _(required)_: The id of this request — include it when contacting support. #### `500`: Internal server error. Body (`application/json`): - `error` `object` _(required)_: What went wrong. - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`). - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields). - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation). - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors. - `message` `string` _(required)_: A human-readable explanation of what went wrong. - `requestId` `string` _(required)_: The id of this request — include it when contacting support. #### `502`: The upstream indexer could not serve this request. Body (`application/json`): - `error` `object` _(required)_: What went wrong. - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`). - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields). - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation). - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors. - `message` `string` _(required)_: A human-readable explanation of what went wrong. - `requestId` `string` _(required)_: The id of this request — include it when contacting support. ### Example request ```bash curl 'https://api.tempo.xyz/v1/transfers?address=0xbe058e1c4df8a4366a387bf595b284246a93039e&recipient=0xbe058e1c4df8a4366a387bf595b284246a93039e&sender=0xbe058e1c4df8a4366a387bf595b284246a93039e&token=0x20c0000000000000000000000000000000000000&blockNumber.from=23456789&blockNumber.to=23456999&chainId=4217&cursor=WzIzNDU2Nzg5LDBd&include=memo,token,totalCount&limit=10&order=desc&page=1×tamp.from=2024-01-01T00:00:00Z×tamp.to=2024-12-31T23:59:59Z' ``` ```ts fetch('https://api.tempo.xyz/v1/transfers?address=0xbe058e1c4df8a4366a387bf595b284246a93039e&recipient=0xbe058e1c4df8a4366a387bf595b284246a93039e&sender=0xbe058e1c4df8a4366a387bf595b284246a93039e&token=0x20c0000000000000000000000000000000000000&blockNumber.from=23456789&blockNumber.to=23456999&chainId=4217&cursor=WzIzNDU2Nzg5LDBd&include=memo,token,totalCount&limit=10&order=desc&page=1×tamp.from=2024-01-01T00:00:00Z×tamp.to=2024-12-31T23:59:59Z') ```