{ "x-generated-warning": "⚠️ This file is auto-generated. Do not edit manually", "openapi": "3.1.0", "info": { "title": "🧠 Data", "version": "1.0" }, "servers": [ { "url": "https://api.g.alchemy.com/data/v1" } ], "paths": { "/{apiKey}/assets/tokens/by-address": { "post": { "summary": "Tokens By Wallet", "description": "Fetches fungible tokens (native, ERC-20 and SPL) for multiple wallet addresses and networks. Returns a list of tokens with balances, prices, and metadata for each wallet/network combination. This endpoint is supported on Ethereum, Solana, and 30+ EVM chains. See the full list of supported networks [here](https://dashboard.alchemy.com/chains).\n\nThis endpoint fans out across every requested network and merges the results. If one or more networks fail (upstream error or per-network timeout: 5s on paginated requests, 10s on fetch-all), the response is still HTTP 200 with a top-level `error.partialErrors` array listing the failed networks. See [Handling partial failures](/docs/reference/portfolio-apis#handling-partial-failures) for the recommended client pattern.\n\nThe top-level `error` object is distinct from the per-token `data.tokens[].error` field. The former reports networks that failed entirely; the latter reports a per-token metadata or pricing failure within an otherwise successful network response.\n", "tags": [ "Portfolio API Endpoints" ], "parameters": [ { "name": "apiKey", "in": "path", "schema": { "type": "string", "default": "docs-demo", "description": "For higher throughput, [create your own API key](https://dashboard.alchemy.com/signup)" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "addresses": { "type": "array", "description": "Array of wallet addresses and the networks to query them on. Maximum 2 addresses and maximum 5 networks per address.\n", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Wallet address.", "example": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "default": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152" }, "networks": { "type": "array", "example": [ "eth-mainnet", "base-mainnet", "matic-mainnet" ], "items": { "type": "string", "default": "eth-mainnet" }, "description": "Network identifier (e.g., eth-mainnet). Find more network enums [here](https://dashboard.alchemy.com/chains)" } }, "required": [ "address", "networks" ] } }, "withMetadata": { "description": "Boolean - if set to `true`, returns metadata. Setting this to false will reduce payload size and may result in a faster API call.", "type": "boolean", "default": true }, "withPrices": { "description": "Boolean - if set to `true`, returns token prices. Setting this to false will reduce payload size and may result in a faster API call.", "type": "boolean", "default": true }, "includeNativeTokens": { "type": "boolean", "description": "Whether to include each chain's native token in the response (e.g. ETH on Ethereum). The native token will have a null contract address.", "example": true, "default": true }, "includeErc20Tokens": { "description": "Boolean - if set to `true`, returns ERC-20 tokens. Setting this to false will reduce payload size and may result in a faster API call.", "type": "boolean", "default": true }, "includeBlockMetadata": { "description": "Boolean - if set to `true`, includes a `blockMetadata` object inside `data` (alongside `pageKey`) mapping each requested network to the block used to compute the returned balances (`blockNumber`, `blockHash`, `blockTimestamp`). Failed networks are still present as keys but map to `null`.", "type": "boolean", "default": false } }, "required": [ "addresses" ] }, "example": { "addresses": [ { "address": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "networks": [ "eth-mainnet", "base-mainnet", "matic-mainnet" ] } ], "withMetadata": true, "withPrices": true, "includeNativeTokens": true, "includeErc20Tokens": false, "includeBlockMetadata": false } } } }, "responses": { "200": { "description": "Successful response!", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "List of tokens by address, with prices and metadata.", "properties": { "tokens": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Wallet address." }, "network": { "type": "string", "description": "Network identifier." }, "tokenAddress": { "type": [ "string", "null" ], "description": "Token contract address. `null` for a chain's native token." }, "tokenBalance": { "type": "string", "description": "Balance of that particular token." }, "tokenMetadata": { "type": "object", "properties": { "decimals": { "type": "integer", "description": "Number of decimals the token uses" }, "logo": { "type": "string", "description": "URL of the token's logo image" }, "name": { "type": "string", "description": "Token's name" }, "symbol": { "type": "string", "description": "Token's symbol" } } }, "tokenPrices": { "type": "array", "description": "List of price information.", "items": { "type": "object", "properties": { "currency": { "type": "string", "example": "usd" }, "value": { "type": "string", "example": "4608.2208671202" }, "lastUpdatedAt": { "type": "string", "format": "date-time", "example": "2025-08-26T20:17:27Z" } }, "required": [ "currency", "value", "lastUpdatedAt" ] } }, "error": { "type": [ "string", "null" ], "description": "Error message if applicable." } }, "required": [ "network", "address", "tokenAddress", "tokenBalance" ] } }, "pageKey": { "type": "string" }, "blockMetadata": { "type": "object", "description": "Block metadata for each network in the response, keyed by network slug (e.g. `eth-mainnet`, `matic-mainnet`). Present only when the request sets `includeBlockMetadata` to `true`. Every requested network appears as a key: successful networks map to a `BlockMetadataEntry`, and networks that failed map to `null` (their reason is reported in `error.partialErrors`).\n", "additionalProperties": { "oneOf": [ { "type": "object", "description": "Block used to compute the returned balances on a given network. `null` for networks that failed (see `error.partialErrors` for the reason).\n", "properties": { "blockNumber": { "type": "string", "description": "Hex-encoded block number.", "example": "0x18a6825" }, "blockHash": { "type": "string", "description": "Block hash.", "example": "0xb9587b181217d4c32c45e614d85c92c857dac76b57e15d36fb7d38b27dcecb92" }, "blockTimestamp": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp when the block was produced.", "example": "2026-08-27T16:45:59.000Z" } }, "required": [ "blockNumber", "blockHash", "blockTimestamp" ] }, { "type": "null" } ] }, "example": { "eth-mainnet": { "blockNumber": "0x18a6825", "blockHash": "0xb9587b181217d4c32c45e614d85c92c857dac76b57e15d36fb7d38b27dcecb92", "blockTimestamp": "2026-08-27T16:45:59.000Z" }, "matic-mainnet": { "blockNumber": "0x5877288", "blockHash": "0x4ddbc1d12e14909468c49efd2771d1a09dec2850a823e0d9942db54d54633e43", "blockTimestamp": "2026-08-27T16:46:07.000Z" }, "base-mainnet": null } } }, "required": [ "tokens" ] }, "error": { "type": "object", "description": "Present on 200 responses only when one or more requested networks did not return data (upstream error or per-network timeout: 5s on paginated requests, 10s on fetch-all). When every requested network succeeds, the `error` key is omitted from the response entirely (it is not present-and-null). See [Handling partial failures](/docs/reference/portfolio-apis#handling-partial-failures) for the recommended client pattern.\n", "properties": { "message": { "type": "string", "description": "Human-readable summary of the partial failure. On the token endpoints this is `\"Failed to fetch tokens on certain networks\"`; on the NFT endpoints it is `\"Failed to fetch NFTs on certain networks\"`.\n" }, "partialErrors": { "type": "array", "description": "One entry per failed network. A network may appear more than once if the request body contained multiple entries covering that network.\n", "items": { "type": "object", "properties": { "network": { "type": "string", "description": "Network slug that failed (e.g. `eth-mainnet`, `robinhood-mainnet`)." }, "message": { "type": "string", "description": "Human-readable failure reason. Treat as an opaque string, not an enumerable error code. It does not distinguish upstream errors from per-network timeouts.\n" } }, "required": [ "network", "message" ] } } }, "required": [ "message", "partialErrors" ] } }, "required": [ "data" ] }, "examples": { "success": { "summary": "All networks succeeded", "value": { "data": { "tokens": [ { "address": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "network": "eth-mainnet", "tokenAddress": null, "tokenBalance": "0x02c68af0bb140000", "tokenMetadata": { "decimals": 18, "logo": "https://static.alchemyapi.io/images/assets/1027.png", "name": "Ethereum", "symbol": "ETH" }, "tokenPrices": [ { "currency": "usd", "value": "4608.2208671202", "lastUpdatedAt": "2025-08-26T20:17:27Z" } ] }, { "address": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "network": "base-mainnet", "tokenAddress": null, "tokenBalance": "0x016345785d8a0000", "tokenMetadata": { "decimals": 18, "logo": "https://static.alchemyapi.io/images/assets/1027.png", "name": "Ethereum", "symbol": "ETH" }, "tokenPrices": [ { "currency": "usd", "value": "4608.2208671202", "lastUpdatedAt": "2025-08-26T20:17:27Z" } ] }, { "address": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "network": "matic-mainnet", "tokenAddress": null, "tokenBalance": "0x0de0b6b3a7640000", "tokenMetadata": { "decimals": 18, "logo": "https://static.alchemyapi.io/images/assets/3890.png", "name": "Polygon", "symbol": "POL" }, "tokenPrices": [ { "currency": "usd", "value": "0.4210556310", "lastUpdatedAt": "2025-08-26T20:17:27Z" } ] } ] } } }, "partialFailure": { "summary": "One or more networks failed (HTTP 200)", "value": { "data": { "tokens": [ { "address": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "network": "eth-mainnet", "tokenAddress": null, "tokenBalance": "0x02c68af0bb140000", "tokenMetadata": { "decimals": 18, "logo": "https://static.alchemyapi.io/images/assets/1027.png", "name": "Ethereum", "symbol": "ETH" }, "tokenPrices": [ { "currency": "usd", "value": "4608.2208671202", "lastUpdatedAt": "2025-08-26T20:17:27Z" } ] } ] }, "error": { "message": "Failed to fetch tokens on certain networks", "partialErrors": [ { "network": "base-mainnet", "message": "Internal server error" }, { "network": "matic-mainnet", "message": "Internal server error" } ] } } }, "withBlockMetadata": { "summary": "Request set `includeBlockMetadata: true`", "value": { "data": { "tokens": [ { "address": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "network": "eth-mainnet", "tokenAddress": null, "tokenBalance": "0x02c68af0bb140000", "tokenMetadata": { "decimals": 18, "logo": "https://static.alchemyapi.io/images/assets/1027.png", "name": "Ethereum", "symbol": "ETH" }, "tokenPrices": [ { "currency": "usd", "value": "4608.2208671202", "lastUpdatedAt": "2025-08-26T20:17:27Z" } ] }, { "address": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "network": "matic-mainnet", "tokenAddress": null, "tokenBalance": "0x0de0b6b3a7640000", "tokenMetadata": { "decimals": 18, "logo": "https://static.alchemyapi.io/images/assets/3890.png", "name": "Polygon", "symbol": "POL" }, "tokenPrices": [ { "currency": "usd", "value": "0.4210556310", "lastUpdatedAt": "2025-08-26T20:17:27Z" } ] } ], "blockMetadata": { "eth-mainnet": { "blockNumber": "0x18a6825", "blockHash": "0xb9587b181217d4c32c45e614d85c92c857dac76b57e15d36fb7d38b27dcecb92", "blockTimestamp": "2026-08-27T16:45:59.000Z" }, "matic-mainnet": { "blockNumber": "0x5877288", "blockHash": "0x4ddbc1d12e14909468c49efd2771d1a09dec2850a823e0d9942db54d54633e43", "blockTimestamp": "2026-08-27T16:46:07.000Z" }, "base-mainnet": null } }, "error": { "message": "Failed to fetch tokens on certain networks", "partialErrors": [ { "network": "base-mainnet", "message": "Internal server error" } ] } } } } } } }, "400": { "description": "Bad Request: Invalid input (e.g., malformed JSON).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Detailed error message." } }, "required": [ "message" ], "description": "Error details." } }, "required": [ "error" ] } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Detailed error message." } }, "required": [ "message" ], "description": "Error details." } }, "required": [ "error" ] } } } } }, "operationId": "get-tokens-by-address" } }, "/{apiKey}/assets/tokens/balances/by-address": { "post": { "summary": "Token Balances By Wallet", "description": "Fetches fungible tokens (native, ERC-20, and SPL) for multiple wallet addresses and networks. Returns a list of tokens with balances for each wallet/network combination. This endpoint is supported on Ethereum, Solana, and 30+ EVM chains. See the full list of supported networks [here](https://dashboard.alchemy.com/chains)\n\nThis endpoint fans out across every requested network and merges the results. If one or more networks fail (upstream error or per-network timeout: 5s on paginated requests, 10s on fetch-all), the response is still HTTP 200 with a top-level `error.partialErrors` array listing the failed networks. See [Handling partial failures](/docs/reference/portfolio-apis#handling-partial-failures) for the recommended client pattern.\n", "tags": [ "Portfolio API Endpoints" ], "parameters": [ { "name": "apiKey", "in": "path", "schema": { "type": "string", "default": "docs-demo", "description": "For higher throughput, [create your own API key](https://dashboard.alchemy.com/signup)" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "addresses": { "type": "array", "description": "Array of address and networks pairs (limit 3 pairs, max 20 networks). Networks should match network enums.\n", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Wallet address.", "example": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "default": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152" }, "networks": { "type": "array", "example": [ "eth-mainnet", "base-mainnet", "matic-mainnet" ], "items": { "type": "string", "default": "eth-mainnet" }, "description": "Network identifier (e.g., eth-mainnet). Find more network enums [here](https://dashboard.alchemy.com/chains)" } }, "required": [ "address", "networks" ] } }, "includeNativeTokens": { "type": "boolean", "description": "Whether to include each chain's native token in the response (e.g. ETH on Ethereum). The native token will have a null contract address.", "example": true, "default": true }, "includeErc20Tokens": { "description": "Boolean - if set to `true`, returns ERC-20 tokens. Setting this to false will reduce payload size and may result in a faster API call.", "type": "boolean", "default": true }, "includeBlockMetadata": { "description": "Boolean - if set to `true`, includes a `blockMetadata` object inside `data` (alongside `pageKey`) mapping each requested network to the block used to compute the returned balances (`blockNumber`, `blockHash`, `blockTimestamp`). Failed networks are still present as keys but map to `null`.", "type": "boolean", "default": false } }, "required": [ "addresses" ] }, "example": { "addresses": [ { "address": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "networks": [ "eth-mainnet", "base-mainnet", "matic-mainnet" ] } ], "includeNativeTokens": true, "includeErc20Tokens": false, "includeBlockMetadata": false } } } }, "responses": { "200": { "description": "Successful response!", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tokens": { "type": "array", "description": "List of token balances by address.", "items": { "type": "object", "properties": { "network": { "type": "string", "description": "Network identifier." }, "address": { "type": "string", "description": "Wallet address." }, "tokenAddress": { "type": [ "string", "null" ], "description": "Token contract address. `null` for a chain's native token." }, "tokenBalance": { "type": "string", "description": "Balance of that particular token." } }, "required": [ "network", "address", "tokenAddress", "tokenBalance" ] } }, "pageKey": { "type": "string" }, "blockMetadata": { "type": "object", "description": "Block metadata for each network in the response, keyed by network slug (e.g. `eth-mainnet`, `matic-mainnet`). Present only when the request sets `includeBlockMetadata` to `true`. Every requested network appears as a key: successful networks map to a `BlockMetadataEntry`, and networks that failed map to `null` (their reason is reported in `error.partialErrors`).\n", "additionalProperties": { "oneOf": [ { "type": "object", "description": "Block used to compute the returned balances on a given network. `null` for networks that failed (see `error.partialErrors` for the reason).\n", "properties": { "blockNumber": { "type": "string", "description": "Hex-encoded block number.", "example": "0x18a6825" }, "blockHash": { "type": "string", "description": "Block hash.", "example": "0xb9587b181217d4c32c45e614d85c92c857dac76b57e15d36fb7d38b27dcecb92" }, "blockTimestamp": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp when the block was produced.", "example": "2026-08-27T16:45:59.000Z" } }, "required": [ "blockNumber", "blockHash", "blockTimestamp" ] }, { "type": "null" } ] }, "example": { "eth-mainnet": { "blockNumber": "0x18a6825", "blockHash": "0xb9587b181217d4c32c45e614d85c92c857dac76b57e15d36fb7d38b27dcecb92", "blockTimestamp": "2026-08-27T16:45:59.000Z" }, "matic-mainnet": { "blockNumber": "0x5877288", "blockHash": "0x4ddbc1d12e14909468c49efd2771d1a09dec2850a823e0d9942db54d54633e43", "blockTimestamp": "2026-08-27T16:46:07.000Z" }, "base-mainnet": null } } }, "required": [ "tokens" ] }, "error": { "type": "object", "description": "Present on 200 responses only when one or more requested networks did not return data (upstream error or per-network timeout: 5s on paginated requests, 10s on fetch-all). When every requested network succeeds, the `error` key is omitted from the response entirely (it is not present-and-null). See [Handling partial failures](/docs/reference/portfolio-apis#handling-partial-failures) for the recommended client pattern.\n", "properties": { "message": { "type": "string", "description": "Human-readable summary of the partial failure. On the token endpoints this is `\"Failed to fetch tokens on certain networks\"`; on the NFT endpoints it is `\"Failed to fetch NFTs on certain networks\"`.\n" }, "partialErrors": { "type": "array", "description": "One entry per failed network. A network may appear more than once if the request body contained multiple entries covering that network.\n", "items": { "type": "object", "properties": { "network": { "type": "string", "description": "Network slug that failed (e.g. `eth-mainnet`, `robinhood-mainnet`)." }, "message": { "type": "string", "description": "Human-readable failure reason. Treat as an opaque string, not an enumerable error code. It does not distinguish upstream errors from per-network timeouts.\n" } }, "required": [ "network", "message" ] } } }, "required": [ "message", "partialErrors" ] } }, "required": [ "data" ] }, "examples": { "success": { "summary": "All networks succeeded", "value": { "data": { "tokens": [ { "address": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "network": "eth-mainnet", "tokenAddress": null, "tokenBalance": "0x02c68af0bb140000" }, { "address": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "network": "base-mainnet", "tokenAddress": null, "tokenBalance": "0x016345785d8a0000" }, { "address": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "network": "matic-mainnet", "tokenAddress": null, "tokenBalance": "0x0de0b6b3a7640000" } ] } } }, "partialFailure": { "summary": "One or more networks failed (HTTP 200)", "value": { "data": { "tokens": [ { "address": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "network": "eth-mainnet", "tokenAddress": null, "tokenBalance": "0x02c68af0bb140000" } ] }, "error": { "message": "Failed to fetch tokens on certain networks", "partialErrors": [ { "network": "base-mainnet", "message": "Internal server error" }, { "network": "matic-mainnet", "message": "Internal server error" } ] } } }, "withBlockMetadata": { "summary": "Request set `includeBlockMetadata: true`", "value": { "data": { "tokens": [ { "address": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "network": "eth-mainnet", "tokenAddress": null, "tokenBalance": "0x02c68af0bb140000" }, { "address": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "network": "matic-mainnet", "tokenAddress": null, "tokenBalance": "0x0de0b6b3a7640000" } ], "blockMetadata": { "eth-mainnet": { "blockNumber": "0x18a6825", "blockHash": "0xb9587b181217d4c32c45e614d85c92c857dac76b57e15d36fb7d38b27dcecb92", "blockTimestamp": "2026-08-27T16:45:59.000Z" }, "matic-mainnet": { "blockNumber": "0x5877288", "blockHash": "0x4ddbc1d12e14909468c49efd2771d1a09dec2850a823e0d9942db54d54633e43", "blockTimestamp": "2026-08-27T16:46:07.000Z" }, "base-mainnet": null } }, "error": { "message": "Failed to fetch tokens on certain networks", "partialErrors": [ { "network": "base-mainnet", "message": "Internal server error" } ] } } } } } } }, "400": { "description": "Bad Request: Invalid input (e.g., malformed JSON).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Detailed error message." } }, "required": [ "message" ], "description": "Error details." } }, "required": [ "error" ] } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Detailed error message." } }, "required": [ "message" ], "description": "Error details." } }, "required": [ "error" ] } } } } }, "operationId": "get-token-balances-by-address" } }, "/{apiKey}/assets/nfts/by-address": { "post": { "summary": "NFTs By Wallet", "description": "Fetches NFTs for multiple wallet addresses and networks. Returns a list of NFTs and metadata for each wallet/network combination. This endpoint is supported on Ethereum and many L2s, including Polygon, Arbitrum, Optimism, Base, World Chain and more. See the full list of supported networks [here](https://dashboard.alchemy.com/chains).\n\nThis endpoint fans out across every requested network and merges the results. If one or more networks fail (upstream error or per-network timeout: 5s on paginated requests, 10s on fetch-all), the response is still HTTP 200 with a top-level `error.partialErrors` array listing the failed networks. See [Handling partial failures](/docs/reference/portfolio-apis#handling-partial-failures) for the recommended client pattern.\n", "tags": [ "Portfolio API Endpoints" ], "parameters": [ { "name": "apiKey", "in": "path", "schema": { "type": "string", "default": "docs-demo", "description": "For higher throughput, [create your own API key](https://dashboard.alchemy.com/signup)" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "addresses": { "type": "array", "description": "Array of address and networks pairs (limit 2 pairs, max 15 networks each). Networks should match network enums.\n", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Wallet address.", "example": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "default": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152" }, "networks": { "type": "array", "example": [ "eth-mainnet", "base-mainnet", "matic-mainnet" ], "items": { "type": "string", "enum": [ "eth-mainnet", "eth-sepolia", "eth-holesky", "avax-mainnet", "avax-fuji", "zksync-mainnet", "opt-mainnet", "matic-mainnet", "matic-amoy", "arb-mainnet", "arb-sepolia", "blast-mainnet", "blast-sepolia", "base-mainnet", "base-sepolia", "soneium-mainnet", "soneium-minato", "scroll-mainnet", "shape-mainnet", "shape-sepolia", "lens-mainnet", "lens-sepolia", "starknet-mainnet", "starknet-sepolia", "rootstock-mainnet", "rootstock-testnet", "linea-mainnet", "linea-sepolia", "settlus-septestnet", "abstract-mainnet", "abstract-testnet", "apechain-mainnet" ], "default": "eth-mainnet" }, "description": "Network identifier (e.g., eth-mainnet). Find more network enums [here](https://dashboard.alchemy.com/chains)" }, "excludeFilters": { "type": "array", "items": { "type": "string", "enum": [ "SPAM", "AIRDROPS" ], "default": "SPAM" } }, "includeFilters": { "type": "array", "items": { "type": "string", "enum": [ "SPAM", "AIRDROPS" ], "default": "SPAM" } }, "spamConfidenceLevel": { "type": "string", "enum": [ "VERY_HIGH", "HIGH", "MEDIUM", "LOW" ] } }, "required": [ "address", "networks" ] } }, "withMetadata": { "description": "Boolean - if set to `true`, returns metadata. Setting this to false will reduce payload size and may result in a faster API call.", "type": "boolean", "default": true }, "pageKey": { "type": "string" }, "pageSize": { "type": "integer", "default": 100 } }, "required": [ "addresses" ] }, { "type": "object", "properties": { "orderBy": { "type": "string", "enum": [ "transferTime" ], "description": "Field to order results by" }, "sortOrder": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for results" } } } ] }, "example": { "addresses": [ { "address": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "networks": [ "eth-mainnet", "base-mainnet", "matic-mainnet" ] } ], "withMetadata": true } } } }, "responses": { "200": { "description": "Successful response!", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "List of nfts by address with appropriate metadata.", "properties": { "ownedNfts": { "type": "array", "items": { "type": "object", "description": "The object that represents an NFT and has all data corresponding to that NFT", "properties": { "network": { "type": "string", "description": "Network identifier." }, "address": { "type": "string", "description": "Wallet address." }, "contract": { "type": "object", "description": "The contract object that has details of a contract", "properties": { "address": { "description": "Address of the held contract", "type": "string" }, "name": { "type": "string", "description": "String - NFT contract name." }, "symbol": { "type": "string", "description": "String - NFT contract symbol abbreviation." }, "totalSupply": { "type": "string", "description": "String - Total number of NFTs in a given NFT collection." }, "tokenType": { "type": "string", "enum": [ "ERC721", "ERC1155", "NO_SUPPORTED_NFT_STANDARD", "NOT_A_CONTRACT" ], "description": "String - For valid NFTs, 'ERC721' or 'ERC1155.' For invalid NFTs, a descriptive reason such as 'NO_SUPPORTED_NFT_STANDARD' if the input contract address doesn't support a known NFT standard, or 'NOT_A_CONTRACT' if there is no contract deployed at the input address." }, "contractDeployer": { "type": "string", "description": "String - Address that deployed the smart contract" }, "deployedBlockNumber": { "type": "number", "description": "Number - The Block Number when the deployment transaction is successfully mined" }, "openseaMetadata": { "type": "object", "description": "Note that the OpenSea metadata object is currently only available on ETH and Polygon Mainnet. Please reach out to us at support@alchemy.com if you would like to access this data on other networks.", "properties": { "floorPrice": { "type": "number", "description": "NFT floor price" }, "collectionName": { "type": "string", "description": "OpenSea collection name" }, "safelistRequestStatus": { "type": "string", "description": "Collection approval status within OpenSea. For more info, see the Opensea docs at docs.opensea.io/reference/collection-model" }, "imageUrl": { "type": "string", "description": "OpenSea CDN image URL" }, "description": { "type": "string", "description": "OpenSea collection description. Note: this value is truncated to 255 characters." }, "externalUrl": { "type": "string", "description": "Collection homepage" }, "twitterUsername": { "type": "string", "description": "The twitter username of the collection" }, "discordUrl": { "type": "string", "description": "The discord URL of the collection" }, "bannerImageUrl": { "type": "string", "description": "The banner image URL of the collection" }, "lastIngestedAt": { "type": "string", "description": "The timestamp when the collection was last ingested by us" } } }, "isSpam": { "type": "string", "description": "\"true\" if contract is spam, else \"false\". **Only available on paid tiers.**" }, "spamClassifications": { "description": "List of reasons why a contract was classified as spam. **Only available on paid tiers.**", "type": "array", "items": { "type": "string" } } } }, "tokenId": { "type": "string", "default": "44" }, "tokenType": { "type": "string" }, "name": { "type": "string", "description": "String - Name of the NFT asset." }, "description": { "type": "string", "description": "String - Brief human-readable description" }, "image": { "type": "object", "description": "Details of the image corresponding to this contract", "properties": { "cachedUrl": { "type": "string", "description": "The Url of the image stored in Alchemy cache" }, "thumbnailUrl": { "type": "string", "description": "The Url that has the thumbnail version of the NFT" }, "pngUrl": { "type": "string", "description": "The Url that has the NFT image in png" }, "contentType": { "type": "string", "description": "The Url of the image stored in Alchemy cache" }, "size": { "type": "integer", "description": "The size of the media asset in bytes." }, "originalUrl": { "type": "string", "description": "The original Url of the image coming straight from the smart contract" } } }, "raw": { "type": "object", "description": "Raw details of the NFT like its tokenUri and metadata info obtained directly from the smart contract", "properties": { "tokenUri": { "type": "string", "description": "String - Uri representing the location of the NFT's original metadata blob. This is a backup for you to parse when the metadata field is not automatically populated." }, "metadata": { "type": "object", "description": "Relevant metadata for NFT contract. This is useful for viewing image url, traits, etc. without having to follow the metadata url in tokenUri to parse manually.", "properties": { "image": { "type": "string", "description": "String - URL to the NFT asset image. Can be standard URLs pointing to images on conventional servers, IPFS, or Arweave. Most types of images (SVGs, PNGs, JPEGs, etc.) are supported by NFT marketplaces." }, "name": { "type": "string", "description": "String - Name of the NFT asset." }, "description": { "type": "string", "description": "String - Human-readable description of the NFT asset. (Markdown is supported/rendered on OpenSea and other NFT platforms)" }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "trait_type": { "type": "string" } } }, "description": "Object - Traits/attributes/characteristics for each NFT asset." } } }, "error": { "type": "string", "description": "String - A string describing a particular reason that we were unable to fetch complete metadata for the NFT." } } }, "collection": { "type": "object", "description": "The collection object that has details of a collection", "properties": { "name": { "type": "string", "description": "String - Collection name" }, "slug": { "type": "string", "description": "String - OpenSea collection slug" }, "externalUrl": { "type": "string", "description": "String - URL for the external site of the collection" }, "bannerImageUrl": { "type": "string", "description": "String - Banner image URL for the collection" } } }, "tokenUri": { "type": "string", "description": "String - Uri representing the location of the NFT's original metadata blob. This is a backup for you to parse when the metadata field is not automatically populated." }, "timeLastUpdated": { "type": "string", "description": "String - ISO timestamp of the last cache refresh for the information returned in the metadata field." }, "acquiredAt": { "type": "object", "description": "Only present if the request specified `orderBy=transferTime`.", "properties": { "blockTimestamp": { "type": "string", "description": "Block timestamp of the block where the NFT was most recently acquired." }, "blockNumber": { "type": "string", "description": "Block number of the block where the NFT was most recently acquired." } } } } } }, "totalCount": { "type": "integer", "description": "Integer - Total number of NFTs (distinct `tokenIds`) owned by the given address." }, "pageKey": { "type": "string" } } }, "error": { "type": "object", "description": "Present on 200 responses only when one or more requested networks did not return data (upstream error or per-network timeout: 5s on paginated requests, 10s on fetch-all). When every requested network succeeds, the `error` key is omitted from the response entirely (it is not present-and-null). See [Handling partial failures](/docs/reference/portfolio-apis#handling-partial-failures) for the recommended client pattern.\n", "properties": { "message": { "type": "string", "description": "Human-readable summary of the partial failure. On the token endpoints this is `\"Failed to fetch tokens on certain networks\"`; on the NFT endpoints it is `\"Failed to fetch NFTs on certain networks\"`.\n" }, "partialErrors": { "type": "array", "description": "One entry per failed network. A network may appear more than once if the request body contained multiple entries covering that network.\n", "items": { "type": "object", "properties": { "network": { "type": "string", "description": "Network slug that failed (e.g. `eth-mainnet`, `robinhood-mainnet`)." }, "message": { "type": "string", "description": "Human-readable failure reason. Treat as an opaque string, not an enumerable error code. It does not distinguish upstream errors from per-network timeouts.\n" } }, "required": [ "network", "message" ] } } }, "required": [ "message", "partialErrors" ] } }, "required": [ "data" ] }, "examples": { "success": { "summary": "All networks succeeded", "value": { "data": { "ownedNfts": [ { "network": "eth-mainnet", "address": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "contract": { "address": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d", "name": "BoredApeYachtClub", "symbol": "BAYC", "totalSupply": "10000", "tokenType": "ERC721" }, "tokenId": "1234", "tokenType": "ERC721", "name": "Bored Ape #1234", "description": "A Bored Ape from the Bored Ape Yacht Club collection.", "tokenUri": "https://ipfs.io/ipfs/QmXXXXX/1234", "timeLastUpdated": "2025-08-26T20:17:27Z" } ], "totalCount": 1 } } }, "partialFailure": { "summary": "One or more networks failed (HTTP 200)", "value": { "data": { "ownedNfts": [ { "network": "eth-mainnet", "address": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "contract": { "address": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d", "name": "BoredApeYachtClub", "symbol": "BAYC", "totalSupply": "10000", "tokenType": "ERC721" }, "tokenId": "1234", "tokenType": "ERC721", "name": "Bored Ape #1234", "description": "A Bored Ape from the Bored Ape Yacht Club collection.", "tokenUri": "https://ipfs.io/ipfs/QmXXXXX/1234", "timeLastUpdated": "2025-08-26T20:17:27Z" } ], "totalCount": 1 }, "error": { "message": "Failed to fetch NFTs on certain networks", "partialErrors": [ { "network": "base-mainnet", "message": "Internal server error" }, { "network": "matic-mainnet", "message": "Internal server error" } ] } } } } } } }, "400": { "description": "Bad Request: Invalid input (e.g., malformed JSON).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Detailed error message." } }, "required": [ "message" ], "description": "Error details." } }, "required": [ "error" ] } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Detailed error message." } }, "required": [ "message" ], "description": "Error details." } }, "required": [ "error" ] } } } } }, "operationId": "get-nfts-by-address" } }, "/{apiKey}/assets/nfts/contracts/by-address": { "post": { "summary": "NFT Collections By Wallet", "description": "Fetches NFT collections (contracts) for multiple wallet addresses and networks. Returns a list of collections and metadata for each wallet/network combination. This endpoint is supported on Ethereum and many L2s, including Polygon, Arbitrum, Optimism, Base, World Chain and more. See the full list of supported networks [here](https://dashboard.alchemy.com/chains).\n\nThis endpoint fans out across every requested network and merges the results. If one or more networks fail (upstream error or per-network timeout: 5s on paginated requests, 10s on fetch-all), the response is still HTTP 200 with a top-level `error.partialErrors` array listing the failed networks. See [Handling partial failures](/docs/reference/portfolio-apis#handling-partial-failures) for the recommended client pattern.\n", "tags": [ "Portfolio API Endpoints" ], "parameters": [ { "name": "apiKey", "in": "path", "schema": { "type": "string", "default": "docs-demo", "description": "For higher throughput, [create your own API key](https://dashboard.alchemy.com/signup)" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "addresses": { "type": "array", "description": "Array of address and networks pairs (limit 2 pairs, max 15 networks each). Networks should match network enums.\n", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Wallet address.", "example": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "default": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152" }, "networks": { "type": "array", "example": [ "eth-mainnet", "base-mainnet", "matic-mainnet" ], "items": { "type": "string", "enum": [ "eth-mainnet", "eth-sepolia", "eth-holesky", "avax-mainnet", "avax-fuji", "zksync-mainnet", "opt-mainnet", "matic-mainnet", "matic-amoy", "arb-mainnet", "arb-sepolia", "blast-mainnet", "blast-sepolia", "base-mainnet", "base-sepolia", "soneium-mainnet", "soneium-minato", "scroll-mainnet", "shape-mainnet", "shape-sepolia", "lens-mainnet", "lens-sepolia", "starknet-mainnet", "starknet-sepolia", "rootstock-mainnet", "rootstock-testnet", "linea-mainnet", "linea-sepolia", "settlus-septestnet", "abstract-mainnet", "abstract-testnet", "apechain-mainnet" ], "default": "eth-mainnet" }, "description": "Network identifier (e.g., eth-mainnet). Find more network enums [here](https://dashboard.alchemy.com/chains)" }, "excludeFilters": { "type": "array", "items": { "type": "string", "enum": [ "SPAM", "AIRDROPS" ], "default": "SPAM" } }, "includeFilters": { "type": "array", "items": { "type": "string", "enum": [ "SPAM", "AIRDROPS" ], "default": "SPAM" } }, "spamConfidenceLevel": { "type": "string", "enum": [ "VERY_HIGH", "HIGH", "MEDIUM", "LOW" ] } }, "required": [ "address", "networks" ] } }, "withMetadata": { "description": "Boolean - if set to `true`, returns metadata. Setting this to false will reduce payload size and may result in a faster API call.", "type": "boolean", "default": true }, "pageKey": { "type": "string" }, "pageSize": { "type": "integer", "default": 100 } }, "required": [ "addresses" ] }, { "type": "object", "properties": { "orderBy": { "type": "string", "enum": [ "transferTime" ], "description": "Field to order results by" }, "sortOrder": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order for results" } } } ] }, "example": { "addresses": [ { "address": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "networks": [ "eth-mainnet", "base-mainnet", "matic-mainnet" ] } ], "withMetadata": true } } } }, "responses": { "200": { "description": "Successful response!", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "List of nft collections.", "properties": { "contracts": { "type": "array", "items": { "type": "object", "description": "The object that represents an NFT collection", "properties": { "network": { "type": "string", "description": "Network identifier." }, "address": { "type": "string", "description": "Wallet address." }, "contract": { "type": "object", "description": "The contract object that has details of a contract", "properties": { "address": { "description": "Address of the held contract", "type": "string" }, "name": { "type": "string", "description": "String - NFT contract name." }, "symbol": { "type": "string", "description": "String - NFT contract symbol abbreviation." }, "totalSupply": { "type": "string", "description": "String - Total number of NFTs in a given NFT collection." }, "tokenType": { "type": "string", "enum": [ "ERC721", "ERC1155", "NO_SUPPORTED_NFT_STANDARD", "NOT_A_CONTRACT" ], "description": "String - For valid NFTs, 'ERC721' or 'ERC1155.' For invalid NFTs, a descriptive reason such as 'NO_SUPPORTED_NFT_STANDARD' if the input contract address doesn't support a known NFT standard, or 'NOT_A_CONTRACT' if there is no contract deployed at the input address." }, "contractDeployer": { "type": "string", "description": "String - Address that deployed the smart contract" }, "deployedBlockNumber": { "type": "number", "description": "Number - The Block Number when the deployment transaction is successfully mined" }, "openseaMetadata": { "type": "object", "description": "Note that the OpenSea metadata object is currently only available on ETH and Polygon Mainnet. Please reach out to us at support@alchemy.com if you would like to access this data on other networks.", "properties": { "floorPrice": { "type": "number", "description": "NFT floor price" }, "collectionName": { "type": "string", "description": "OpenSea collection name" }, "safelistRequestStatus": { "type": "string", "description": "Collection approval status within OpenSea. For more info, see the Opensea docs at docs.opensea.io/reference/collection-model" }, "imageUrl": { "type": "string", "description": "OpenSea CDN image URL" }, "description": { "type": "string", "description": "OpenSea collection description. Note: this value is truncated to 255 characters." }, "externalUrl": { "type": "string", "description": "Collection homepage" }, "twitterUsername": { "type": "string", "description": "The twitter username of the collection" }, "discordUrl": { "type": "string", "description": "The discord URL of the collection" }, "bannerImageUrl": { "type": "string", "description": "The banner image URL of the collection" }, "lastIngestedAt": { "type": "string", "description": "The timestamp when the collection was last ingested by us" } } }, "isSpam": { "type": "string", "description": "\"true\" if contract is spam, else \"false\". **Only available on paid tiers.**" }, "spamClassifications": { "description": "List of reasons why a contract was classified as spam. **Only available on paid tiers.**", "type": "array", "items": { "type": "string" } } } } } } }, "totalCount": { "type": "integer", "description": "Integer - Total number of NFTs (distinct `tokenIds`) owned by the given address." }, "pageKey": { "type": "string" } } }, "error": { "type": "object", "description": "Present on 200 responses only when one or more requested networks did not return data (upstream error or per-network timeout: 5s on paginated requests, 10s on fetch-all). When every requested network succeeds, the `error` key is omitted from the response entirely (it is not present-and-null). See [Handling partial failures](/docs/reference/portfolio-apis#handling-partial-failures) for the recommended client pattern.\n", "properties": { "message": { "type": "string", "description": "Human-readable summary of the partial failure. On the token endpoints this is `\"Failed to fetch tokens on certain networks\"`; on the NFT endpoints it is `\"Failed to fetch NFTs on certain networks\"`.\n" }, "partialErrors": { "type": "array", "description": "One entry per failed network. A network may appear more than once if the request body contained multiple entries covering that network.\n", "items": { "type": "object", "properties": { "network": { "type": "string", "description": "Network slug that failed (e.g. `eth-mainnet`, `robinhood-mainnet`)." }, "message": { "type": "string", "description": "Human-readable failure reason. Treat as an opaque string, not an enumerable error code. It does not distinguish upstream errors from per-network timeouts.\n" } }, "required": [ "network", "message" ] } } }, "required": [ "message", "partialErrors" ] } }, "required": [ "data" ] }, "examples": { "success": { "summary": "All networks succeeded", "value": { "data": { "contracts": [ { "network": "eth-mainnet", "address": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "contract": { "address": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d", "name": "BoredApeYachtClub", "symbol": "BAYC", "totalSupply": "10000", "tokenType": "ERC721" } } ], "totalCount": 1 } } }, "partialFailure": { "summary": "One or more networks failed (HTTP 200)", "value": { "data": { "contracts": [ { "network": "eth-mainnet", "address": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "contract": { "address": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d", "name": "BoredApeYachtClub", "symbol": "BAYC", "totalSupply": "10000", "tokenType": "ERC721" } } ], "totalCount": 1 }, "error": { "message": "Failed to fetch NFTs on certain networks", "partialErrors": [ { "network": "base-mainnet", "message": "Internal server error" }, { "network": "matic-mainnet", "message": "Internal server error" } ] } } } } } } }, "400": { "description": "Bad Request: Invalid input (e.g., malformed JSON).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Detailed error message." } }, "required": [ "message" ], "description": "Error details." } }, "required": [ "error" ] } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Detailed error message." } }, "required": [ "message" ], "description": "Error details." } }, "required": [ "error" ] } } } } }, "operationId": "get-nft-contracts-by-address" } }, "/{apiKey}/transfers/by-address": { "post": { "summary": "Transfers By Wallet (Beta)", "description": "**Beta:** This endpoint is production-ready and fully supported. While it's in beta, the API may still change, including breaking changes.\n\nFetches historical transfers (native, ERC-20, ERC-721, ERC-1155, special NFT, and internal) for a single wallet address and multiple networks. Returns a list of transfers ordered by `blockTimestamp`. Supported on 14 EVM networks — see the `networks` request-body field for the enumerated list.\n\nNote: the `internal` category is only supported on Ethereum Mainnet, Base Mainnet, Polygon Mainnet, Arc Mainnet, and Arc Testnet. The `specialnft` category is only supported on Ethereum Mainnet.\n\nThis endpoint fans out across every requested network and merges the results. A partially fulfilled request still returns HTTP 200 with every transfer that was retrieved successfully and a top-level `error.partialErrors` array. A partial error can apply to an entire network or to one unsupported category. If only a category is unsupported, transfers from other categories on the same network are still returned. Always process the `transfers` array even when `error` is present. See [Handling partial failures](/docs/reference/portfolio-apis#handling-partial-failures) for the recommended client pattern.\n", "tags": [ "Portfolio API Endpoints" ], "parameters": [ { "name": "apiKey", "in": "path", "schema": { "type": "string", "default": "docs-demo", "description": "For higher throughput, [create your own API key](https://dashboard.alchemy.com/signup)" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "The wallet address to fetch transfers for. A single address keeps the common wallet use case (all activity to and from one address) in a single request.\n", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }, "direction": { "type": "string", "enum": [ "to", "from", "both" ], "default": "both", "description": "Which side of the transfer `address` must match. `to` returns transfers received by the address, `from` returns transfers sent by it, and `both` returns transfers on either side.\n" }, "networks": { "type": "array", "maxItems": 5, "example": [ "eth-mainnet", "base-mainnet", "matic-mainnet" ], "items": { "type": "string", "enum": [ "eth-mainnet", "matic-mainnet", "arb-mainnet", "opt-mainnet", "base-mainnet", "bnb-mainnet", "celo-mainnet", "ronin-mainnet", "monad-mainnet", "monad-testnet", "robinhood-mainnet", "robinhood-testnet", "arc-mainnet", "arc-testnet" ] }, "description": "Networks to query. You can query up to 5 networks per request. Reach out if you need more.\n" }, "fromTimestamp": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (inclusive). Only transfers at or after this time are returned. Defaults to the beginning of chain history.\n", "example": "2026-08-01T00:00:00Z" }, "toTimestamp": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp (inclusive). Only transfers at or before this time are returned. Defaults to the current time.\n", "example": "2026-08-06T00:00:00Z" }, "order": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort order of results by `blockTimestamp`." }, "category": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "external", "internal", "erc20", "erc721", "erc1155", "specialnft" ] }, "description": "Transfer categories to fetch. **Required**, with no default — provide one or more of the listed categories.\n\n**Network support for `internal` and `specialnft`:** the `internal` category is only supported on Ethereum Mainnet (`eth-mainnet`), Base Mainnet (`base-mainnet`), Polygon Mainnet (`matic-mainnet`), Arc Mainnet (`arc-mainnet`), and Arc Testnet (`arc-testnet`). The `specialnft` category is only supported on Ethereum Mainnet (`eth-mainnet`). All other categories are supported on every network listed under `networks`.\n" }, "contractAddresses": { "type": "array", "items": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "description": "Filter results to these token contract addresses. Applies to the `erc20`, `erc721`, `erc1155`, and `specialnft` categories.\n" }, "excludeZeroValue": { "type": "boolean", "default": true, "description": "Whether to exclude zero-value `external`, `internal`, and `erc20` transfers. This option does not affect `erc721`, `erc1155`, or `specialnft` transfers.\n" }, "maxCount": { "type": "integer", "default": 100, "description": "Maximum number of transfers to return per page." }, "pageKey": { "type": "string", "description": "Opaque cursor returned by a previous response. Pass it back to fetch the next page.\n" } }, "required": [ "address", "networks", "category" ] }, "example": { "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "direction": "both", "networks": [ "eth-mainnet", "base-mainnet", "matic-mainnet" ], "fromTimestamp": "2026-08-01T00:00:00Z", "toTimestamp": "2026-08-06T00:00:00Z", "category": [ "external", "erc20", "erc721", "erc1155" ], "order": "desc", "maxCount": 100 } } } }, "responses": { "200": { "description": "Successful response!", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfers": { "type": "array", "description": "Transfers matching the query, merged across all requested networks and ordered by `blockTimestamp`. If nothing matches, the array is empty.\n", "items": { "type": "object", "description": "A historical transfer that matches the request.", "properties": { "network": { "type": "string", "description": "The network this transfer occurred on." }, "blockNum": { "type": "string", "description": "Block number as a hex string. Not comparable across networks — use `blockTimestamp` for ordering.\n" }, "blockTimestamp": { "type": "string", "format": "date-time", "description": "ISO-8601 block timestamp. This field is the cross-chain sort key and is always returned.\n" }, "category": { "type": "string", "enum": [ "external", "internal", "erc20", "erc721", "erc1155", "specialnft" ], "description": "Transfer category." }, "hash": { "type": "string", "description": "Transaction hash." }, "from": { "type": "string", "description": "Sender address." }, "to": { "type": [ "string", "null" ], "description": "Recipient address. `null` on contract creation." }, "contractAddress": { "type": "string", "description": "Token contract address. Present for `erc20`, `erc721`, `erc1155`, and `specialnft` transfers. Omitted for `external` and `internal` transfers.\n" }, "uniqueId": { "type": "string", "description": "Stable per-transfer identifier. Format varies by category: `{hash}:log:{logIndex}` (erc20/erc721/erc1155/specialnft), `{hash}:external`, `{hash}:internal:{traceAddress}`.\n" }, "fungible": { "type": "object", "description": "Fungible-transfer details for the `external`, `internal`, and `erc20` categories. Omitted for NFT (`erc721`/`erc1155`/`specialnft`) transfers.\n", "properties": { "rawValue": { "type": "string", "description": "Raw on-chain amount as a hex string (unscaled)." }, "value": { "type": [ "number", "null" ], "description": "Human-readable amount, scaled by `decimals`. If metadata is missing, this field is `null`.\n" }, "decimals": { "type": [ "integer", "null" ], "description": "Number of decimals for the token. If metadata is missing, this field is `null`.\n" }, "asset": { "type": [ "string", "null" ], "description": "Token symbol, such as USDC or ETH. If metadata is missing, this field is `null`.\n" } } }, "nfts": { "type": "object", "description": "NFT-transfer details for the `erc721`, `erc1155`, and `specialnft` categories. Omitted for fungible transfers.\n", "properties": { "tokens": { "type": "array", "description": "The token IDs and amounts transferred in this event.", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "description": "Token ID as a hex string." }, "amount": { "type": "string", "pattern": "^0x[0-9a-fA-F]+$", "example": "0x1", "description": "Raw transferred amount as a 0x-prefixed hexadecimal string. Always `0x1` for ERC-721. ERC-1155 amounts can contain leading zeroes, for example `0x01`.\n" } } } } } } }, "required": [ "network", "blockNum", "blockTimestamp", "category", "hash", "from", "to", "uniqueId" ] } }, "pageKey": { "type": [ "string", "null" ], "description": "Opaque base64url cursor. Pass it as `pageKey` on the next request to fetch the following page. `null` indicates that no more results exist.\n" }, "error": { "type": "object", "description": "Present when the request is only partially fulfilled. The `transfers` array still contains every result that was retrieved successfully. A partial error can apply to an entire network or to one unsupported category on a network. If only a category is unsupported, transfers from other categories on that same network are still returned. When the full request succeeds, the `error` key is omitted. See [Handling partial failures](/docs/reference/portfolio-apis#handling-partial-failures) for the recommended client pattern.\n", "properties": { "message": { "type": "string", "description": "Human-readable summary. Do not use this text for programmatic decisions." }, "partialErrors": { "type": "array", "description": "Details about the parts of the request that were not fulfilled. A network listed here can still appear in `transfers` when only one of its requested categories is unsupported.\n", "items": { "type": "object", "properties": { "network": { "type": "string", "description": "The affected network." }, "state": { "type": "string", "enum": [ "unsupported", "timeout", "error" ], "description": "Stable failure state. `unsupported` is permanent unless the request changes; `timeout` and `error` can be retried with a bounded retry policy.\n" }, "message": { "type": "string", "description": "Human-readable context about the partial error. Do not use this text for programmatic decisions.\n" } }, "required": [ "network", "state", "message" ] } } }, "required": [ "message", "partialErrors" ] } }, "required": [ "transfers" ] }, "examples": { "success": { "summary": "All networks succeeded", "value": { "transfers": [ { "network": "base-mainnet", "blockNum": "0x1410a3b", "blockTimestamp": "2026-08-05T23:58:41Z", "category": "erc20", "hash": "0xabc123…", "from": "0x1f98abcd…", "to": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "contractAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "uniqueId": "0xabc123…:log:12", "fungible": { "rawValue": "0xee6b2800", "value": 250, "decimals": 6, "asset": "USDC" } }, { "network": "eth-mainnet", "blockNum": "0x15f9a2d", "blockTimestamp": "2026-08-05T23:55:12Z", "category": "external", "hash": "0xdef456…", "from": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "to": "0x7a250d...", "uniqueId": "0xdef456…:external", "fungible": { "rawValue": "0x6f05b59d3b20000", "value": 0.5, "decimals": 18, "asset": "ETH" } }, { "network": "base-mainnet", "blockNum": "0x1410a10", "blockTimestamp": "2026-08-05T23:50:03Z", "category": "erc721", "hash": "0x9a8b7c…", "from": "0x0000000000000000000000000000000000000000", "to": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "contractAddress": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D", "uniqueId": "0x9a8b7c…:log:0", "nfts": { "tokens": [ { "tokenId": "0x1a4", "amount": "0x1" } ] } } ], "pageKey": "eyJ0cyI6IjIwMjYtMDgtMDVUMjM6NTU6MTJaIiwibmV0Ijp7ImV0aC1tYWlubmV0IjoiMHgxNWY5YTJkOjMifX0=" } }, "partialFailure": { "summary": "One or more networks failed (HTTP 200)", "value": { "transfers": [ { "network": "base-mainnet", "blockNum": "0x1410a3b", "blockTimestamp": "2026-08-05T23:58:41Z", "category": "erc20", "hash": "0xabc123…", "from": "0x1f98abcd…", "to": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "contractAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "uniqueId": "0xabc123…:log:12", "fungible": { "rawValue": "0xee6b2800", "value": 250, "decimals": 6, "asset": "USDC" } } ], "pageKey": null, "error": { "message": "Failed to fetch transfers on certain networks", "partialErrors": [ { "network": "matic-mainnet", "state": "timeout", "message": "upstream request timed out" } ] } } }, "unsupportedCategory": { "summary": "A category is unsupported while another category succeeds (HTTP 200)", "value": { "transfers": [ { "network": "base-mainnet", "blockNum": "0x3160d69", "blockTimestamp": "2026-09-25T13:31:33Z", "category": "erc20", "hash": "0x4a265a6a…", "from": "0x7437cc0e…", "to": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "contractAddress": "0x88fb150bdc53a65fe94dea0c9ba0a6daf8c6e196", "uniqueId": "0x4a265a6a…:log:946", "fungible": { "rawValue": "0x5a58994db8be9", "value": 0.001589385210072041, "decimals": 18, "asset": "LINK" } } ], "pageKey": "eyJ2ZXJzaW9uIjoxLCJvcmRlciI6ImRlc2MiLCIuLi4iOiIuLi4ifQ", "error": { "message": "Some requested networks were not returned", "partialErrors": [ { "network": "base-mainnet", "state": "unsupported", "message": "The 'specialnft' category is not supported for network 'base-mainnet'. Check the Alchemy documentation for supported networks.\n" } ] } } } } } } }, "400": { "description": "Bad Request: Invalid input (e.g., malformed JSON).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Detailed error message." } }, "required": [ "message" ], "description": "Error details." } }, "required": [ "error" ] } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Detailed error message." } }, "required": [ "message" ], "description": "Error details." } }, "required": [ "error" ] } } } } }, "operationId": "get-transfers-by-address" } } }, "components": { "schemas": { "ByAddressRequest": { "type": "object", "properties": { "addresses": { "type": "array", "description": "Array of wallet addresses and the networks to query them on. Maximum 2 addresses and maximum 5 networks per address.\n", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Wallet address.", "example": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "default": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152" }, "networks": { "type": "array", "example": [ "eth-mainnet", "base-mainnet", "matic-mainnet" ], "items": { "type": "string", "default": "eth-mainnet" }, "description": "Network identifier (e.g., eth-mainnet). Find more network enums [here](https://dashboard.alchemy.com/chains)" } }, "required": [ "address", "networks" ] } } }, "required": [ "addresses" ] }, "ByAddressRequestWith3PairsAnd20Networks": { "type": "object", "properties": { "addresses": { "type": "array", "description": "Array of address and networks pairs (limit 3 pairs, max 20 networks). Networks should match network enums.\n", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Wallet address.", "example": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "default": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152" }, "networks": { "type": "array", "example": [ "eth-mainnet", "base-mainnet", "matic-mainnet" ], "items": { "type": "string", "default": "eth-mainnet" }, "description": "Network identifier (e.g., eth-mainnet). Find more network enums [here](https://dashboard.alchemy.com/chains)" } }, "required": [ "address", "networks" ] } }, "includeNativeTokens": { "type": "boolean", "description": "Whether to include each chain's native token in the response (e.g. ETH on Ethereum). The native token will have a null contract address.", "example": true, "default": true }, "includeErc20Tokens": { "description": "Boolean - if set to `true`, returns ERC-20 tokens. Setting this to false will reduce payload size and may result in a faster API call.", "type": "boolean", "default": true }, "includeBlockMetadata": { "description": "Boolean - if set to `true`, includes a `blockMetadata` object inside `data` (alongside `pageKey`) mapping each requested network to the block used to compute the returned balances (`blockNumber`, `blockHash`, `blockTimestamp`). Failed networks are still present as keys but map to `null`.", "type": "boolean", "default": false } }, "required": [ "addresses" ] }, "ByAddressRequestWithOptions": { "type": "object", "properties": { "addresses": { "type": "array", "description": "Array of wallet addresses and the networks to query them on. Maximum 2 addresses and maximum 5 networks per address.\n", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Wallet address.", "example": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "default": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152" }, "networks": { "type": "array", "example": [ "eth-mainnet", "base-mainnet", "matic-mainnet" ], "items": { "type": "string", "default": "eth-mainnet" }, "description": "Network identifier (e.g., eth-mainnet). Find more network enums [here](https://dashboard.alchemy.com/chains)" } }, "required": [ "address", "networks" ] } }, "withMetadata": { "description": "Boolean - if set to `true`, returns metadata. Setting this to false will reduce payload size and may result in a faster API call.", "type": "boolean", "default": true }, "withPrices": { "description": "Boolean - if set to `true`, returns token prices. Setting this to false will reduce payload size and may result in a faster API call.", "type": "boolean", "default": true }, "includeNativeTokens": { "type": "boolean", "description": "Whether to include each chain's native token in the response (e.g. ETH on Ethereum). The native token will have a null contract address.", "example": true, "default": true }, "includeErc20Tokens": { "description": "Boolean - if set to `true`, returns ERC-20 tokens. Setting this to false will reduce payload size and may result in a faster API call.", "type": "boolean", "default": true }, "includeBlockMetadata": { "description": "Boolean - if set to `true`, includes a `blockMetadata` object inside `data` (alongside `pageKey`) mapping each requested network to the block used to compute the returned balances (`blockNumber`, `blockHash`, `blockTimestamp`). Failed networks are still present as keys but map to `null`.", "type": "boolean", "default": false } }, "required": [ "addresses" ] }, "ByAddressRequestWithNFTOptionsAndPaging": { "type": "object", "properties": { "addresses": { "type": "array", "description": "Array of address and networks pairs (limit 2 pairs, max 15 networks each). Networks should match network enums.\n", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Wallet address.", "example": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "default": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152" }, "networks": { "type": "array", "example": [ "eth-mainnet", "base-mainnet", "matic-mainnet" ], "items": { "type": "string", "enum": [ "eth-mainnet", "eth-sepolia", "eth-holesky", "avax-mainnet", "avax-fuji", "zksync-mainnet", "opt-mainnet", "matic-mainnet", "matic-amoy", "arb-mainnet", "arb-sepolia", "blast-mainnet", "blast-sepolia", "base-mainnet", "base-sepolia", "soneium-mainnet", "soneium-minato", "scroll-mainnet", "shape-mainnet", "shape-sepolia", "lens-mainnet", "lens-sepolia", "starknet-mainnet", "starknet-sepolia", "rootstock-mainnet", "rootstock-testnet", "linea-mainnet", "linea-sepolia", "settlus-septestnet", "abstract-mainnet", "abstract-testnet", "apechain-mainnet" ], "default": "eth-mainnet" }, "description": "Network identifier (e.g., eth-mainnet). Find more network enums [here](https://dashboard.alchemy.com/chains)" }, "excludeFilters": { "type": "array", "items": { "type": "string", "enum": [ "SPAM", "AIRDROPS" ], "default": "SPAM" } }, "includeFilters": { "type": "array", "items": { "type": "string", "enum": [ "SPAM", "AIRDROPS" ], "default": "SPAM" } }, "spamConfidenceLevel": { "type": "string", "enum": [ "VERY_HIGH", "HIGH", "MEDIUM", "LOW" ] } }, "required": [ "address", "networks" ] } }, "withMetadata": { "description": "Boolean - if set to `true`, returns metadata. Setting this to false will reduce payload size and may result in a faster API call.", "type": "boolean", "default": true }, "pageKey": { "type": "string" }, "pageSize": { "type": "integer", "default": 100 } }, "required": [ "addresses" ] }, "ByAddressRequestWithNFTOptions": { "type": "object", "properties": { "addresses": { "type": "array", "description": "Array of wallet addresses and the networks to query them on. Maximum 2 addresses and maximum 5 networks per address.\n", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Wallet address.", "example": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "default": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152" }, "networks": { "type": "array", "example": [ "eth-mainnet", "base-mainnet", "matic-mainnet" ], "items": { "type": "string", "default": "eth-mainnet" }, "description": "Network identifier (e.g., eth-mainnet). Find more network enums [here](https://dashboard.alchemy.com/chains)" } }, "required": [ "address", "networks" ] } }, "withMetadata": { "description": "Boolean - if set to `true`, returns metadata. Setting this to false will reduce payload size and may result in a faster API call.", "type": "boolean", "default": true } }, "required": [ "addresses" ] }, "AddressItemForNFTOwnership": { "type": "object", "properties": { "address": { "type": "string", "description": "Wallet address.", "example": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152", "default": "0x1E6E8695FAb3Eb382534915eA8d7Cc1D1994B152" }, "networks": { "type": "array", "example": [ "eth-mainnet", "base-mainnet", "matic-mainnet" ], "items": { "type": "string", "enum": [ "eth-mainnet", "eth-sepolia", "eth-holesky", "avax-mainnet", "avax-fuji", "zksync-mainnet", "opt-mainnet", "matic-mainnet", "matic-amoy", "arb-mainnet", "arb-sepolia", "blast-mainnet", "blast-sepolia", "base-mainnet", "base-sepolia", "soneium-mainnet", "soneium-minato", "scroll-mainnet", "shape-mainnet", "shape-sepolia", "lens-mainnet", "lens-sepolia", "starknet-mainnet", "starknet-sepolia", "rootstock-mainnet", "rootstock-testnet", "linea-mainnet", "linea-sepolia", "settlus-septestnet", "abstract-mainnet", "abstract-testnet", "apechain-mainnet" ], "default": "eth-mainnet" }, "description": "Network identifier (e.g., eth-mainnet). Find more network enums [here](https://dashboard.alchemy.com/chains)" }, "excludeFilters": { "type": "array", "items": { "type": "string", "enum": [ "SPAM", "AIRDROPS" ], "default": "SPAM" } }, "includeFilters": { "type": "array", "items": { "type": "string", "enum": [ "SPAM", "AIRDROPS" ], "default": "SPAM" } }, "spamConfidenceLevel": { "type": "string", "enum": [ "VERY_HIGH", "HIGH", "MEDIUM", "LOW" ] } }, "required": [ "address", "networks" ] }, "PartialError": { "type": "object", "description": "Present on 200 responses only when one or more requested networks did not return data (upstream error or per-network timeout: 5s on paginated requests, 10s on fetch-all). When every requested network succeeds, the `error` key is omitted from the response entirely (it is not present-and-null). See [Handling partial failures](/docs/reference/portfolio-apis#handling-partial-failures) for the recommended client pattern.\n", "properties": { "message": { "type": "string", "description": "Human-readable summary of the partial failure. On the token endpoints this is `\"Failed to fetch tokens on certain networks\"`; on the NFT endpoints it is `\"Failed to fetch NFTs on certain networks\"`.\n" }, "partialErrors": { "type": "array", "description": "One entry per failed network. A network may appear more than once if the request body contained multiple entries covering that network.\n", "items": { "type": "object", "properties": { "network": { "type": "string", "description": "Network slug that failed (e.g. `eth-mainnet`, `robinhood-mainnet`)." }, "message": { "type": "string", "description": "Human-readable failure reason. Treat as an opaque string, not an enumerable error code. It does not distinguish upstream errors from per-network timeouts.\n" } }, "required": [ "network", "message" ] } } }, "required": [ "message", "partialErrors" ] }, "BlockMetadata": { "type": "object", "description": "Block metadata for each network in the response, keyed by network slug (e.g. `eth-mainnet`, `matic-mainnet`). Present only when the request sets `includeBlockMetadata` to `true`. Every requested network appears as a key: successful networks map to a `BlockMetadataEntry`, and networks that failed map to `null` (their reason is reported in `error.partialErrors`).\n", "additionalProperties": { "oneOf": [ { "type": "object", "description": "Block used to compute the returned balances on a given network. `null` for networks that failed (see `error.partialErrors` for the reason).\n", "properties": { "blockNumber": { "type": "string", "description": "Hex-encoded block number.", "example": "0x18a6825" }, "blockHash": { "type": "string", "description": "Block hash.", "example": "0xb9587b181217d4c32c45e614d85c92c857dac76b57e15d36fb7d38b27dcecb92" }, "blockTimestamp": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp when the block was produced.", "example": "2026-08-27T16:45:59.000Z" } }, "required": [ "blockNumber", "blockHash", "blockTimestamp" ] }, { "type": "null" } ] }, "example": { "eth-mainnet": { "blockNumber": "0x18a6825", "blockHash": "0xb9587b181217d4c32c45e614d85c92c857dac76b57e15d36fb7d38b27dcecb92", "blockTimestamp": "2026-08-27T16:45:59.000Z" }, "matic-mainnet": { "blockNumber": "0x5877288", "blockHash": "0x4ddbc1d12e14909468c49efd2771d1a09dec2850a823e0d9942db54d54633e43", "blockTimestamp": "2026-08-27T16:46:07.000Z" }, "base-mainnet": null } }, "TransfersResponse": { "type": "object", "properties": { "transfers": { "type": "array", "description": "Transfers matching the query, merged across all requested networks and ordered by `blockTimestamp`. If nothing matches, the array is empty.\n", "items": { "type": "object", "description": "A historical transfer that matches the request.", "properties": { "network": { "type": "string", "description": "The network this transfer occurred on." }, "blockNum": { "type": "string", "description": "Block number as a hex string. Not comparable across networks — use `blockTimestamp` for ordering.\n" }, "blockTimestamp": { "type": "string", "format": "date-time", "description": "ISO-8601 block timestamp. This field is the cross-chain sort key and is always returned.\n" }, "category": { "type": "string", "enum": [ "external", "internal", "erc20", "erc721", "erc1155", "specialnft" ], "description": "Transfer category." }, "hash": { "type": "string", "description": "Transaction hash." }, "from": { "type": "string", "description": "Sender address." }, "to": { "type": [ "string", "null" ], "description": "Recipient address. `null` on contract creation." }, "contractAddress": { "type": "string", "description": "Token contract address. Present for `erc20`, `erc721`, `erc1155`, and `specialnft` transfers. Omitted for `external` and `internal` transfers.\n" }, "uniqueId": { "type": "string", "description": "Stable per-transfer identifier. Format varies by category: `{hash}:log:{logIndex}` (erc20/erc721/erc1155/specialnft), `{hash}:external`, `{hash}:internal:{traceAddress}`.\n" }, "fungible": { "type": "object", "description": "Fungible-transfer details for the `external`, `internal`, and `erc20` categories. Omitted for NFT (`erc721`/`erc1155`/`specialnft`) transfers.\n", "properties": { "rawValue": { "type": "string", "description": "Raw on-chain amount as a hex string (unscaled)." }, "value": { "type": [ "number", "null" ], "description": "Human-readable amount, scaled by `decimals`. If metadata is missing, this field is `null`.\n" }, "decimals": { "type": [ "integer", "null" ], "description": "Number of decimals for the token. If metadata is missing, this field is `null`.\n" }, "asset": { "type": [ "string", "null" ], "description": "Token symbol, such as USDC or ETH. If metadata is missing, this field is `null`.\n" } } }, "nfts": { "type": "object", "description": "NFT-transfer details for the `erc721`, `erc1155`, and `specialnft` categories. Omitted for fungible transfers.\n", "properties": { "tokens": { "type": "array", "description": "The token IDs and amounts transferred in this event.", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "description": "Token ID as a hex string." }, "amount": { "type": "string", "pattern": "^0x[0-9a-fA-F]+$", "example": "0x1", "description": "Raw transferred amount as a 0x-prefixed hexadecimal string. Always `0x1` for ERC-721. ERC-1155 amounts can contain leading zeroes, for example `0x01`.\n" } } } } } } }, "required": [ "network", "blockNum", "blockTimestamp", "category", "hash", "from", "to", "uniqueId" ] } }, "pageKey": { "type": [ "string", "null" ], "description": "Opaque base64url cursor. Pass it as `pageKey` on the next request to fetch the following page. `null` indicates that no more results exist.\n" }, "error": { "type": "object", "description": "Present when the request is only partially fulfilled. The `transfers` array still contains every result that was retrieved successfully. A partial error can apply to an entire network or to one unsupported category on a network. If only a category is unsupported, transfers from other categories on that same network are still returned. When the full request succeeds, the `error` key is omitted. See [Handling partial failures](/docs/reference/portfolio-apis#handling-partial-failures) for the recommended client pattern.\n", "properties": { "message": { "type": "string", "description": "Human-readable summary. Do not use this text for programmatic decisions." }, "partialErrors": { "type": "array", "description": "Details about the parts of the request that were not fulfilled. A network listed here can still appear in `transfers` when only one of its requested categories is unsupported.\n", "items": { "type": "object", "properties": { "network": { "type": "string", "description": "The affected network." }, "state": { "type": "string", "enum": [ "unsupported", "timeout", "error" ], "description": "Stable failure state. `unsupported` is permanent unless the request changes; `timeout` and `error` can be retried with a bounded retry policy.\n" }, "message": { "type": "string", "description": "Human-readable context about the partial error. Do not use this text for programmatic decisions.\n" } }, "required": [ "network", "state", "message" ] } } }, "required": [ "message", "partialErrors" ] } }, "required": [ "transfers" ] }, "TokensResponse": { "type": "object", "properties": { "data": { "type": "object", "description": "List of tokens by address, with prices and metadata.", "properties": { "tokens": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Wallet address." }, "network": { "type": "string", "description": "Network identifier." }, "tokenAddress": { "type": [ "string", "null" ], "description": "Token contract address. `null` for a chain's native token." }, "tokenBalance": { "type": "string", "description": "Balance of that particular token." }, "tokenMetadata": { "type": "object", "properties": { "decimals": { "type": "integer", "description": "Number of decimals the token uses" }, "logo": { "type": "string", "description": "URL of the token's logo image" }, "name": { "type": "string", "description": "Token's name" }, "symbol": { "type": "string", "description": "Token's symbol" } } }, "tokenPrices": { "type": "array", "description": "List of price information.", "items": { "type": "object", "properties": { "currency": { "type": "string", "example": "usd" }, "value": { "type": "string", "example": "4608.2208671202" }, "lastUpdatedAt": { "type": "string", "format": "date-time", "example": "2025-08-26T20:17:27Z" } }, "required": [ "currency", "value", "lastUpdatedAt" ] } }, "error": { "type": [ "string", "null" ], "description": "Error message if applicable." } }, "required": [ "network", "address", "tokenAddress", "tokenBalance" ] } }, "pageKey": { "type": "string" }, "blockMetadata": { "type": "object", "description": "Block metadata for each network in the response, keyed by network slug (e.g. `eth-mainnet`, `matic-mainnet`). Present only when the request sets `includeBlockMetadata` to `true`. Every requested network appears as a key: successful networks map to a `BlockMetadataEntry`, and networks that failed map to `null` (their reason is reported in `error.partialErrors`).\n", "additionalProperties": { "oneOf": [ { "type": "object", "description": "Block used to compute the returned balances on a given network. `null` for networks that failed (see `error.partialErrors` for the reason).\n", "properties": { "blockNumber": { "type": "string", "description": "Hex-encoded block number.", "example": "0x18a6825" }, "blockHash": { "type": "string", "description": "Block hash.", "example": "0xb9587b181217d4c32c45e614d85c92c857dac76b57e15d36fb7d38b27dcecb92" }, "blockTimestamp": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp when the block was produced.", "example": "2026-08-27T16:45:59.000Z" } }, "required": [ "blockNumber", "blockHash", "blockTimestamp" ] }, { "type": "null" } ] }, "example": { "eth-mainnet": { "blockNumber": "0x18a6825", "blockHash": "0xb9587b181217d4c32c45e614d85c92c857dac76b57e15d36fb7d38b27dcecb92", "blockTimestamp": "2026-08-27T16:45:59.000Z" }, "matic-mainnet": { "blockNumber": "0x5877288", "blockHash": "0x4ddbc1d12e14909468c49efd2771d1a09dec2850a823e0d9942db54d54633e43", "blockTimestamp": "2026-08-27T16:46:07.000Z" }, "base-mainnet": null } } }, "required": [ "tokens" ] }, "error": { "type": "object", "description": "Present on 200 responses only when one or more requested networks did not return data (upstream error or per-network timeout: 5s on paginated requests, 10s on fetch-all). When every requested network succeeds, the `error` key is omitted from the response entirely (it is not present-and-null). See [Handling partial failures](/docs/reference/portfolio-apis#handling-partial-failures) for the recommended client pattern.\n", "properties": { "message": { "type": "string", "description": "Human-readable summary of the partial failure. On the token endpoints this is `\"Failed to fetch tokens on certain networks\"`; on the NFT endpoints it is `\"Failed to fetch NFTs on certain networks\"`.\n" }, "partialErrors": { "type": "array", "description": "One entry per failed network. A network may appear more than once if the request body contained multiple entries covering that network.\n", "items": { "type": "object", "properties": { "network": { "type": "string", "description": "Network slug that failed (e.g. `eth-mainnet`, `robinhood-mainnet`)." }, "message": { "type": "string", "description": "Human-readable failure reason. Treat as an opaque string, not an enumerable error code. It does not distinguish upstream errors from per-network timeouts.\n" } }, "required": [ "network", "message" ] } } }, "required": [ "message", "partialErrors" ] } }, "required": [ "data" ] }, "TokenBalancesResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tokens": { "type": "array", "description": "List of token balances by address.", "items": { "type": "object", "properties": { "network": { "type": "string", "description": "Network identifier." }, "address": { "type": "string", "description": "Wallet address." }, "tokenAddress": { "type": [ "string", "null" ], "description": "Token contract address. `null` for a chain's native token." }, "tokenBalance": { "type": "string", "description": "Balance of that particular token." } }, "required": [ "network", "address", "tokenAddress", "tokenBalance" ] } }, "pageKey": { "type": "string" }, "blockMetadata": { "type": "object", "description": "Block metadata for each network in the response, keyed by network slug (e.g. `eth-mainnet`, `matic-mainnet`). Present only when the request sets `includeBlockMetadata` to `true`. Every requested network appears as a key: successful networks map to a `BlockMetadataEntry`, and networks that failed map to `null` (their reason is reported in `error.partialErrors`).\n", "additionalProperties": { "oneOf": [ { "type": "object", "description": "Block used to compute the returned balances on a given network. `null` for networks that failed (see `error.partialErrors` for the reason).\n", "properties": { "blockNumber": { "type": "string", "description": "Hex-encoded block number.", "example": "0x18a6825" }, "blockHash": { "type": "string", "description": "Block hash.", "example": "0xb9587b181217d4c32c45e614d85c92c857dac76b57e15d36fb7d38b27dcecb92" }, "blockTimestamp": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp when the block was produced.", "example": "2026-08-27T16:45:59.000Z" } }, "required": [ "blockNumber", "blockHash", "blockTimestamp" ] }, { "type": "null" } ] }, "example": { "eth-mainnet": { "blockNumber": "0x18a6825", "blockHash": "0xb9587b181217d4c32c45e614d85c92c857dac76b57e15d36fb7d38b27dcecb92", "blockTimestamp": "2026-08-27T16:45:59.000Z" }, "matic-mainnet": { "blockNumber": "0x5877288", "blockHash": "0x4ddbc1d12e14909468c49efd2771d1a09dec2850a823e0d9942db54d54633e43", "blockTimestamp": "2026-08-27T16:46:07.000Z" }, "base-mainnet": null } } }, "required": [ "tokens" ] }, "error": { "type": "object", "description": "Present on 200 responses only when one or more requested networks did not return data (upstream error or per-network timeout: 5s on paginated requests, 10s on fetch-all). When every requested network succeeds, the `error` key is omitted from the response entirely (it is not present-and-null). See [Handling partial failures](/docs/reference/portfolio-apis#handling-partial-failures) for the recommended client pattern.\n", "properties": { "message": { "type": "string", "description": "Human-readable summary of the partial failure. On the token endpoints this is `\"Failed to fetch tokens on certain networks\"`; on the NFT endpoints it is `\"Failed to fetch NFTs on certain networks\"`.\n" }, "partialErrors": { "type": "array", "description": "One entry per failed network. A network may appear more than once if the request body contained multiple entries covering that network.\n", "items": { "type": "object", "properties": { "network": { "type": "string", "description": "Network slug that failed (e.g. `eth-mainnet`, `robinhood-mainnet`)." }, "message": { "type": "string", "description": "Human-readable failure reason. Treat as an opaque string, not an enumerable error code. It does not distinguish upstream errors from per-network timeouts.\n" } }, "required": [ "network", "message" ] } } }, "required": [ "message", "partialErrors" ] } }, "required": [ "data" ] }, "NFTByOwnerResponse": { "type": "object", "properties": { "data": { "type": "object", "description": "List of nfts by address with appropriate metadata.", "properties": { "ownedNfts": { "type": "array", "items": { "type": "object", "description": "The object that represents an NFT and has all data corresponding to that NFT", "properties": { "network": { "type": "string", "description": "Network identifier." }, "address": { "type": "string", "description": "Wallet address." }, "contract": { "type": "object", "description": "The contract object that has details of a contract", "properties": { "address": { "description": "Address of the held contract", "type": "string" }, "name": { "type": "string", "description": "String - NFT contract name." }, "symbol": { "type": "string", "description": "String - NFT contract symbol abbreviation." }, "totalSupply": { "type": "string", "description": "String - Total number of NFTs in a given NFT collection." }, "tokenType": { "type": "string", "enum": [ "ERC721", "ERC1155", "NO_SUPPORTED_NFT_STANDARD", "NOT_A_CONTRACT" ], "description": "String - For valid NFTs, 'ERC721' or 'ERC1155.' For invalid NFTs, a descriptive reason such as 'NO_SUPPORTED_NFT_STANDARD' if the input contract address doesn't support a known NFT standard, or 'NOT_A_CONTRACT' if there is no contract deployed at the input address." }, "contractDeployer": { "type": "string", "description": "String - Address that deployed the smart contract" }, "deployedBlockNumber": { "type": "number", "description": "Number - The Block Number when the deployment transaction is successfully mined" }, "openseaMetadata": { "type": "object", "description": "Note that the OpenSea metadata object is currently only available on ETH and Polygon Mainnet. Please reach out to us at support@alchemy.com if you would like to access this data on other networks.", "properties": { "floorPrice": { "type": "number", "description": "NFT floor price" }, "collectionName": { "type": "string", "description": "OpenSea collection name" }, "safelistRequestStatus": { "type": "string", "description": "Collection approval status within OpenSea. For more info, see the Opensea docs at docs.opensea.io/reference/collection-model" }, "imageUrl": { "type": "string", "description": "OpenSea CDN image URL" }, "description": { "type": "string", "description": "OpenSea collection description. Note: this value is truncated to 255 characters." }, "externalUrl": { "type": "string", "description": "Collection homepage" }, "twitterUsername": { "type": "string", "description": "The twitter username of the collection" }, "discordUrl": { "type": "string", "description": "The discord URL of the collection" }, "bannerImageUrl": { "type": "string", "description": "The banner image URL of the collection" }, "lastIngestedAt": { "type": "string", "description": "The timestamp when the collection was last ingested by us" } } }, "isSpam": { "type": "string", "description": "\"true\" if contract is spam, else \"false\". **Only available on paid tiers.**" }, "spamClassifications": { "description": "List of reasons why a contract was classified as spam. **Only available on paid tiers.**", "type": "array", "items": { "type": "string" } } } }, "tokenId": { "type": "string", "default": "44" }, "tokenType": { "type": "string" }, "name": { "type": "string", "description": "String - Name of the NFT asset." }, "description": { "type": "string", "description": "String - Brief human-readable description" }, "image": { "type": "object", "description": "Details of the image corresponding to this contract", "properties": { "cachedUrl": { "type": "string", "description": "The Url of the image stored in Alchemy cache" }, "thumbnailUrl": { "type": "string", "description": "The Url that has the thumbnail version of the NFT" }, "pngUrl": { "type": "string", "description": "The Url that has the NFT image in png" }, "contentType": { "type": "string", "description": "The Url of the image stored in Alchemy cache" }, "size": { "type": "integer", "description": "The size of the media asset in bytes." }, "originalUrl": { "type": "string", "description": "The original Url of the image coming straight from the smart contract" } } }, "raw": { "type": "object", "description": "Raw details of the NFT like its tokenUri and metadata info obtained directly from the smart contract", "properties": { "tokenUri": { "type": "string", "description": "String - Uri representing the location of the NFT's original metadata blob. This is a backup for you to parse when the metadata field is not automatically populated." }, "metadata": { "type": "object", "description": "Relevant metadata for NFT contract. This is useful for viewing image url, traits, etc. without having to follow the metadata url in tokenUri to parse manually.", "properties": { "image": { "type": "string", "description": "String - URL to the NFT asset image. Can be standard URLs pointing to images on conventional servers, IPFS, or Arweave. Most types of images (SVGs, PNGs, JPEGs, etc.) are supported by NFT marketplaces." }, "name": { "type": "string", "description": "String - Name of the NFT asset." }, "description": { "type": "string", "description": "String - Human-readable description of the NFT asset. (Markdown is supported/rendered on OpenSea and other NFT platforms)" }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "trait_type": { "type": "string" } } }, "description": "Object - Traits/attributes/characteristics for each NFT asset." } } }, "error": { "type": "string", "description": "String - A string describing a particular reason that we were unable to fetch complete metadata for the NFT." } } }, "collection": { "type": "object", "description": "The collection object that has details of a collection", "properties": { "name": { "type": "string", "description": "String - Collection name" }, "slug": { "type": "string", "description": "String - OpenSea collection slug" }, "externalUrl": { "type": "string", "description": "String - URL for the external site of the collection" }, "bannerImageUrl": { "type": "string", "description": "String - Banner image URL for the collection" } } }, "tokenUri": { "type": "string", "description": "String - Uri representing the location of the NFT's original metadata blob. This is a backup for you to parse when the metadata field is not automatically populated." }, "timeLastUpdated": { "type": "string", "description": "String - ISO timestamp of the last cache refresh for the information returned in the metadata field." }, "acquiredAt": { "type": "object", "description": "Only present if the request specified `orderBy=transferTime`.", "properties": { "blockTimestamp": { "type": "string", "description": "Block timestamp of the block where the NFT was most recently acquired." }, "blockNumber": { "type": "string", "description": "Block number of the block where the NFT was most recently acquired." } } } } } }, "totalCount": { "type": "integer", "description": "Integer - Total number of NFTs (distinct `tokenIds`) owned by the given address." }, "pageKey": { "type": "string" } } }, "error": { "type": "object", "description": "Present on 200 responses only when one or more requested networks did not return data (upstream error or per-network timeout: 5s on paginated requests, 10s on fetch-all). When every requested network succeeds, the `error` key is omitted from the response entirely (it is not present-and-null). See [Handling partial failures](/docs/reference/portfolio-apis#handling-partial-failures) for the recommended client pattern.\n", "properties": { "message": { "type": "string", "description": "Human-readable summary of the partial failure. On the token endpoints this is `\"Failed to fetch tokens on certain networks\"`; on the NFT endpoints it is `\"Failed to fetch NFTs on certain networks\"`.\n" }, "partialErrors": { "type": "array", "description": "One entry per failed network. A network may appear more than once if the request body contained multiple entries covering that network.\n", "items": { "type": "object", "properties": { "network": { "type": "string", "description": "Network slug that failed (e.g. `eth-mainnet`, `robinhood-mainnet`)." }, "message": { "type": "string", "description": "Human-readable failure reason. Treat as an opaque string, not an enumerable error code. It does not distinguish upstream errors from per-network timeouts.\n" } }, "required": [ "network", "message" ] } } }, "required": [ "message", "partialErrors" ] } }, "required": [ "data" ] }, "NFTCollectionsByOwnerResponse": { "type": "object", "properties": { "data": { "type": "object", "description": "List of nft collections.", "properties": { "contracts": { "type": "array", "items": { "type": "object", "description": "The object that represents an NFT collection", "properties": { "network": { "type": "string", "description": "Network identifier." }, "address": { "type": "string", "description": "Wallet address." }, "contract": { "type": "object", "description": "The contract object that has details of a contract", "properties": { "address": { "description": "Address of the held contract", "type": "string" }, "name": { "type": "string", "description": "String - NFT contract name." }, "symbol": { "type": "string", "description": "String - NFT contract symbol abbreviation." }, "totalSupply": { "type": "string", "description": "String - Total number of NFTs in a given NFT collection." }, "tokenType": { "type": "string", "enum": [ "ERC721", "ERC1155", "NO_SUPPORTED_NFT_STANDARD", "NOT_A_CONTRACT" ], "description": "String - For valid NFTs, 'ERC721' or 'ERC1155.' For invalid NFTs, a descriptive reason such as 'NO_SUPPORTED_NFT_STANDARD' if the input contract address doesn't support a known NFT standard, or 'NOT_A_CONTRACT' if there is no contract deployed at the input address." }, "contractDeployer": { "type": "string", "description": "String - Address that deployed the smart contract" }, "deployedBlockNumber": { "type": "number", "description": "Number - The Block Number when the deployment transaction is successfully mined" }, "openseaMetadata": { "type": "object", "description": "Note that the OpenSea metadata object is currently only available on ETH and Polygon Mainnet. Please reach out to us at support@alchemy.com if you would like to access this data on other networks.", "properties": { "floorPrice": { "type": "number", "description": "NFT floor price" }, "collectionName": { "type": "string", "description": "OpenSea collection name" }, "safelistRequestStatus": { "type": "string", "description": "Collection approval status within OpenSea. For more info, see the Opensea docs at docs.opensea.io/reference/collection-model" }, "imageUrl": { "type": "string", "description": "OpenSea CDN image URL" }, "description": { "type": "string", "description": "OpenSea collection description. Note: this value is truncated to 255 characters." }, "externalUrl": { "type": "string", "description": "Collection homepage" }, "twitterUsername": { "type": "string", "description": "The twitter username of the collection" }, "discordUrl": { "type": "string", "description": "The discord URL of the collection" }, "bannerImageUrl": { "type": "string", "description": "The banner image URL of the collection" }, "lastIngestedAt": { "type": "string", "description": "The timestamp when the collection was last ingested by us" } } }, "isSpam": { "type": "string", "description": "\"true\" if contract is spam, else \"false\". **Only available on paid tiers.**" }, "spamClassifications": { "description": "List of reasons why a contract was classified as spam. **Only available on paid tiers.**", "type": "array", "items": { "type": "string" } } } } } } }, "totalCount": { "type": "integer", "description": "Integer - Total number of NFTs (distinct `tokenIds`) owned by the given address." }, "pageKey": { "type": "string" } } }, "error": { "type": "object", "description": "Present on 200 responses only when one or more requested networks did not return data (upstream error or per-network timeout: 5s on paginated requests, 10s on fetch-all). When every requested network succeeds, the `error` key is omitted from the response entirely (it is not present-and-null). See [Handling partial failures](/docs/reference/portfolio-apis#handling-partial-failures) for the recommended client pattern.\n", "properties": { "message": { "type": "string", "description": "Human-readable summary of the partial failure. On the token endpoints this is `\"Failed to fetch tokens on certain networks\"`; on the NFT endpoints it is `\"Failed to fetch NFTs on certain networks\"`.\n" }, "partialErrors": { "type": "array", "description": "One entry per failed network. A network may appear more than once if the request body contained multiple entries covering that network.\n", "items": { "type": "object", "properties": { "network": { "type": "string", "description": "Network slug that failed (e.g. `eth-mainnet`, `robinhood-mainnet`)." }, "message": { "type": "string", "description": "Human-readable failure reason. Treat as an opaque string, not an enumerable error code. It does not distinguish upstream errors from per-network timeouts.\n" } }, "required": [ "network", "message" ] } } }, "required": [ "message", "partialErrors" ] } }, "required": [ "data" ] }, "NFTResponseItem": { "type": "object", "description": "The object that represents an NFT and has all data corresponding to that NFT", "properties": { "network": { "type": "string", "description": "Network identifier." }, "address": { "type": "string", "description": "Wallet address." }, "contract": { "type": "object", "description": "The contract object that has details of a contract", "properties": { "address": { "description": "Address of the held contract", "type": "string" }, "name": { "type": "string", "description": "String - NFT contract name." }, "symbol": { "type": "string", "description": "String - NFT contract symbol abbreviation." }, "totalSupply": { "type": "string", "description": "String - Total number of NFTs in a given NFT collection." }, "tokenType": { "type": "string", "enum": [ "ERC721", "ERC1155", "NO_SUPPORTED_NFT_STANDARD", "NOT_A_CONTRACT" ], "description": "String - For valid NFTs, 'ERC721' or 'ERC1155.' For invalid NFTs, a descriptive reason such as 'NO_SUPPORTED_NFT_STANDARD' if the input contract address doesn't support a known NFT standard, or 'NOT_A_CONTRACT' if there is no contract deployed at the input address." }, "contractDeployer": { "type": "string", "description": "String - Address that deployed the smart contract" }, "deployedBlockNumber": { "type": "number", "description": "Number - The Block Number when the deployment transaction is successfully mined" }, "openseaMetadata": { "type": "object", "description": "Note that the OpenSea metadata object is currently only available on ETH and Polygon Mainnet. Please reach out to us at support@alchemy.com if you would like to access this data on other networks.", "properties": { "floorPrice": { "type": "number", "description": "NFT floor price" }, "collectionName": { "type": "string", "description": "OpenSea collection name" }, "safelistRequestStatus": { "type": "string", "description": "Collection approval status within OpenSea. For more info, see the Opensea docs at docs.opensea.io/reference/collection-model" }, "imageUrl": { "type": "string", "description": "OpenSea CDN image URL" }, "description": { "type": "string", "description": "OpenSea collection description. Note: this value is truncated to 255 characters." }, "externalUrl": { "type": "string", "description": "Collection homepage" }, "twitterUsername": { "type": "string", "description": "The twitter username of the collection" }, "discordUrl": { "type": "string", "description": "The discord URL of the collection" }, "bannerImageUrl": { "type": "string", "description": "The banner image URL of the collection" }, "lastIngestedAt": { "type": "string", "description": "The timestamp when the collection was last ingested by us" } } }, "isSpam": { "type": "string", "description": "\"true\" if contract is spam, else \"false\". **Only available on paid tiers.**" }, "spamClassifications": { "description": "List of reasons why a contract was classified as spam. **Only available on paid tiers.**", "type": "array", "items": { "type": "string" } } } }, "tokenId": { "type": "string", "default": "44" }, "tokenType": { "type": "string" }, "name": { "type": "string", "description": "String - Name of the NFT asset." }, "description": { "type": "string", "description": "String - Brief human-readable description" }, "image": { "type": "object", "description": "Details of the image corresponding to this contract", "properties": { "cachedUrl": { "type": "string", "description": "The Url of the image stored in Alchemy cache" }, "thumbnailUrl": { "type": "string", "description": "The Url that has the thumbnail version of the NFT" }, "pngUrl": { "type": "string", "description": "The Url that has the NFT image in png" }, "contentType": { "type": "string", "description": "The Url of the image stored in Alchemy cache" }, "size": { "type": "integer", "description": "The size of the media asset in bytes." }, "originalUrl": { "type": "string", "description": "The original Url of the image coming straight from the smart contract" } } }, "raw": { "type": "object", "description": "Raw details of the NFT like its tokenUri and metadata info obtained directly from the smart contract", "properties": { "tokenUri": { "type": "string", "description": "String - Uri representing the location of the NFT's original metadata blob. This is a backup for you to parse when the metadata field is not automatically populated." }, "metadata": { "type": "object", "description": "Relevant metadata for NFT contract. This is useful for viewing image url, traits, etc. without having to follow the metadata url in tokenUri to parse manually.", "properties": { "image": { "type": "string", "description": "String - URL to the NFT asset image. Can be standard URLs pointing to images on conventional servers, IPFS, or Arweave. Most types of images (SVGs, PNGs, JPEGs, etc.) are supported by NFT marketplaces." }, "name": { "type": "string", "description": "String - Name of the NFT asset." }, "description": { "type": "string", "description": "String - Human-readable description of the NFT asset. (Markdown is supported/rendered on OpenSea and other NFT platforms)" }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "trait_type": { "type": "string" } } }, "description": "Object - Traits/attributes/characteristics for each NFT asset." } } }, "error": { "type": "string", "description": "String - A string describing a particular reason that we were unable to fetch complete metadata for the NFT." } } }, "collection": { "type": "object", "description": "The collection object that has details of a collection", "properties": { "name": { "type": "string", "description": "String - Collection name" }, "slug": { "type": "string", "description": "String - OpenSea collection slug" }, "externalUrl": { "type": "string", "description": "String - URL for the external site of the collection" }, "bannerImageUrl": { "type": "string", "description": "String - Banner image URL for the collection" } } }, "tokenUri": { "type": "string", "description": "String - Uri representing the location of the NFT's original metadata blob. This is a backup for you to parse when the metadata field is not automatically populated." }, "timeLastUpdated": { "type": "string", "description": "String - ISO timestamp of the last cache refresh for the information returned in the metadata field." }, "acquiredAt": { "type": "object", "description": "Only present if the request specified `orderBy=transferTime`.", "properties": { "blockTimestamp": { "type": "string", "description": "Block timestamp of the block where the NFT was most recently acquired." }, "blockNumber": { "type": "string", "description": "Block number of the block where the NFT was most recently acquired." } } } } }, "NFTCollectionResponseItem": { "type": "object", "description": "The object that represents an NFT collection", "properties": { "network": { "type": "string", "description": "Network identifier." }, "address": { "type": "string", "description": "Wallet address." }, "contract": { "type": "object", "description": "The contract object that has details of a contract", "properties": { "address": { "description": "Address of the held contract", "type": "string" }, "name": { "type": "string", "description": "String - NFT contract name." }, "symbol": { "type": "string", "description": "String - NFT contract symbol abbreviation." }, "totalSupply": { "type": "string", "description": "String - Total number of NFTs in a given NFT collection." }, "tokenType": { "type": "string", "enum": [ "ERC721", "ERC1155", "NO_SUPPORTED_NFT_STANDARD", "NOT_A_CONTRACT" ], "description": "String - For valid NFTs, 'ERC721' or 'ERC1155.' For invalid NFTs, a descriptive reason such as 'NO_SUPPORTED_NFT_STANDARD' if the input contract address doesn't support a known NFT standard, or 'NOT_A_CONTRACT' if there is no contract deployed at the input address." }, "contractDeployer": { "type": "string", "description": "String - Address that deployed the smart contract" }, "deployedBlockNumber": { "type": "number", "description": "Number - The Block Number when the deployment transaction is successfully mined" }, "openseaMetadata": { "type": "object", "description": "Note that the OpenSea metadata object is currently only available on ETH and Polygon Mainnet. Please reach out to us at support@alchemy.com if you would like to access this data on other networks.", "properties": { "floorPrice": { "type": "number", "description": "NFT floor price" }, "collectionName": { "type": "string", "description": "OpenSea collection name" }, "safelistRequestStatus": { "type": "string", "description": "Collection approval status within OpenSea. For more info, see the Opensea docs at docs.opensea.io/reference/collection-model" }, "imageUrl": { "type": "string", "description": "OpenSea CDN image URL" }, "description": { "type": "string", "description": "OpenSea collection description. Note: this value is truncated to 255 characters." }, "externalUrl": { "type": "string", "description": "Collection homepage" }, "twitterUsername": { "type": "string", "description": "The twitter username of the collection" }, "discordUrl": { "type": "string", "description": "The discord URL of the collection" }, "bannerImageUrl": { "type": "string", "description": "The banner image URL of the collection" }, "lastIngestedAt": { "type": "string", "description": "The timestamp when the collection was last ingested by us" } } }, "isSpam": { "type": "string", "description": "\"true\" if contract is spam, else \"false\". **Only available on paid tiers.**" }, "spamClassifications": { "description": "List of reasons why a contract was classified as spam. **Only available on paid tiers.**", "type": "array", "items": { "type": "string" } } } } } }, "TokenPricesResponse": { "type": "object", "properties": { "data": { "type": "array", "description": "List of token price data.", "items": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Token symbol." }, "prices": { "type": "array", "description": "List of price information.", "items": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency code (e.g., USD)." }, "value": { "type": "string", "description": "Price value as a string." }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "Time when the price was last updated." } }, "required": [ "currency", "value", "lastUpdatedAt" ] } }, "error": { "type": [ "string", "null" ], "description": "Error message if applicable." } }, "required": [ "symbol", "prices", "error" ] } } }, "required": [ "data" ] }, "TokenPriceResponseItem": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Token symbol." }, "prices": { "type": "array", "description": "List of price information.", "items": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency code (e.g., USD)." }, "value": { "type": "string", "description": "Price value as a string." }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "Time when the price was last updated." } }, "required": [ "currency", "value", "lastUpdatedAt" ] } }, "error": { "type": [ "string", "null" ], "description": "Error message if applicable." } }, "required": [ "symbol", "prices", "error" ] }, "BlockTimestampResponse": { "type": "object", "properties": { "data": { "type": "array", "description": "List of blocks", "items": { "type": "object", "properties": { "network": { "type": "string", "description": "Network identifier" }, "block": { "type": "object", "properties": { "number": { "type": "integer", "description": "Block number" }, "timestamp": { "type": "string", "description": "ISO timestamp of the block" } }, "required": [ "number", "timestamp" ] } }, "required": [ "network", "block" ] } } }, "required": [ "data" ] } } } }