{ "openapi": "3.1.0", "info": { "title": "OpenSea API", "description": "The API for OpenSea", "contact": { "name": "OpenSea", "url": "https://www.opensea.io", "email": "contact@opensea.io" }, "version": "2.0.0" }, "servers": [ { "url": "https://api.opensea.io", "description": "Production server" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Chain Endpoints", "description": "Chain endpoints to discover supported blockchains and their capabilities" }, { "name": "Account Endpoints", "description": "Account endpoints to retrieve OpenSea account profiles and resolve identifiers" }, { "name": "Collection Endpoints", "description": "Collection endpoints to retrieve collection details, traits, and trending data" }, { "name": "NFT Endpoints", "description": "NFT endpoints to retrieve individual NFTs, metadata, ownership, and rarity" }, { "name": "Contract Endpoints", "description": "Contract endpoints to retrieve contract metadata and payment token details" }, { "name": "Token Endpoints", "description": "Token endpoints for getting token details, balances, and trending data" }, { "name": "Search Endpoints", "description": "Search endpoints for discovering collections, tokens, NFTs, and accounts" }, { "name": "Listing Endpoints", "description": "Listing endpoints for creating, fulfilling, and querying listings" }, { "name": "Offer Endpoints", "description": "Offer endpoints for building, creating, fulfilling, and querying offers" }, { "name": "Order Endpoints", "description": "Order endpoints for looking up and canceling individual orders" }, { "name": "Swap Endpoints", "description": "Swap endpoints for getting token swap quotes with executable transaction data" }, { "name": "Drops Endpoints", "description": "Endpoints for discovering drops, checking mint eligibility, and building mint transactions" }, { "name": "Analytics Endpoints", "description": "Analytics endpoints to retrieve events, stats, and trading data" }, { "name": "Tool Endpoints [Beta]", "description": "[Beta] Tool endpoints for discovering and inspecting registered onchain tools. This API is under active development and may change without notice." }, { "name": "Transaction Endpoints", "description": "Transaction endpoints for checking transaction receipts and status" } ], "paths": { "/api/v2/transactions/receipt": { "post": { "tags": ["Transaction Endpoints"], "summary": "Get transaction receipt", "description": "Get the receipt/status for a submitted transaction. Works for all transaction types including listing fulfillments, cross-chain buys, sweeps, offer fulfillments, and token swaps. Poll this endpoint after submitting transactions to check completion status.", "operationId": "get_transaction_receipt", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionReceiptRequest" } } }, "required": true }, "responses": { "200": { "description": "Transaction receipt retrieved", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/TransactionReceiptResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/tools/usage": { "post": { "tags": ["Tool Endpoints [Beta]"], "summary": "[Beta] Report tool usage (metrics only)", "description": "[Beta] Report verified tool usage for metrics and analytics purposes only. Supports verification_type: eip3009_authorization (free tools, identity proof) or x402_settlement (paid tools, onchain USDC payment verification). This endpoint does NOT trigger any onchain transactions. This endpoint is under active development and may change without notice.", "operationId": "report_tool_usage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolUsageRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ToolUsageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/tokens/batch": { "post": { "tags": ["Token Endpoints"], "summary": "Get tokens by contract identifiers", "description": "Retrieve multiple tokens in a single request by providing a list of contract identifiers (chain and address). Not-found tokens are silently omitted from the response.", "operationId": "get_tokens_batch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchTokensRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/TokenBatchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/swap/execute": { "post": { "tags": ["Swap Endpoints"], "summary": "Execute a token swap", "description": "Get executable transactions for token-to-token swaps. Supports same-chain and cross-chain swaps with multiple from/to assets.", "operationId": "post_swap_execute", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapExecuteRequest" } } }, "required": true }, "responses": { "200": { "description": "Swap execution data retrieved successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SwapExecuteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/orders/{chain}/{protocol}/offers": { "post": { "tags": ["Offer Endpoints"], "summary": "Create an item offer", "description": "Create an offer to purchase a single NFT (ERC721 or ERC1155).", "operationId": "post_offer", "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "protocol", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeaportRequest" } } }, "required": true }, "responses": { "200": { "description": "Item offer created successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Offer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/orders/{chain}/{protocol}/listings": { "post": { "tags": ["Listing Endpoints"], "summary": "Create a listing", "description": "List a single NFT (ERC721 or ERC1155) for sale on the OpenSea marketplace.", "operationId": "post_listing", "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "protocol", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeaportRequest" } } }, "required": true }, "responses": { "200": { "description": "Listing created successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Listing" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/orders/chain/{chain}/protocol/{protocol_address}/{order_hash}/cancel": { "post": { "tags": ["Order Endpoints"], "summary": "Cancel an order", "description": "Offchain cancel a single order, offer or listing, by its order hash when protected by the SignedZone. Protocol and Chain are required to prevent hash collisions. Please note cancellation is only assured if a fulfillment signature was not vended prior to cancellation.", "operationId": "cancel_order", "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "protocol_address", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "order_hash", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Api-Key", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelRequest" } } } }, "responses": { "200": { "description": "Order cancelled successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CancelResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/offers": { "post": { "tags": ["Offer Endpoints"], "summary": "Create a criteria offer", "description": "Create a criteria offer to purchase any NFT in a collection or which matches the specified trait. For trait offers where the Build Offer endpoint returns identifierOrCriteria '0', use that value directly — trait matching is validated server-side at fulfillment time rather than via onchain merkle proof.", "operationId": "post_criteria_offer_v2", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferWithCriteriaRequest" } } }, "required": true }, "responses": { "200": { "description": "Criteria offer created successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Offer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/offers/fulfillment_data": { "post": { "tags": ["Offer Endpoints"], "summary": "Fulfill an offer", "description": "Retrieve all the information, including signatures, needed to fulfill an offer directly onchain. For trait offers with identifierOrCriteria '0', the server validates that the specified token matches the offer's trait criteria before generating fulfillment data.", "operationId": "generate_offer_fulfillment_data_v2", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FullfillmentDataRequest" } } }, "required": true }, "responses": { "200": { "description": "Offer fulfillment data retrieved successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/FulfillListingResponse" } } } }, "400": { "description": "The request is invalid\nThe order_hash does not exist\nThe chain is not an EVM Chain\nThe protocol_address is not a supported Seaport contract\nFor other error reasons, see the response data.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/FulfillListingResponse" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/offers/build": { "post": { "tags": ["Offer Endpoints"], "summary": "Build a criteria offer", "description": "Build a portion of a criteria offer including the consideration item, zone, and zone hash needed to post an offer. For trait offers on supported collections, the identifierOrCriteria in the returned consideration will be '0' (no merkle root computation needed). For other collections, a computed merkle root is returned. When identifierOrCriteria is '0', the encodedTokenIds field is informational only and not required for constructing the onchain order.", "operationId": "build_offer_v2", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildOfferRequest" } } }, "required": true }, "responses": { "200": { "description": "Criteria offer built successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/BuildOfferResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/nfts/batch": { "post": { "tags": ["NFT Endpoints"], "summary": "Get NFTs by identifiers", "description": "Retrieve multiple NFTs in a single request by providing a list of identifiers (chain, contract address, and token ID). Not-found NFTs are silently omitted from the response.", "operationId": "get_nfts_batch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchNftsRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/NftBatchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/listings/sweep": { "post": { "tags": ["Listing Endpoints"], "summary": "Sweep buy items from a collection", "description": "Buy up to N items from a collection using any payment token, including cross-chain. If a requested item becomes unavailable, the system can automatically substitute it with the next cheapest listing from the same collection (enabled by default). Returns an ordered list of transactions to execute.", "operationId": "sweep_collection", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SweepCollectionRequest" } } }, "required": true }, "responses": { "200": { "description": "Sweep fulfillment data retrieved successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SweepCollectionResponse" } } } }, "400": { "description": "The request is invalid. Possible reasons: collection not found, invalid chain, max_items exceeds limit, or no listings available.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SweepCollectionResponse" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/listings/fulfillment_data": { "post": { "tags": ["Listing Endpoints"], "summary": "Fulfill a listing", "description": "Retrieve all the information, including signatures, needed to fulfill a listing directly onchain.", "operationId": "generate_listing_fulfillment_data_v2", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FullfillListingRequest" } } }, "required": true }, "responses": { "200": { "description": "Listing fulfillment data retrieved successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/FulfillListingResponse" } } } }, "400": { "description": "The request is invalid\nThe order_hash does not exist\nThe chain is not an EVM Chain\nThe protocol_address is not a supported Seaport contract\nFor other error reasons, see the response data.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/FulfillListingResponse" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/listings/cross_chain_fulfillment_data": { "post": { "tags": ["Listing Endpoints"], "summary": "Fulfill a listing using a different token", "description": "Get fulfillment data to buy one or more listings using a token on a different chain or a different token on the same chain. Supports cross-chain purchases and same-chain token swaps via the Relay protocol. Returns an ordered list of transactions to execute.", "operationId": "generate_cross_chain_listing_fulfillment_data", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrossChainFulfillmentRequest" } } }, "required": true }, "responses": { "200": { "description": "Cross-chain fulfillment data retrieved successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CrossChainFulfillmentResponse" } } } }, "400": { "description": "The request is invalid. Possible reasons: listing not found, listing not valid, listing is not a listing order, or no fulfillment actions could be generated.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CrossChainFulfillmentResponse" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/listings/actions": { "post": { "tags": ["Listing Endpoints"], "summary": "Get listing creation actions", "description": "Returns the blockchain actions (approvals + Seaport order signing payload) needed to list one or more NFTs. This eliminates the need to construct Seaport orders manually.", "operationId": "create_listing_actions", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateListingActionsRequest" } } }, "required": true }, "responses": { "200": { "description": "Listing creation actions retrieved successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CreateListingActionsResponse" } } } }, "400": { "description": "The request is invalid. Possible reasons: items on different chains, invalid addresses, items not found, invalid currency, or prices/quantities not positive.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CreateListingActionsResponse" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/drops/{slug}/mint": { "post": { "tags": ["Drops Endpoints"], "summary": "Build mint transaction data for a drop", "description": "Returns ready-to-sign transaction data for minting tokens from a drop. The caller is responsible for signing and submitting the transaction. No wallet authentication is required — only an API key. The minter address in the request body determines who will receive the tokens. Stage selection is handled automatically by the backend — if multiple stages are active, the first eligible stage is used.", "operationId": "build_drop_mint_transaction", "parameters": [ { "name": "slug", "in": "path", "description": "The collection slug identifying the drop", "required": true, "schema": { "type": "string" }, "example": "boredapeyachtclub" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DropMintRequest" } } }, "required": true }, "responses": { "200": { "description": "Ready-to-sign transaction data including target contract, calldata, and value", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/DropMintResponse" } } } }, "400": { "description": "Invalid request: bad address format, invalid quantity, or missing required fields", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/V1ErrorWrapper" } } } }, "404": { "description": "Drop or collection not found for the given slug", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/V1ErrorWrapper" } } } }, "409": { "description": "Drop is not currently active for minting (not started, ended, or paused)", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/V1ErrorWrapper" } } } }, "422": { "description": "Minting precondition failed: wallet not in allowlist, mint limit exceeded, or supply exhausted", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/V1ErrorWrapper" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/drops/deploy": { "post": { "tags": ["Drops Endpoints"], "summary": "Build deploy contract transaction data", "description": "Returns ready-to-sign transaction data for deploying a new NFT drop contract. The caller is responsible for signing and submitting the transaction.", "operationId": "deploy_drop_contract", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DropDeployRequest" } } }, "required": true }, "responses": { "200": { "description": "Ready-to-sign transaction data for contract deployment", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/DropDeployResponse" } } } }, "400": { "description": "Invalid request: unsupported drop_type/token_type combination, bad address format, or missing required fields", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/V1ErrorWrapper" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/collections/batch": { "post": { "tags": ["Collection Endpoints"], "summary": "Get collections by slugs", "description": "Retrieve multiple collections in a single request by providing a list of slugs. Results are returned in the same order as the input slugs. Not-found collections are silently omitted.", "operationId": "get_collections_batch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCollectionsRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CollectionBatchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/chain/{chain}/contract/{address}/nfts/{identifier}/validate-metadata": { "post": { "tags": ["NFT Endpoints"], "summary": "Validate NFT metadata", "description": "Fetch and validate NFT metadata directly from the blockchain without using cached data. Returns both original and processed (SeaDN) URLs to show how the metadata would be ingested. This endpoint does not persist any data.", "operationId": "validate_nft_metadata", "parameters": [ { "name": "chain", "in": "path", "description": "The blockchain on which the NFT exists", "required": true, "schema": { "type": "string" }, "example": "ethereum" }, { "name": "address", "in": "path", "description": "The contract address", "required": true, "schema": { "type": "string" }, "example": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d" }, { "name": "identifier", "in": "path", "description": "The NFT token id", "required": true, "schema": { "type": "string" }, "example": 1 }, { "name": "ignoreCachedItemUrls", "in": "query", "description": "Whether to bypass cached SeaDN URLs", "required": false, "schema": { "type": "boolean" }, "example": true } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidateMetadataResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/chain/{chain}/contract/{address}/nfts/{identifier}/refresh": { "post": { "tags": ["NFT Endpoints"], "summary": "Refresh NFT metadata", "description": "Queue a metadata refresh for a specific NFT to update its information from the blockchain.", "operationId": "refresh_nft_metadata", "parameters": [ { "name": "address", "in": "path", "description": "Contract address", "required": true, "schema": { "type": "string" } }, { "name": "chain", "in": "path", "description": "Blockchain chain identifier", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "Token identifier", "required": true, "schema": { "type": "string" } }, { "name": "ignoreCachedItemUrls", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/auth/keys": { "post": { "tags": ["Auth Endpoints"], "summary": "Create an instant API key", "description": "Creates a free-tier API key instantly without authentication. The key can be used immediately for all API endpoints. Rate limited to 2 keys per hour per IP. Keys expire after 30 days.", "operationId": "create_instant_api_key", "responses": { "201": { "description": "API key created successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/InstantApiKeyResponse" } } } }, "429": { "description": "Key creation rate limit exceeded", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/V1ErrorWrapper" } } } }, "500": { "description": "Internal server error (e.g. database failure)", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/V1ErrorWrapper" } } } }, "503": { "description": "Feature is currently disabled or temporarily unavailable", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/V1ErrorWrapper" } } } } } } }, "/api/v2/assets/transfer": { "post": { "tags": ["NFT Endpoints"], "summary": "Transfer NFTs or tokens between wallets", "description": "Returns ordered blockchain actions to execute for transferring one or more NFTs or tokens from one wallet to another. Supports bulk transfers of multiple assets in a single request.", "operationId": "transfer_assets", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferRequest" } } }, "required": true }, "responses": { "200": { "description": "Transfer actions retrieved successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/TransferResponse" } } } }, "400": { "description": "The request is invalid. Possible reasons: empty assets array, invalid addresses, invalid chain, or cross-ecosystem transfer.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/TransferResponse" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/traits/{slug}": { "get": { "tags": ["Collection Endpoints"], "summary": "Get collection traits", "description": "Get all available traits for a collection with their value counts and data types.", "operationId": "get_collection_traits", "parameters": [ { "name": "slug", "in": "path", "description": "Unique identifier for the specific collection", "required": true, "schema": { "type": "string" }, "example": "doodles-official" } ], "responses": { "200": { "description": "Collection traits with categories and counts", "content": { "application/json": { "examples": { "TraitsResponse": { "description": "Example response showing both string and numeric trait types", "value": { "categories": { "face": "string", "background": "string", "level": "number" }, "counts": { "face": { "glasses": 4, "sunglasses": 2 }, "background": { "red": 6 }, "level": { "min": 1, "max": 99 } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/tools": { "get": { "tags": ["Tool Endpoints [Beta]"], "summary": "[Beta] List registered tools", "description": "[Beta] List verified registered tools with optional sorting and filtering. This endpoint is under active development and may change without notice.", "operationId": "list_tools", "parameters": [ { "name": "sort_by", "in": "query", "description": "Sort by: newest, oldest", "required": false, "schema": { "type": "string", "default": "newest" } }, { "name": "type", "in": "query", "description": "Filter by access type: open, nft_gated, token_gated, subscription, gated", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of items to return per page", "required": false, "schema": { "type": "integer", "format": "int32", "description": "Number of items to return per page", "example": 20, "maximum": 200, "minimum": 1 }, "example": 20 }, { "name": "cursor.value", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ToolListPaginatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/tools/{registry_chain}/{registry_addr}/{tool_id}": { "get": { "tags": ["Tool Endpoints [Beta]"], "summary": "[Beta] Get a registered tool", "description": "[Beta] Get a registered tool by its composite key: registry chain, registry address, and tool ID. Includes pricing recipients and NFT collection info for gated tools. This endpoint is under active development and may change without notice.", "operationId": "get_tool", "parameters": [ { "name": "registry_chain", "in": "path", "description": "Registry chain ID (e.g. 1, 8453)", "required": true, "schema": { "type": "string" } }, { "name": "registry_addr", "in": "path", "description": "Registry contract address", "required": true, "schema": { "type": "string" } }, { "name": "tool_id", "in": "path", "description": "Numeric tool ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/RegisteredToolResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/tools/search": { "get": { "tags": ["Tool Endpoints [Beta]"], "summary": "[Beta] Search registered tools", "description": "[Beta] Search for verified registered tools by name, tags, creator, or other criteria. This endpoint is under active development and may change without notice.", "operationId": "search_tools", "parameters": [ { "name": "query", "in": "query", "description": "Search query text", "required": false, "schema": { "type": "string" } }, { "name": "registry_chain", "in": "query", "description": "Filter by registry chain ID", "required": false, "schema": { "type": "string" } }, { "name": "tags", "in": "query", "description": "Filter by tags", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "access_type", "in": "query", "description": "Filter by access type: open, nft_gated, subscription", "required": false, "schema": { "type": "string" } }, { "name": "creator", "in": "query", "description": "Filter by creator address", "required": false, "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "description": "Sort by: relevance, newest, most_used", "required": false, "schema": { "type": "string", "default": "relevance" } }, { "name": "include_details", "in": "query", "description": "Include pricing recipients and access requirements per result. Defaults to true; set false for a lighter list response.", "required": false, "schema": { "type": "boolean", "default": true } }, { "name": "limit", "in": "query", "description": "Number of items to return per page", "required": false, "schema": { "type": "integer", "format": "int32", "description": "Number of items to return per page", "example": 20, "maximum": 200, "minimum": 1 }, "example": 20 }, { "name": "cursor.value", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ToolSearchPaginatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/tokens/trending": { "get": { "tags": ["Token Endpoints"], "summary": "Get trending tokens", "description": "Get trending tokens based on OpenSea's trending score algorithm. Returns tokens with high momentum including memecoins and newly popular assets.", "operationId": "get_trending_tokens", "parameters": [ { "name": "limit", "in": "query", "description": "Number of results to return (default: 20, max: 100)", "required": false, "schema": { "type": "integer", "format": "int32", "default": 20 }, "example": 20 }, { "name": "chains", "in": "query", "description": "Filter by blockchain(s)", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChainIdentifier" } }, "example": "ethereum" }, { "name": "cursor", "in": "query", "description": "Pagination cursor for next page", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/TokenPaginatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/tokens/top": { "get": { "tags": ["Token Endpoints"], "summary": "Get top tokens", "description": "Get top tokens ranked by 24-hour trading volume. Returns established tokens with high market activity.", "operationId": "get_top_tokens", "parameters": [ { "name": "limit", "in": "query", "description": "Number of results to return (default: 20, max: 100)", "required": false, "schema": { "type": "integer", "format": "int32", "default": 20 }, "example": 20 }, { "name": "chains", "in": "query", "description": "Filter by blockchain(s)", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChainIdentifier" } }, "example": "ethereum" }, { "name": "cursor", "in": "query", "description": "Pagination cursor for next page", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/TokenPaginatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/token-groups": { "get": { "tags": ["Token Endpoints"], "summary": "Get token groups", "description": "Get a paginated list of token groups sorted by market cap descending. Token groups represent equivalent currencies across different blockchains (e.g., ETH on Ethereum, Base, and Arbitrum are all in the \"eth\" token group).", "operationId": "get_token_groups", "parameters": [ { "name": "limit", "in": "query", "description": "Number of results to return (default: 50, max: 100)", "required": false, "schema": { "type": "integer", "format": "int32", "default": 50 }, "example": 50 }, { "name": "cursor", "in": "query", "description": "Pagination cursor for next page", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/TokenGroupPaginatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/token-groups/{slug}": { "get": { "tags": ["Token Endpoints"], "summary": "Get a token group by slug", "description": "Get detailed information about a specific token group by its slug identifier.", "operationId": "get_token_group", "parameters": [ { "name": "slug", "in": "path", "description": "The slug identifier of the token group", "required": true, "schema": { "type": "string" }, "example": "eth" } ], "responses": { "200": { "description": "Successful response", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/TokenGroupResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/swap/quote": { "get": { "tags": ["Swap Endpoints"], "summary": "Get swap quote", "description": "Get a quote for swapping tokens, including price details and executable transaction data.", "operationId": "get_swap_quote", "parameters": [ { "name": "from_chain", "in": "query", "description": "Chain of the token to swap from", "required": true, "schema": { "type": "string" }, "example": "ethereum" }, { "name": "from_address", "in": "query", "description": "Contract address of the token to swap from", "required": true, "schema": { "type": "string" }, "example": "0x0000000000000000000000000000000000000000" }, { "name": "to_chain", "in": "query", "description": "Chain of the token to swap to", "required": true, "schema": { "type": "string" }, "example": "ethereum" }, { "name": "to_address", "in": "query", "description": "Contract address of the token to swap to", "required": true, "schema": { "type": "string" }, "example": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }, { "name": "quantity", "in": "query", "description": "Amount to swap in the smallest unit of the token (e.g. wei for ETH)", "required": true, "schema": { "type": "string" }, "example": 1000000000000000000 }, { "name": "address", "in": "query", "description": "Wallet address executing the swap", "required": true, "schema": { "type": "string" }, "example": "0x1234567890abcdef1234567890abcdef12345678" }, { "name": "slippage", "in": "query", "description": "Slippage tolerance (0.0 to 0.5, default: 0.01)", "required": false, "schema": { "type": "number", "format": "double", "default": 0.01 }, "example": 0.01 }, { "name": "recipient", "in": "query", "description": "Recipient address (defaults to sender address)", "required": false, "schema": { "type": "string" }, "example": "0x1234567890abcdef1234567890abcdef12345678" } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SwapQuoteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/search": { "get": { "tags": ["Search Endpoints"], "summary": "Search across OpenSea", "description": "Search across collections, tokens, NFTs, and accounts. Results are ranked by relevance.", "operationId": "search", "parameters": [ { "name": "query", "in": "query", "description": "Search query text", "required": true, "schema": { "type": "string" }, "example": "bored ape" }, { "name": "chains", "in": "query", "description": "Filter by blockchain(s)", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChainIdentifier" } } }, { "name": "asset_types", "in": "query", "description": "Filter by asset type(s). Valid values: collection, nft, token, account. Defaults to [collection, token] if not specified.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "limit", "in": "query", "description": "Number of results to return (default: 20, max: 50)", "required": false, "schema": { "type": "integer", "format": "int32", "default": 20 } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/orders/chain/{chain}/protocol/{protocol_address}/{order_hash}": { "get": { "tags": ["Order Endpoints"], "summary": "Get an order", "description": "Get a single order by its order hash.", "operationId": "get_order", "parameters": [ { "name": "chain", "in": "path", "description": "Blockchain chain identifier", "required": true, "schema": { "type": "string" } }, { "name": "protocol_address", "in": "path", "description": "Protocol contract address", "required": true, "schema": { "type": "string" } }, { "name": "order_hash", "in": "path", "description": "Order hash", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order details retrieved successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/GetOrderResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/offers/collection/{slug}": { "get": { "tags": ["Offer Endpoints"], "summary": "Get offers by collection", "description": "Get collection offers on a collection.", "operationId": "get_offers_collection", "parameters": [ { "name": "slug", "in": "path", "description": "Unique string to identify a collection on OpenSea", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of items to return per page", "required": false, "schema": { "type": "integer", "format": "int32", "description": "Number of items to return per page", "example": 20, "maximum": 200, "minimum": 1 }, "example": 20 }, { "name": "next.value", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/OffersResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/offers/collection/{slug}/traits": { "get": { "tags": ["Offer Endpoints"], "summary": "Get trait offers for a collection", "description": "Get trait offers for a collection. Use the `mode` parameter to select the bid category.\n\n**Single string trait:** `?mode=STRING&type=Background&value=Red`\n**Multiple string traits:** `?mode=MULTI&traits=[{\"traitType\":\"Background\",\"value\":\"Red\"},{\"traitType\":\"Eyes\",\"value\":\"Blue\"}]`\n**Numeric trait range:** `?mode=NUMERIC&type=Level&min_value=1&max_value=10`\n\nOmit filter params to discover all bids of that mode (e.g. `?mode=NUMERIC` returns all numeric bids).\n\nIf `mode` is omitted, the mode is inferred from the params for backward compatibility.", "operationId": "get_offers_collection_trait", "parameters": [ { "name": "slug", "in": "path", "description": "Unique string to identify a collection on OpenSea", "required": true, "schema": { "type": "string" } }, { "name": "mode", "in": "query", "description": "Bid category: STRING (single string trait), MULTI (multiple string traits), or NUMERIC (numeric trait range). If omitted, inferred from params.", "required": false, "schema": { "type": "string", "enum": ["STRING", "NUMERIC", "MULTI"] } }, { "name": "type", "in": "query", "description": "Trait type name", "required": false, "schema": { "type": "string" } }, { "name": "value", "in": "query", "description": "Trait value as string", "required": false, "schema": { "type": "string" } }, { "name": "float_value", "in": "query", "description": "Trait value as float", "required": false, "schema": { "type": "number", "format": "double" } }, { "name": "int_value", "in": "query", "description": "Trait value as integer", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "min_value", "in": "query", "description": "Minimum value for numeric trait range queries", "required": false, "schema": { "type": "number", "format": "float" } }, { "name": "max_value", "in": "query", "description": "Maximum value for numeric trait range queries", "required": false, "schema": { "type": "number", "format": "float" } }, { "name": "traits", "in": "query", "description": "JSON array of trait filters for multi-trait queries. Each element has 'traitType' and 'value' fields. Example: [{\"traitType\":\"Background\",\"value\":\"Red\"}]", "required": false, "schema": { "type": "string" }, "example": [ { "traitType": "Background", "value": "Red" } ] }, { "name": "limit", "in": "query", "description": "Number of items to return per page", "required": false, "schema": { "type": "integer", "format": "int32", "description": "Number of items to return per page", "example": 20, "maximum": 200, "minimum": 1 }, "example": 20 }, { "name": "next.value", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/OffersResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/offers/collection/{slug}/nfts/{identifier}": { "get": { "tags": ["Offer Endpoints"], "summary": "Get offers by NFT", "description": "Get offers for an NFT.", "operationId": "get_offers_nft", "parameters": [ { "name": "slug", "in": "path", "description": "Unique string to identify a collection on OpenSea", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "NFT token id", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of items to return per page", "required": false, "schema": { "type": "integer", "format": "int32", "description": "Number of items to return per page", "example": 20, "maximum": 200, "minimum": 1 }, "example": 20 }, { "name": "next.value", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/OffersResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/offers/collection/{slug}/nfts/{identifier}/best": { "get": { "tags": ["Offer Endpoints"], "summary": "Get best offer by NFT", "description": "Get the best offer for an NFT.", "operationId": "get_best_offer_nft", "parameters": [ { "name": "slug", "in": "path", "description": "Unique string to identify a collection on OpenSea", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "NFT token id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Offer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/offers/collection/{slug}/all": { "get": { "tags": ["Offer Endpoints"], "summary": "Get all offers by collection", "description": "Get all offers for a collection.", "operationId": "list_offers_collection_all", "parameters": [ { "name": "slug", "in": "path", "description": "Unique string to identify a collection on OpenSea", "required": true, "schema": { "type": "string" } }, { "name": "maker", "in": "query", "description": "Filter by the wallet address of the order maker", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of items to return per page", "required": false, "schema": { "type": "integer", "format": "int32", "description": "Number of items to return per page", "example": 20, "maximum": 200, "minimum": 1 }, "example": 20 }, { "name": "next.value", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/OffersResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/metadata/{chain}/{contractAddress}/{tokenId}": { "get": { "tags": ["NFT Endpoints"], "summary": "Get NFT metadata", "description": "Get detailed metadata for an NFT including name, description, image, traits, and external links.", "operationId": "get_nft_metadata", "parameters": [ { "name": "chain", "in": "path", "description": "The blockchain on which to filter the results", "required": true, "schema": { "type": "string" }, "example": "ethereum" }, { "name": "contractAddress", "in": "path", "description": "The unique public blockchain identifier for the contract", "required": true, "schema": { "type": "string" }, "example": "0x8ba1f109551bD432803012645Hac136c94C19D6e" }, { "name": "tokenId", "in": "path", "description": "The NFT token id", "required": true, "schema": { "type": "string" }, "example": 1 } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/AssetMetadataResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/listings/collection/{slug}/nfts/{identifier}/best": { "get": { "tags": ["Listing Endpoints"], "summary": "Get best listing by NFT", "description": "Get the best listing for an NFT.", "operationId": "get_best_listing_nft", "parameters": [ { "name": "slug", "in": "path", "description": "Unique string to identify a collection on OpenSea", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "NFT token id", "required": true, "schema": { "type": "string" } }, { "name": "include_private_listings", "in": "query", "description": "Whether to include private listings; defaults to false", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Listing" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/listings/collection/{slug}/best": { "get": { "tags": ["Listing Endpoints"], "summary": "Get best listings by collection", "description": "Get the best listings for a collection sorted by price ascending. Optionally filter by item traits using the 'traits' query parameter with a JSON array of trait filters. Multiple traits are AND-combined (items must match all). Note: results are not deduplicated by token ID — if a token has multiple listings, each listing is returned individually. Filter client-side if you need unique tokens. Example: ?traits=[{\"traitType\":\"Background\",\"value\":\"Red\"}]", "operationId": "get_best_listings_collection", "parameters": [ { "name": "slug", "in": "path", "description": "Unique string to identify a collection on OpenSea", "required": true, "schema": { "type": "string" } }, { "name": "include_private_listings", "in": "query", "description": "Whether to include private listings; defaults to false", "required": false, "schema": { "type": "boolean" } }, { "name": "traits", "in": "query", "description": "JSON array of trait filters to narrow listings by item traits. Each object has 'traitType' and 'value' fields. Multiple traits are AND-combined (items must match all). Example: [{\"traitType\":\"Background\",\"value\":\"Red\"}]", "required": false, "schema": { "type": "string" }, "example": [ { "traitType": "Background", "value": "Red" } ] }, { "name": "limit", "in": "query", "description": "Number of items to return per page", "required": false, "schema": { "type": "integer", "format": "int32", "description": "Number of items to return per page", "example": 20, "maximum": 200, "minimum": 1 }, "example": 20 }, { "name": "next.value", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ListingsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/listings/collection/{slug}/all": { "get": { "tags": ["Listing Endpoints"], "summary": "Get all listings by collection", "description": "Get all listings for a collection.", "operationId": "list_listings_collection_all", "parameters": [ { "name": "slug", "in": "path", "description": "Unique string to identify a collection on OpenSea", "required": true, "schema": { "type": "string" } }, { "name": "include_private_listings", "in": "query", "description": "Whether to include private listings; defaults to false", "required": false, "schema": { "type": "boolean" } }, { "name": "maker", "in": "query", "description": "Filter by the wallet address of the order maker", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of items to return per page", "required": false, "schema": { "type": "integer", "format": "int32", "description": "Number of items to return per page", "example": 20, "maximum": 200, "minimum": 1 }, "example": 20 }, { "name": "next.value", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ListingsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/events": { "get": { "tags": ["Analytics Endpoints"], "summary": "Get events", "description": "Get a list of events, with optional filtering by event type and time range.", "operationId": "list_events", "parameters": [ { "name": "after", "in": "query", "description": "Only show events after this timestamp (Unix timestamp in seconds)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "before", "in": "query", "description": "Only show events before this timestamp (Unix timestamp in seconds)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "event_type", "in": "query", "description": "Filter by event types. To get order invalidation and revalidation events, please use the Stream API. The order status can also be checked on the Get Order endpoint.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "sale", "transfer", "mint", "listing", "offer", "trait_offer", "collection_offer" ] } } }, { "name": "limit", "in": "query", "description": "Number of items to return per page", "required": false, "schema": { "type": "integer", "format": "int32", "description": "Number of items to return per page", "example": 20, "maximum": 200, "minimum": 1 }, "example": 20 }, { "name": "next.value", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/AssetEventsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/events/collection/{slug}": { "get": { "tags": ["Analytics Endpoints"], "summary": "Get events (by collection)", "description": "Get a list of events for a collection. Optionally filter by traits to only return events for items matching the specified trait criteria.", "operationId": "list_events_by_collection", "parameters": [ { "name": "slug", "in": "path", "description": "Unique identifier for the collection", "required": true, "schema": { "type": "string" }, "example": "doodles-official" }, { "name": "after", "in": "query", "description": "Only show events after this timestamp (Unix timestamp in seconds)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "before", "in": "query", "description": "Only show events before this timestamp (Unix timestamp in seconds)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "event_type", "in": "query", "description": "Filter by event types. To get order invalidation and revalidation events, please use the Stream API. The order status can also be checked on the Get Order endpoint.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "sale", "transfer", "mint", "listing", "offer", "trait_offer", "collection_offer" ] } } }, { "name": "traits", "in": "query", "description": "JSON array of trait filters. Each object has 'traitType' and 'value' fields. Multiple traits are AND-combined (items must match all). Example: [{\"traitType\":\"Background\",\"value\":\"Red\"}]", "required": false, "schema": { "type": "string" }, "example": [ { "traitType": "Background", "value": "Red" } ] }, { "name": "limit", "in": "query", "description": "Number of items to return per page", "required": false, "schema": { "type": "integer", "format": "int32", "description": "Number of items to return per page", "example": 20, "maximum": 200, "minimum": 1 }, "example": 20 }, { "name": "next.value", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/AssetEventsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/events/chain/{chain}/contract/{address}/nfts/{identifier}": { "get": { "tags": ["Analytics Endpoints"], "summary": "Get events (by NFT)", "description": "Get a list of events for a specific NFT.", "operationId": "list_events_by_nft", "parameters": [ { "name": "chain", "in": "path", "description": "The blockchain on which to filter the results", "required": true, "schema": { "type": "string" }, "example": "ethereum" }, { "name": "address", "in": "path", "description": "The unique public blockchain identifier for the contract", "required": true, "schema": { "type": "string" }, "example": "0x8ba1f109551bD432803012645Hac136c94C19D6e" }, { "name": "identifier", "in": "path", "description": "The NFT token id", "required": true, "schema": { "type": "string" }, "example": 1 }, { "name": "after", "in": "query", "description": "Only show events after this timestamp (Unix timestamp in seconds)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "before", "in": "query", "description": "Only show events before this timestamp (Unix timestamp in seconds)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "event_type", "in": "query", "description": "Filter by event types. To get order invalidation and revalidation events, please use the Stream API. The order status can also be checked on the Get Order endpoint.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "sale", "transfer", "mint", "listing", "offer", "trait_offer", "collection_offer" ] } } }, { "name": "limit", "in": "query", "description": "Number of items to return per page", "required": false, "schema": { "type": "integer", "format": "int32", "description": "Number of items to return per page", "example": 20, "maximum": 200, "minimum": 1 }, "example": 20 }, { "name": "next.value", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/AssetEventsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/events/accounts/{address}": { "get": { "tags": ["Analytics Endpoints"], "summary": "Get events (by account)", "description": "Get a list of events for an account.", "operationId": "list_events_by_account", "parameters": [ { "name": "address", "in": "path", "description": "The blockchain address of the account", "required": true, "schema": { "type": "string" }, "example": "0x8ba1f109551bD432803012645Hac136c94C19D6e" }, { "name": "after", "in": "query", "description": "Only show events after this timestamp (Unix timestamp in seconds)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "before", "in": "query", "description": "Only show events before this timestamp (Unix timestamp in seconds)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "event_type", "in": "query", "description": "Filter by event types. To get order invalidation and revalidation events, please use the Stream API. The order status can also be checked on the Get Order endpoint.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "sale", "transfer", "mint", "listing", "offer", "trait_offer", "collection_offer" ] } } }, { "name": "chain", "in": "query", "description": "Filter by blockchain", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of items to return per page", "required": false, "schema": { "type": "integer", "format": "int32", "description": "Number of items to return per page", "example": 20, "maximum": 200, "minimum": 1 }, "example": 20 }, { "name": "next.value", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/AssetEventsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/drops": { "get": { "tags": ["Drops Endpoints"], "summary": "Get drops", "description": "Get a list of NFT drops (mints) by type: featured, upcoming, or recently_minted. Results may be fewer than the requested limit due to post-fetch filtering.", "operationId": "get_drops", "parameters": [ { "name": "type", "in": "query", "description": "Drop calendar type: featured, upcoming, or recently_minted", "required": false, "schema": { "type": "string", "default": "featured" }, "example": "featured" }, { "name": "limit", "in": "query", "description": "Number of results to return (1-100, default: 20)", "required": false, "schema": { "type": "integer", "format": "int32", "default": 20 }, "example": 20 }, { "name": "chains", "in": "query", "description": "Comma-separated list of chains to filter by (e.g. ethereum, base). Omit to return drops on all chains.", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChainIdentifier" } }, "example": "ethereum,base" }, { "name": "cursor", "in": "query", "description": "Pagination cursor for next page", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of drops", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/DropPaginatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/drops/{slug}": { "get": { "tags": ["Drops Endpoints"], "summary": "Get drop by collection slug", "description": "Get detailed drop information for a collection, including stages and supply.", "operationId": "get_drop_by_slug", "parameters": [ { "name": "slug", "in": "path", "description": "Collection slug", "required": true, "schema": { "type": "string" }, "example": "cool-cats" } ], "responses": { "200": { "description": "Detailed drop information", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/DropDetailedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/drops/deploy/{chain}/{tx_hash}/receipt": { "get": { "tags": ["Drops Endpoints"], "summary": "Get deploy contract receipt", "description": "Check the status of a contract deployment transaction. Returns the deployment status and, on success, the deployed contract address and linked collection slug.", "operationId": "get_deploy_contract_receipt", "parameters": [ { "name": "chain", "in": "path", "description": "Chain slug (e.g. ethereum, base)", "required": true, "schema": { "type": "string" }, "example": "ethereum" }, { "name": "tx_hash", "in": "path", "description": "Transaction hash of the deployment transaction", "required": true, "schema": { "type": "string" }, "example": "0xabc123..." } ], "responses": { "200": { "description": "Deployment receipt status", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/DropDeployReceiptResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/collections": { "get": { "tags": ["Collection Endpoints"], "summary": "Get multiple collections", "description": "Get a list of collections with filters and sorting options.", "operationId": "list_collections", "parameters": [ { "name": "limit", "in": "query", "description": "Number of items to return per page", "required": false, "schema": { "type": "integer", "format": "int32", "description": "Number of items to return per page", "example": 20, "maximum": 200, "minimum": 1 }, "example": 20 }, { "name": "next.value", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "chain", "in": "query", "description": "Blockchain to filter by", "required": false, "schema": { "type": "string" } }, { "name": "creator_username", "in": "query", "description": "Username of collection creator to filter by", "required": false, "schema": { "type": "string" } }, { "name": "include_hidden", "in": "query", "description": "Include hidden collections in results", "required": false, "schema": { "type": "boolean" } }, { "name": "order_by", "in": "query", "description": "Field to order results by", "required": false, "schema": { "type": "string" }, "example": "created_date" } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CollectionPaginatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/collections/{slug}": { "get": { "tags": ["Collection Endpoints"], "summary": "Get a single collection", "description": "Get a single collection including details such as fees, traits, and links.", "operationId": "get_collection", "parameters": [ { "name": "slug", "in": "path", "description": "Unique identifier for the specific collection", "required": true, "schema": { "type": "string" }, "example": "doodles-official" } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CollectionDetailedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/collections/{slug}/stats": { "get": { "tags": ["Collection Endpoints", "Analytics Endpoints"], "summary": "Get collection stats", "description": "Get comprehensive statistics for a collection including volume, floor price, and trading metrics.", "operationId": "get_collection_stats", "parameters": [ { "name": "slug", "in": "path", "description": "Unique identifier for the specific collection", "required": true, "schema": { "type": "string" }, "example": "doodles-official" } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CollectionStatsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/collections/{slug}/offer_aggregates": { "get": { "tags": ["Collection Endpoints"], "summary": "Get collection offer aggregates", "description": "Get aggregated offer buckets grouped by price level for a collection.", "operationId": "get_collection_offer_aggregates", "parameters": [ { "name": "slug", "in": "path", "description": "Collection slug", "required": true, "schema": { "type": "string" }, "example": "boredapeyachtclub" }, { "name": "limit", "in": "query", "description": "Number of results to return (default: 20, max: 100)", "required": false, "schema": { "type": "integer", "format": "int32", "default": 20 }, "example": 20 }, { "name": "cursor", "in": "query", "description": "Pagination cursor for next page", "required": false, "schema": { "type": "string" } }, { "name": "sort_direction", "in": "query", "description": "Sort direction (asc or desc)", "required": false, "schema": { "type": "string", "default": "desc" }, "example": "desc" } ], "responses": { "200": { "description": "Collection offer aggregates", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CollectionOfferAggregatesPaginatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/collections/{slug}/holders": { "get": { "tags": ["Collection Endpoints"], "summary": "Get collection holders", "description": "Get a paginated list of holders for a collection.", "operationId": "get_collection_holders", "parameters": [ { "name": "slug", "in": "path", "description": "Collection slug", "required": true, "schema": { "type": "string" }, "example": "boredapeyachtclub" }, { "name": "limit", "in": "query", "description": "Number of results to return (default: 20, max: 100)", "required": false, "schema": { "type": "integer", "format": "int32", "default": 20 }, "example": 20 }, { "name": "cursor", "in": "query", "description": "Pagination cursor for next page", "required": false, "schema": { "type": "string" } }, { "name": "sort_direction", "in": "query", "description": "Sort direction (asc or desc)", "required": false, "schema": { "type": "string", "default": "desc" }, "example": "desc" }, { "name": "owned_by", "in": "query", "description": "Filter by owner address", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Collection holders", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CollectionHoldersPaginatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/collections/{slug}/floor_prices": { "get": { "tags": ["Collection Endpoints"], "summary": "Get collection floor price history", "description": "Get time-series floor price data for a collection.", "operationId": "get_collection_floor_prices", "parameters": [ { "name": "slug", "in": "path", "description": "Collection slug", "required": true, "schema": { "type": "string" }, "example": "boredapeyachtclub" }, { "name": "timeframe", "in": "query", "description": "Time window for floor price history. Options: one_minute, five_minutes, fifteen_minutes, one_hour, one_day, seven_days, thirty_days, one_year, all_time", "required": false, "schema": { "type": "string", "default": "one_day" }, "example": "one_day" }, { "name": "resolution", "in": "query", "description": "Number of data points to return", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Floor price history", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/FloorPriceHistoryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/collections/trending": { "get": { "tags": ["Collection Endpoints"], "summary": "Get trending collections", "description": "Get a list of trending NFT collections sorted by sales activity over a specified timeframe. Trending is determined by sales volume and activity metrics. Available timeframes range from 1 minute to all time. For the one_day timeframe without a chain filter, collections are sorted by a composite trending score; all other timeframes sort by raw sales count. Results are filtered to verified, non-spam, non-NSFW collections with minimum volume thresholds.", "operationId": "get_trending_collections", "parameters": [ { "name": "timeframe", "in": "query", "description": "Time window for trending calculation. Options: one_minute, five_minutes, fifteen_minutes, one_hour, one_day, seven_days, thirty_days, one_year, all_time.", "required": false, "schema": { "type": "string", "default": "one_day" }, "example": "one_day" }, { "name": "chains", "in": "query", "description": "Blockchain(s) to filter by. Comma-separated list of chain identifiers. Unsupported chains are silently ignored; a 400 is returned only if all specified chains are unsupported.", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChainIdentifier" } }, "example": "ethereum,base" }, { "name": "category", "in": "query", "description": "Category to filter by (e.g. art, gaming, memberships, music, pfps, photography, domain-names, virtual-worlds, sports-collectibles, physical-collectibles).", "required": false, "schema": { "type": "string" }, "example": "pfps" }, { "name": "limit", "in": "query", "description": "Maximum number of collections to return (1-100).", "required": false, "schema": { "type": "integer", "format": "int32", "default": 20 }, "example": 20 }, { "name": "cursor", "in": "query", "description": "Cursor for pagination. Use the 'next' value from a previous response.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trending collections", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CollectionPaginatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/collections/top": { "get": { "tags": ["Collection Endpoints"], "summary": "Get top collections", "description": "Get top NFT collections ranked by various stats (sorted descending). Unlike /trending, results are not filtered by verification status; spam-tagged collections are excluded via trust-safety enforcement states. Available sort options: one_day_volume, seven_days_volume, thirty_days_volume, floor_price, one_day_sales, seven_days_sales, thirty_days_sales, total_volume, total_sales.", "operationId": "get_top_collections", "parameters": [ { "name": "sort_by", "in": "query", "description": "The stat to sort collections by (always sorted descending). Options: one_day_volume, seven_days_volume, thirty_days_volume, floor_price, one_day_sales, seven_days_sales, thirty_days_sales, total_volume, total_sales", "required": false, "schema": { "type": "string", "default": "one_day_volume" }, "example": "one_day_volume" }, { "name": "chains", "in": "query", "description": "Blockchain(s) to filter by. Comma-separated list of chain identifiers. Unsupported chains are silently ignored; a 400 is returned only if all specified chains are unsupported.", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChainIdentifier" } }, "example": "ethereum,base" }, { "name": "category", "in": "query", "description": "Category to filter by (e.g. art, gaming, memberships, music, pfps, photography, domain-names, virtual-worlds, sports-collectibles, physical-collectibles).", "required": false, "schema": { "type": "string" }, "example": "pfps" }, { "name": "limit", "in": "query", "description": "Maximum number of collections to return (1-100).", "required": false, "schema": { "type": "integer", "format": "int32", "default": 50 }, "example": 50 }, { "name": "cursor", "in": "query", "description": "Cursor for pagination", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Top collections list", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CollectionPaginatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/collection/{slug}/nfts": { "get": { "tags": ["NFT Endpoints"], "summary": "Get NFTs by collection", "description": "Get NFTs in a specific collection. Optionally filter by traits using the 'traits' query parameter with a JSON array of trait filters. Multiple traits are AND-combined (items must match all specified traits). Example: ?traits=[{\"traitType\":\"Background\",\"value\":\"Red\"},{\"traitType\":\"Eyes\",\"value\":\"Blue\"}]", "operationId": "get_nfts_by_collection", "parameters": [ { "name": "slug", "in": "path", "description": "Collection slug", "required": true, "schema": { "type": "string" } }, { "name": "traits", "in": "query", "description": "JSON array of trait filters. Each object has 'traitType' and 'value' fields. Multiple traits are AND-combined (items must match all). Example: [{\"traitType\":\"Background\",\"value\":\"Red\"}]", "required": false, "schema": { "type": "string" }, "example": [ { "traitType": "Background", "value": "Red" } ] }, { "name": "has_agent_binding", "in": "query", "description": "Filter by NFTs that have an ERC-8217 agent binding", "required": false, "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "description": "Number of items to return per page", "required": false, "schema": { "type": "integer", "format": "int32", "description": "Number of items to return per page", "example": 20, "maximum": 200, "minimum": 1 }, "example": 20 }, { "name": "next.value", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/NftListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/chains": { "get": { "tags": ["Chain Endpoints"], "summary": "Get supported chains", "description": "Get all supported blockchain chains with metadata including name, native currency symbol, swap support, and block explorer information.", "operationId": "get_chains", "responses": { "200": { "description": "List of supported chains", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ChainListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/chain/{chain}/token/{address}": { "get": { "tags": ["Token Endpoints"], "summary": "Get token details", "description": "Get detailed information about a specific token by chain and contract address.", "operationId": "get_token", "parameters": [ { "name": "chain", "in": "path", "description": "The blockchain on which the token exists", "required": true, "schema": { "type": "string" }, "example": "ethereum" }, { "name": "address", "in": "path", "description": "The contract address of the token", "required": true, "schema": { "type": "string" }, "example": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/TokenDetailedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/chain/{chain}/token/{address}/price_history": { "get": { "tags": ["Token Endpoints"], "summary": "Get token price history", "description": "Get historical price data for a specific token.", "operationId": "get_token_price_history", "parameters": [ { "name": "chain", "in": "path", "description": "The blockchain on which the token exists", "required": true, "schema": { "type": "string" }, "example": "ethereum" }, { "name": "address", "in": "path", "description": "The contract address of the token", "required": true, "schema": { "type": "string" }, "example": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }, { "name": "start_time", "in": "query", "description": "Start time for the price history window (ISO 8601)", "required": true, "schema": { "type": "string", "format": "date-time" }, "example": "2024-01-01T00:00:00Z" }, { "name": "end_time", "in": "query", "description": "End time for the price history window (ISO 8601, defaults to now)", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2024-01-02T00:00:00Z" }, { "name": "bucket_size", "in": "query", "description": "Candle bucket size for aggregation (1s, 1m, 5m, 15m, 1h, 4h, 1d)", "required": false, "schema": { "type": "string" }, "example": "1h" } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PriceHistoryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/chain/{chain}/token/{address}/ohlcv": { "get": { "tags": ["Token Endpoints"], "summary": "Get token OHLCV candles", "description": "Get OHLCV (Open, High, Low, Close, Volume) candlestick data for a specific token.", "operationId": "get_token_ohlcv", "parameters": [ { "name": "chain", "in": "path", "description": "The blockchain on which the token exists", "required": true, "schema": { "type": "string" }, "example": "ethereum" }, { "name": "address", "in": "path", "description": "The contract address of the token", "required": true, "schema": { "type": "string" }, "example": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }, { "name": "start_time", "in": "query", "description": "Start time for the OHLCV window (ISO 8601)", "required": true, "schema": { "type": "string", "format": "date-time" }, "example": "2024-01-01T00:00:00Z" }, { "name": "end_time", "in": "query", "description": "End time for the OHLCV window (ISO 8601, defaults to now)", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2024-01-02T00:00:00Z" }, { "name": "bucket_size", "in": "query", "description": "Candle bucket size (1s, 1m, 5m, 15m, 1h, 4h, 1d)", "required": true, "schema": { "type": "string" }, "example": "1h" }, { "name": "fill_time_window", "in": "query", "description": "Whether to fill empty time windows with zero-volume candles", "required": false, "schema": { "type": "boolean", "default": false }, "example": false } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/OhlcvResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/chain/{chain}/token/{address}/liquidity-pools": { "get": { "tags": ["Token Endpoints"], "summary": "Get token liquidity pools", "description": "Get liquidity pools for a specific token.", "operationId": "get_token_liquidity_pools", "parameters": [ { "name": "chain", "in": "path", "description": "The blockchain on which the token exists", "required": true, "schema": { "type": "string" }, "example": "ethereum" }, { "name": "address", "in": "path", "description": "The contract address of the token", "required": true, "schema": { "type": "string" }, "example": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }, { "name": "limit", "in": "query", "description": "Number of results to return (default: 20, max: 50)", "required": false, "schema": { "type": "integer", "format": "int32", "default": 20 }, "example": 20 } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/TokenLiquidityPoolsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/chain/{chain}/token/{address}/holders": { "get": { "tags": ["Token Endpoints"], "summary": "Get token holders", "description": "Get paginated list of holders for a specific token, including quantity held and USD value.", "operationId": "get_token_holders", "parameters": [ { "name": "chain", "in": "path", "description": "The blockchain on which the token exists", "required": true, "schema": { "type": "string" }, "example": "ethereum" }, { "name": "address", "in": "path", "description": "The contract address of the token", "required": true, "schema": { "type": "string" }, "example": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }, { "name": "limit", "in": "query", "description": "Number of results to return (default: 20, max: 100)", "required": false, "schema": { "type": "integer", "format": "int32", "default": 20 }, "example": 20 }, { "name": "cursor", "in": "query", "description": "Pagination cursor for next page", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/TokenHoldersResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/chain/{chain}/token/{address}/activity": { "get": { "tags": ["Token Endpoints"], "summary": "Get token swap activity", "description": "Get paginated swap activity for a specific token on a given chain.", "operationId": "get_token_activity", "parameters": [ { "name": "chain", "in": "path", "description": "The blockchain on which the token exists", "required": true, "schema": { "type": "string" }, "example": "ethereum" }, { "name": "address", "in": "path", "description": "The contract address of the token", "required": true, "schema": { "type": "string" }, "example": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }, { "name": "limit", "in": "query", "description": "Number of results to return (default: 20, max: 50)", "required": false, "schema": { "type": "integer", "format": "int32", "default": 20 }, "example": 20 }, { "name": "cursor", "in": "query", "description": "Pagination cursor for next page", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/TokenSwapActivityPaginatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/chain/{chain}/payment_token/{address}": { "get": { "tags": ["Contract Endpoints"], "summary": "Get payment token", "description": "Get a payment token by chain and contract address.", "operationId": "get_payment_token", "parameters": [ { "name": "address", "in": "path", "description": "The unique public blockchain identifier for the contract", "required": true, "schema": { "type": "string" } }, { "name": "chain", "in": "path", "description": "The blockchain on which to filter the results", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PaymentToken" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/chain/{chain}/contract/{address}": { "get": { "tags": ["Contract Endpoints"], "summary": "Get contract", "description": "Get contract metadata including collection information, contract standards, and ownership details.", "operationId": "get_contract", "parameters": [ { "name": "address", "in": "path", "description": "The unique public blockchain identifier for the contract", "required": true, "schema": { "type": "string" } }, { "name": "chain", "in": "path", "description": "The blockchain on which to filter the results", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ContractResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/chain/{chain}/contract/{address}/nfts": { "get": { "tags": ["NFT Endpoints"], "summary": "Get NFTs by contract", "description": "Get all NFTs for a specific contract address on a blockchain.", "operationId": "get_nfts_by_contract", "parameters": [ { "name": "address", "in": "path", "description": "Contract address", "required": true, "schema": { "type": "string" } }, { "name": "chain", "in": "path", "description": "Blockchain chain identifier", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of items to return per page", "required": false, "schema": { "type": "integer", "format": "int32", "description": "Number of items to return per page", "example": 20, "maximum": 200, "minimum": 1 }, "example": 20 }, { "name": "next.value", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/NftListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/chain/{chain}/contract/{address}/nfts/{identifier}": { "get": { "tags": ["NFT Endpoints"], "summary": "Get NFT", "description": "Get metadata, traits, ownership information, and rarity for a single NFT.", "operationId": "get_nft", "parameters": [ { "name": "chain", "in": "path", "description": "The blockchain on which to filter the results", "required": true, "schema": { "type": "string" }, "example": "ethereum" }, { "name": "address", "in": "path", "description": "The unique public blockchain identifier for the contract", "required": true, "schema": { "type": "string" }, "example": "0x8ba1f109551bD432803012645Hac136c94C19D6e" }, { "name": "identifier", "in": "path", "description": "The NFT token id", "required": true, "schema": { "type": "string" }, "example": 1 } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/NftResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/chain/{chain}/contract/{address}/nfts/{identifier}/owners": { "get": { "tags": ["NFT Endpoints"], "summary": "Get NFT owners", "description": "Get a paginated list of owners for a specific NFT. Particularly useful for ERC-1155 tokens which can have multiple owners.", "operationId": "get_nft_owners", "parameters": [ { "name": "chain", "in": "path", "description": "The blockchain on which to filter the results", "required": true, "schema": { "type": "string" }, "example": "ethereum" }, { "name": "address", "in": "path", "description": "The unique public blockchain identifier for the contract", "required": true, "schema": { "type": "string" }, "example": "0x8ba1f109551bD432803012645Hac136c94C19D6e" }, { "name": "identifier", "in": "path", "description": "The NFT token id", "required": true, "schema": { "type": "string" }, "example": 1 }, { "name": "limit", "in": "query", "description": "Number of results to return (default: 20, max: 100)", "required": false, "schema": { "type": "integer", "format": "int32", "default": 20 }, "example": 20 }, { "name": "next", "in": "query", "description": "Pagination cursor for next page", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "NFT owners", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/OwnersPaginatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/chain/{chain}/contract/{address}/nfts/{identifier}/collection": { "get": { "tags": ["Collection Endpoints"], "summary": "Get collection by NFT", "description": "Get the collection that an NFT belongs to. This is useful for multi-contract collections like Art Blocks where the item ID disambiguates which collection the NFT belongs to.", "operationId": "get_nft_collection", "parameters": [ { "name": "chain", "in": "path", "description": "The blockchain on which to filter the results", "required": true, "schema": { "type": "string" }, "example": "ethereum" }, { "name": "address", "in": "path", "description": "The unique public blockchain identifier for the contract", "required": true, "schema": { "type": "string" }, "example": "0x8ba1f109551bD432803012645Hac136c94C19D6e" }, { "name": "identifier", "in": "path", "description": "The NFT token id", "required": true, "schema": { "type": "string" }, "example": 1 } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CollectionDetailedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/chain/{chain}/contract/{address}/nfts/{identifier}/analytics": { "get": { "tags": ["NFT Endpoints"], "summary": "Get NFT analytics", "description": "Get analytics data for a specific NFT including sales history and floor price history.", "operationId": "get_nft_analytics", "parameters": [ { "name": "chain", "in": "path", "description": "The blockchain on which to filter the results", "required": true, "schema": { "type": "string" }, "example": "ethereum" }, { "name": "address", "in": "path", "description": "The unique public blockchain identifier for the contract", "required": true, "schema": { "type": "string" }, "example": "0x8ba1f109551bD432803012645Hac136c94C19D6e" }, { "name": "identifier", "in": "path", "description": "The NFT token id", "required": true, "schema": { "type": "string" }, "example": 1 } ], "responses": { "200": { "description": "NFT analytics data", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/NftAnalyticsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/chain/{chain}/account/{address}/nfts": { "get": { "tags": ["NFT Endpoints"], "summary": "Get NFTs by account", "description": "Get all NFTs owned by a specific account on a blockchain, with optional collection filtering.", "operationId": "get_nfts_by_account", "parameters": [ { "name": "address", "in": "path", "description": "Account address", "required": true, "schema": { "type": "string" } }, { "name": "chain", "in": "path", "description": "Blockchain chain identifier", "required": true, "schema": { "type": "string" } }, { "name": "collection", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of items to return per page", "required": false, "schema": { "type": "integer", "format": "int32", "description": "Number of items to return per page", "example": 20, "maximum": 200, "minimum": 1 }, "example": 20 }, { "name": "next.value", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/NftListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/accounts/{address_or_username}": { "get": { "tags": ["Account Endpoints"], "summary": "Get an OpenSea account profile", "description": "Get an OpenSea Account Profile including details such as bio, social media usernames, and profile image.", "operationId": "get_account", "parameters": [ { "name": "address_or_username", "in": "path", "description": "The blockchain address or username of the account to retrieve", "required": true, "schema": { "type": "string" }, "example": "0x8ba1f109551bD432803012645Hac136c94C19D6e" } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/AccountResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/accounts/resolve/{identifier}": { "get": { "tags": ["Account Endpoints"], "summary": "Resolve an account identifier", "description": "Resolve an ENS name (e.g. vitalik.eth), OpenSea username, or wallet address to canonical account info including address, username, and ENS name. The ENS path performs both forward resolution (name → address) and reverse lookup (address → canonical primary name). The address and ENS paths perform enrichment calls (username + ENS reverse lookup) in parallel. The username path only needs an ENS reverse lookup after the initial resolution and runs it sequentially. The ENS and username paths require an extra initial call and may be slower than the address path on cache misses.", "operationId": "resolve_account", "parameters": [ { "name": "identifier", "in": "path", "description": "An ENS name (e.g. vitalik.eth), OpenSea username, or wallet address to resolve", "required": true, "schema": { "type": "string", "maxLength": 256, "minLength": 0 }, "example": "vitalik.eth" } ], "responses": { "200": { "description": "Resolved account info", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/AccountResolveResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/account/{address}/tokens": { "get": { "tags": ["Token Endpoints"], "summary": "Get token balances by account", "description": "Get fungible token balances for a specific wallet address. Returns quantity (in display units, not raw/wei), USD value, and token metadata for each token held.", "operationId": "get_token_balances_by_account", "parameters": [ { "name": "address", "in": "path", "description": "Wallet address", "required": true, "schema": { "type": "string" }, "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }, { "name": "limit", "in": "query", "description": "Number of results to return (default: 20, max: 100)", "required": false, "schema": { "type": "integer", "format": "int32", "default": 20 }, "example": 20 }, { "name": "chains", "in": "query", "description": "Filter by blockchain(s)", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChainIdentifier" } }, "example": "ethereum" }, { "name": "sort_by", "in": "query", "description": "Sort field (default: usd_value)", "required": false, "schema": { "type": "string", "enum": [ "USD_VALUE", "MARKET_CAP", "ONE_DAY_VOLUME", "PRICE", "ONE_DAY_PRICE_CHANGE", "SEVEN_DAY_PRICE_CHANGE" ] }, "example": "usd_value" }, { "name": "sort_direction", "in": "query", "description": "Sort direction (default: desc)", "required": false, "schema": { "type": "string", "enum": ["asc", "desc"] }, "example": "desc" }, { "name": "disable_spam_filtering", "in": "query", "description": "When true, disables OpenSea's heuristic spam filtering and returns tokens that would normally be hidden (low liquidity, dust, flagged-as-spam, etc.). Tokens flagged for trust & safety enforcement or as malicious are still filtered out regardless. Surfaced tokens carry a `status` field on the response indicating why they would have been filtered.", "required": false, "schema": { "type": "boolean", "default": false }, "example": false }, { "name": "cursor", "in": "query", "description": "Pagination cursor for next page", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/TokenBalancePaginatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/account/{address}/portfolio": { "get": { "tags": ["Account Endpoints"], "summary": "Get portfolio stats for an account", "description": "Get portfolio analytics including total value, NFT/token breakdown, and P&L for a wallet address over a given timeframe.", "operationId": "get_portfolio_stats", "parameters": [ { "name": "address", "in": "path", "description": "The wallet address", "required": true, "schema": { "type": "string" }, "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }, { "name": "timeframe", "in": "query", "description": "Timeframe for P&L calculation: HOUR, DAY, WEEK, MONTH", "required": false, "schema": { "type": "string", "default": "DAY", "description": "Timeframe for portfolio analytics queries", "enum": ["HOUR", "DAY", "WEEK", "MONTH"] } } ], "responses": { "200": { "description": "Portfolio stats", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PortfolioStatsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/account/{address}/portfolio/history": { "get": { "tags": ["Account Endpoints"], "summary": "Get portfolio net worth history for an account", "description": "Get net worth time series data for a wallet address over a given timeframe.", "operationId": "get_portfolio_history", "parameters": [ { "name": "address", "in": "path", "description": "The wallet address", "required": true, "schema": { "type": "string" }, "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }, { "name": "timeframe", "in": "query", "description": "Timeframe for history: HOUR, DAY, WEEK, MONTH", "required": false, "schema": { "type": "string", "default": "DAY", "description": "Timeframe for portfolio analytics queries", "enum": ["HOUR", "DAY", "WEEK", "MONTH"] } } ], "responses": { "200": { "description": "Portfolio history", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PortfolioHistoryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/account/{address}/offers_received": { "get": { "tags": ["Account Endpoints"], "summary": "Get offers received by an account", "description": "Get a paginated list of offers received on items owned by a wallet address.", "operationId": "get_profile_offers_received", "parameters": [ { "name": "address", "in": "path", "description": "The wallet address", "required": true, "schema": { "type": "string" }, "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }, { "name": "after", "in": "query", "description": "Cursor for pagination", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results to return", "required": false, "schema": { "type": "integer", "format": "int32", "default": 50 } }, { "name": "collection_slugs", "in": "query", "description": "Filter by collection slugs", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "chains", "in": "query", "description": "Filter by chains", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChainIdentifier" } } }, { "name": "sort_by", "in": "query", "description": "Sort by field", "required": false, "schema": { "type": "string", "default": "START_TIME", "enum": ["START_TIME", "TOP_ASSET_OFFER"] } }, { "name": "sort_direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": ["asc", "desc"] } } ], "responses": { "200": { "description": "Offers received for account", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/OffersResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/account/{address}/offers": { "get": { "tags": ["Account Endpoints"], "summary": "Get active offers made by an account", "description": "Get a paginated list of active offers made by a wallet address.", "operationId": "get_profile_offers", "parameters": [ { "name": "address", "in": "path", "description": "The wallet address", "required": true, "schema": { "type": "string" }, "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }, { "name": "after", "in": "query", "description": "Cursor for pagination", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results to return", "required": false, "schema": { "type": "integer", "format": "int32", "default": 50 } }, { "name": "collection_slugs", "in": "query", "description": "Filter by collection slugs", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "chains", "in": "query", "description": "Filter by chains", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChainIdentifier" } } }, { "name": "sort_by", "in": "query", "description": "Sort by field", "required": false, "schema": { "type": "string", "default": "START_TIME", "enum": ["START_TIME", "END_TIME"] } }, { "name": "sort_direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": ["asc", "desc"] } } ], "responses": { "200": { "description": "Active offers for account", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/OffersResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/account/{address}/listings": { "get": { "tags": ["Account Endpoints"], "summary": "Get active listings for an account", "description": "Get a paginated list of active listings created by a wallet address.", "operationId": "get_profile_listings", "parameters": [ { "name": "address", "in": "path", "description": "The wallet address", "required": true, "schema": { "type": "string" }, "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }, { "name": "after", "in": "query", "description": "Cursor for pagination", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results to return", "required": false, "schema": { "type": "integer", "format": "int32", "default": 50 } }, { "name": "collection_slugs", "in": "query", "description": "Filter by collection slugs", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "chains", "in": "query", "description": "Filter by chains", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChainIdentifier" } } }, { "name": "sort_by", "in": "query", "description": "Sort by field", "required": false, "schema": { "type": "string", "default": "START_TIME", "enum": ["START_TIME", "END_TIME"] } }, { "name": "sort_direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": ["asc", "desc"] } } ], "responses": { "200": { "description": "Active listings for account", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ListingsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/account/{address}/favorites": { "get": { "tags": ["Account Endpoints"], "summary": "Get items favorited by an account", "description": "Get a paginated list of items favorited by a wallet address.", "operationId": "get_profile_favorites", "parameters": [ { "name": "address", "in": "path", "description": "The wallet address", "required": true, "schema": { "type": "string" }, "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }, { "name": "after", "in": "query", "description": "Cursor for pagination", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results to return", "required": false, "schema": { "type": "integer", "format": "int32", "default": 50 } }, { "name": "sort_by", "in": "query", "description": "Sort by field", "required": false, "schema": { "type": "string", "default": "CREATED_DATE", "enum": [ "CREATED_DATE", "PRICE", "RARITY", "LISTING_CREATED_DATE", "LAST_SALE" ] } }, { "name": "sort_direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": ["asc", "desc"] } }, { "name": "chains", "in": "query", "description": "Filter by chains", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChainIdentifier" }, "uniqueItems": true } } ], "responses": { "200": { "description": "Favorited items", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/NftListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/account/{address}/collections": { "get": { "tags": ["Account Endpoints"], "summary": "Get collections owned by an account", "description": "Get a paginated list of collections owned by a wallet address, with ownership data.", "operationId": "get_profile_collections", "parameters": [ { "name": "address", "in": "path", "description": "The wallet address", "required": true, "schema": { "type": "string" }, "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }, { "name": "after", "in": "query", "description": "Cursor for pagination", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results to return", "required": false, "schema": { "type": "integer", "format": "int32", "default": 50 } }, { "name": "chains", "in": "query", "description": "Filter by chains", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChainIdentifier" } } } ], "responses": { "200": { "description": "Collections owned by account", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ProfileCollectionsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "schemas": { "ChainIdentifier": { "type": "string", "default": "ethereum", "description": "Blockchain chain identifier. Use the chain slug (e.g., 'ethereum', 'polygon', 'arbitrum', 'optimism', 'base')", "enum": [ "blast", "base", "ethereum", "zora", "arbitrum", "sei", "avalanche", "polygon", "optimism", "ape_chain", "flow", "b3", "soneium", "ronin", "bera_chain", "solana", "shape", "unichain", "gunzilla", "abstract", "animechain", "hyperevm", "somnia", "monad", "hyperliquid", "megaeth", "ink" ], "example": "ethereum" }, "AssetQuantityInput": { "type": "object", "description": "An asset with quantity in base units", "properties": { "chain": { "type": "string", "description": "The blockchain chain", "example": "ethereum" }, "contract": { "type": "string", "description": "The contract address", "example": "0x0000000000000000000000000000000000000000" }, "token_id": { "type": "string", "description": "Token ID for NFTs", "example": 1234 }, "amount": { "type": "string", "description": "Amount in base units (wei/lamports)", "example": 1000000000000000000 } }, "required": ["amount", "chain", "contract"] }, "SwapQuoteInput": { "type": "object", "description": "The original swap quote assets", "properties": { "from_assets": { "type": "array", "description": "Assets being sent/spent", "items": { "$ref": "#/components/schemas/AssetQuantityInput" }, "maxItems": 100, "minItems": 0 }, "to_assets": { "type": "array", "description": "Assets being received", "items": { "$ref": "#/components/schemas/AssetQuantityInput" }, "maxItems": 100, "minItems": 0 } }, "required": ["from_assets"] }, "TransactionIdentifierInput": { "type": "object", "description": "A transaction identifier with optional swap provider", "properties": { "transaction_hash": { "type": "string", "description": "The transaction hash", "example": "0xabc123..." }, "chain": { "type": "string", "description": "The blockchain chain", "example": "ethereum" }, "swap_provider": { "type": "string", "description": "The swap provider used (e.g. RELAY, JUPITER, ZERO_EX, LOCAL_BUY_NFT). Required when relay_request_id is not provided. Can be omitted for cross-chain flows that use relay_request_id.", "example": "RELAY" } }, "required": ["chain", "transaction_hash"] }, "TransactionReceiptRequest": { "type": "object", "description": "Request to get a transaction receipt/status", "properties": { "transaction_identifiers": { "type": "array", "description": "Transaction identifiers to look up", "items": { "$ref": "#/components/schemas/TransactionIdentifierInput" }, "maxItems": 100, "minItems": 0 }, "swap_quote": { "$ref": "#/components/schemas/SwapQuoteInput", "description": "The swap quote that was originally submitted" }, "relay_request_id": { "type": "string", "description": "Relay request ID for cross-chain tracking" }, "request_id": { "type": "string", "description": "Request ID for workflow tracking" } }, "required": ["swap_quote"] }, "AssetIdentifierResponse": { "type": "object", "description": "Asset identifier with chain, contract address, and optional token ID", "properties": { "chain": { "type": "string", "description": "The blockchain chain", "example": "ethereum" }, "contract": { "type": "string", "description": "The contract address", "example": "0xBd3531dA5CF5857e7CfAA92426877b022e612cf8" }, "token_id": { "type": "string", "description": "Token ID for NFTs", "example": 1234 } }, "required": ["chain", "contract"] }, "AssetReceiptResponse": { "type": "object", "description": "Receipt for a single asset in a transaction", "properties": { "asset": { "$ref": "#/components/schemas/AssetIdentifierResponse", "description": "The asset received" }, "quantity": { "type": "string", "description": "Quantity received in base units", "example": 1 }, "price": { "$ref": "#/components/schemas/PriceResponse", "description": "Price paid per item" } }, "required": ["asset", "price", "quantity"] }, "PriceResponse": { "type": "object", "description": "Price information for an asset", "properties": { "amount": { "type": "string", "description": "Amount in the token's native units", "example": 5.5 }, "currency": { "type": "string", "description": "Token symbol", "example": "ETH" }, "usd": { "type": "string", "description": "USD equivalent", "example": 19250 } }, "required": ["amount", "usd"] }, "TotalSpentResponse": { "type": "object", "description": "Total spent across all assets in a transaction", "properties": { "price_per_token": { "type": "array", "description": "Price breakdown per token type", "items": { "$ref": "#/components/schemas/PriceResponse" } } }, "required": ["price_per_token"] }, "TransactionReceiptResponse": { "type": "object", "description": "Transaction receipt with status and asset details", "properties": { "status": { "type": "string", "description": "Transaction status: PENDING, SUCCESS, PARTIAL_SUCCESS, or FAILED", "example": "SUCCESS" }, "fail_reason": { "type": "string", "description": "Reason for failure, if applicable" }, "asset_receipts": { "type": "array", "description": "Successfully received assets", "items": { "$ref": "#/components/schemas/AssetReceiptResponse" } }, "failed_asset_receipts": { "type": "array", "description": "Assets that failed to be received", "items": { "$ref": "#/components/schemas/AssetReceiptResponse" } }, "total_spent": { "$ref": "#/components/schemas/TotalSpentResponse", "description": "Total amount spent across all assets" }, "missing_assets": { "type": "array", "description": "Assets that are missing from the receipt", "items": { "$ref": "#/components/schemas/AssetIdentifierResponse" } }, "cross_chain_refunded": { "type": "boolean", "description": "Whether a cross-chain refund was issued" } }, "required": [ "asset_receipts", "failed_asset_receipts", "missing_assets", "status", "total_spent" ] }, "Eip3009Fields": { "type": "object", "properties": { "caller_address": { "type": "string" }, "signature": { "type": "string" }, "chain_id": { "type": "integer", "format": "int64" }, "from": { "type": "string" }, "to": { "type": "string" }, "value": { "type": "integer" }, "valid_after": { "type": "integer" }, "valid_before": { "type": "integer" }, "nonce": { "type": "string" } } }, "ToolUsageRequest": { "type": "object", "properties": { "verification_type": { "type": "string" }, "tool_chain_id": { "type": "integer", "format": "int64" }, "tool_registry_address": { "type": "string" }, "tool_onchain_id": { "type": "integer", "format": "int64" }, "latency_ms": { "type": "integer", "format": "int64" }, "eip3009": { "$ref": "#/components/schemas/Eip3009Fields" }, "x402": { "$ref": "#/components/schemas/X402SettlementFields" } } }, "X402SettlementFields": { "type": "object", "properties": { "caller_address": { "type": "string" }, "tx_hash": { "type": "string" }, "chain_id": { "type": "integer", "format": "int64" } } }, "ToolUsageResponse": { "type": "object", "properties": { "id": { "type": "string" }, "verified": { "type": "boolean" }, "verification_type": { "type": "string" } }, "required": ["id", "verification_type", "verified"] }, "BatchTokensRequest": { "type": "object", "description": "Request body for batch token retrieval by contract identifiers", "properties": { "contracts": { "type": "array", "description": "List of token contract identifiers to retrieve", "items": { "$ref": "#/components/schemas/TokenContractInput" } } }, "required": ["contracts"] }, "TokenContractInput": { "type": "object", "description": "A token contract identifier consisting of chain and address", "properties": { "chain": { "type": "string", "description": "The blockchain the token is on", "example": "ethereum" }, "address": { "type": "string", "description": "The contract address of the token", "example": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" } }, "required": ["address", "chain"] }, "TokenBaseResponse": { "type": "object", "description": "Common token identity fields shared across token responses", "properties": { "address": { "type": "string", "description": "The contract address of the token", "example": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }, "chain": { "type": "string", "description": "The blockchain the token is on", "example": "ethereum" }, "name": { "type": "string", "description": "The display name of the token", "example": "USD Coin" }, "symbol": { "type": "string", "description": "The ticker symbol of the token", "example": "USDC" }, "image_url": { "type": "string", "description": "URL of the token's image" }, "usd_price": { "type": "string", "description": "Current price in USD", "example": 1 }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimal places", "example": 6 }, "opensea_url": { "type": "string", "description": "URL to the token page on OpenSea" } }, "required": [ "address", "chain", "decimals", "name", "opensea_url", "symbol", "usd_price" ] }, "TokenBatchResponse": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/TokenDetailedResponse" } } }, "required": ["tokens"] }, "TokenDetailedResponse": { "type": "object", "description": "Detailed token information including stats and social links", "properties": { "address": { "type": "string", "description": "The contract address of the token", "example": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }, "chain": { "type": "string", "description": "The blockchain the token is on", "example": "ethereum" }, "name": { "type": "string", "description": "The display name of the token", "example": "USD Coin" }, "symbol": { "type": "string", "description": "The ticker symbol of the token", "example": "USDC" }, "image_url": { "type": "string", "description": "URL of the token's image" }, "usd_price": { "type": "string", "description": "Current price in USD", "example": 1 }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimal places", "example": 6 }, "opensea_url": { "type": "string", "description": "URL to the token page on OpenSea" }, "description": { "type": "string", "description": "A description of the token" }, "stats": { "$ref": "#/components/schemas/TokenStatsResponse", "description": "Market statistics for the token" }, "socials": { "$ref": "#/components/schemas/TokenSocialsResponse", "description": "Social media links for the token" }, "status": { "type": "string", "default": "OK", "description": "Token safety status based on OpenSea's spam-classification rules. `OK` for tokens that pass all safety checks (the normal case). Categories are intentionally broad and may evolve. Possible values, in decreasing severity: `WARNING` (flagged as risky/suspicious — caution advised), `SPAM` (flagged as spam), `LOW_LIQUIDITY` (insufficient liquidity pool reserves), `OK` (passes all checks).", "enum": ["OK", "WARNING", "SPAM", "LOW_LIQUIDITY"] } }, "required": [ "address", "chain", "decimals", "name", "opensea_url", "symbol", "usd_price" ] }, "TokenSocialsResponse": { "type": "object", "description": "Social media links for a token", "properties": { "website": { "type": "string", "description": "The token's website URL" }, "twitter_handle": { "type": "string", "description": "The token's Twitter/X handle" }, "telegram_identifier": { "type": "string", "description": "The token's Telegram identifier" }, "twitter_follower_count": { "type": "integer", "format": "int64", "description": "Twitter/X follower count" } } }, "TokenStatsResponse": { "type": "object", "description": "Market statistics for a token", "properties": { "market_cap_usd": { "type": "number", "format": "double", "description": "Market capitalization in USD" }, "fdv_usd": { "type": "number", "format": "double", "description": "Fully diluted valuation in USD" }, "circulating_supply": { "type": "number", "format": "double", "description": "Circulating supply of the token" }, "max_supply": { "type": "number", "format": "double", "description": "Maximum supply of the token" }, "total_supply": { "type": "number", "format": "double", "description": "Total supply of the token" }, "volume_24h": { "type": "number", "format": "double", "description": "24-hour trading volume in USD" }, "price_change_1h": { "type": "number", "format": "double", "description": "Price change percentage over the last hour" }, "price_change_24h": { "type": "number", "format": "double", "description": "Price change percentage over the last 24 hours" }, "price_change_7d": { "type": "number", "format": "double", "description": "Price change percentage over the last 7 days" }, "price_change_30d": { "type": "number", "format": "double", "description": "Price change percentage over the last 30 days" } } }, "SwapAssetInput": { "type": "object", "description": "An asset to swap with chain, contract address, and amount", "properties": { "chain": { "type": "string", "description": "Chain slug (e.g. ethereum, base, solana)", "example": "ethereum" }, "contract": { "type": "string", "description": "Contract address of the token", "example": "0x0000000000000000000000000000000000000000" }, "amount": { "type": "string", "description": "Amount in the smallest unit of the token (e.g. wei for ETH). Use \"0\" for to_assets to receive the market rate.", "example": 1000000000000000000 } }, "required": ["amount", "chain", "contract"] }, "SwapExecuteRequest": { "type": "object", "description": "Request body for executing a token swap", "properties": { "from_assets": { "type": "array", "description": "Tokens to swap from (at least one required)", "items": { "$ref": "#/components/schemas/SwapAssetInput" } }, "to_assets": { "type": "array", "description": "Tokens to swap to (at least one required)", "items": { "$ref": "#/components/schemas/SwapAssetInput" } }, "address": { "type": "string", "description": "Wallet address executing the swap", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "recipient": { "type": "string", "description": "Recipient address (defaults to sender address)" }, "slippage_tolerance": { "type": "number", "format": "double", "description": "Slippage tolerance as a decimal (0.0 to 0.5, default: 0.01)", "example": 0.01 } }, "required": ["address", "from_assets", "to_assets"] }, "SwapCostResponse": { "type": "object", "description": "A cost component of the swap", "properties": { "type": { "type": "string", "description": "The type of cost", "enum": [ "GAS", "PROVIDER", "PROTOCOL", "SWAP", "MARKETPLACE", "CREATOR", "MEV_PROTECTION" ], "example": "GAS" }, "usd": { "type": "string", "description": "Cost amount in USD", "example": 0.5 } }, "required": ["type", "usd"] }, "SwapExecuteResponse": { "type": "object", "description": "Response containing quote details and executable swap transactions", "properties": { "quote": { "$ref": "#/components/schemas/SwapQuoteDetails", "description": "Price and fee details for the swap" }, "transactions": { "type": "array", "description": "Ordered list of transactions to execute the swap", "items": { "$ref": "#/components/schemas/SwapTransactionResponse" } } }, "required": ["quote", "transactions"] }, "SwapPriceImpact": { "type": "object", "description": "Price impact of the swap", "properties": { "usd": { "type": "string", "description": "Price impact in USD (negative means user loses value)", "example": -1.5 }, "percent": { "type": "string", "description": "Price impact as a percentage (negative means user loses value)", "example": -0.08 } }, "required": ["percent", "usd"] }, "SwapQuoteDetails": { "type": "object", "description": "Price and fee details for a swap quote", "properties": { "total_price_usd": { "type": "number", "format": "double", "description": "Total value of tokens received in USD", "example": 1850.5 }, "total_cost_usd": { "type": "number", "format": "double", "description": "Total cost of tokens sent in USD", "example": 1869 }, "slippage_tolerance": { "type": "number", "format": "double", "description": "Slippage tolerance as a decimal (e.g. 0.01 = 1%)", "example": 0.01 }, "estimated_duration_ms": { "type": "integer", "format": "int64", "description": "Estimated swap duration in milliseconds", "example": 30000 }, "marketplace_fee_bps": { "type": "integer", "format": "int32", "description": "Marketplace fee in basis points", "example": 50 }, "price_impact": { "$ref": "#/components/schemas/SwapPriceImpact", "description": "Price impact of the swap (null if unavailable)" }, "swap_provider": { "type": "string", "description": "The swap provider that fulfilled this quote (null if unavailable)", "example": "RELAY" }, "recommended_slippage": { "type": "number", "format": "double", "description": "Recommended slippage tolerance based on volatility analysis (null if unavailable)", "example": 2 }, "costs": { "type": "array", "description": "Breakdown of costs for the swap", "items": { "$ref": "#/components/schemas/SwapCostResponse" } }, "route_errors": { "type": "array", "description": "Errors encountered for individual swap routes", "items": { "$ref": "#/components/schemas/SwapRouteErrorResponse" } } }, "required": [ "costs", "estimated_duration_ms", "marketplace_fee_bps", "route_errors", "slippage_tolerance", "total_cost_usd", "total_price_usd" ] }, "SwapRouteErrorResponse": { "type": "object", "description": "An error encountered for a specific swap route", "properties": { "type": { "type": "string", "description": "The error type", "example": "INSUFFICIENT_FUNDS" } }, "required": ["type"] }, "SwapTransactionResponse": { "type": "object", "description": "A transaction to be submitted onchain to execute a swap", "properties": { "chain": { "type": "string", "description": "The blockchain for this transaction", "example": "ethereum" }, "to": { "type": "string", "description": "The destination address for the transaction" }, "data": { "type": "string", "description": "The transaction data. For EVM chains: hex-encoded calldata. For SVM chains: comma-separated instructions in programId:data format." }, "value": { "type": "string", "description": "The native token value to send with the transaction" } }, "required": ["chain", "data"] }, "ConsiderationItem": { "type": "object", "properties": { "itemType": { "type": "integer", "format": "int32" }, "token": { "type": "string" }, "identifierOrCriteria": { "type": "string" }, "startAmount": { "type": "string" }, "endAmount": { "type": "string" }, "recipient": { "type": "string" } }, "required": [ "endAmount", "identifierOrCriteria", "itemType", "recipient", "startAmount", "token" ] }, "OfferItem": { "type": "object", "properties": { "itemType": { "type": "integer", "format": "int32" }, "token": { "type": "string" }, "identifierOrCriteria": { "type": "string" }, "startAmount": { "type": "string" }, "endAmount": { "type": "string" } }, "required": [ "endAmount", "identifierOrCriteria", "itemType", "startAmount", "token" ] }, "SeaportParameters": { "type": "object", "properties": { "offerer": { "type": "string" }, "zone": { "type": "string" }, "offer": { "type": "array", "items": { "$ref": "#/components/schemas/OfferItem" } }, "consideration": { "type": "array", "items": { "$ref": "#/components/schemas/ConsiderationItem" } }, "orderType": { "type": "integer", "format": "int32" }, "startTime": { "type": "string" }, "endTime": { "type": "string" }, "zoneHash": { "type": "string" }, "salt": { "type": "string" }, "conduitKey": { "type": "string" }, "totalOriginalConsiderationItems": { "type": "integer", "format": "int32" }, "counter": { "type": "string" } }, "required": [ "conduitKey", "consideration", "counter", "endTime", "offer", "offerer", "orderType", "salt", "startTime", "totalOriginalConsiderationItems", "zoneHash" ] }, "SeaportRequest": { "type": "object", "properties": { "parameters": { "$ref": "#/components/schemas/SeaportParameters" }, "protocol_address": { "type": "string" }, "signature": { "type": "string" } }, "required": ["parameters", "protocol_address", "signature"] }, "CollectionInner": { "type": "object", "properties": { "slug": { "type": "string" } }, "required": ["slug"] }, "ContractInner": { "type": "object", "properties": { "address": { "type": "string" } }, "required": ["address"] }, "Criteria": { "type": "object", "properties": { "collection": { "$ref": "#/components/schemas/CollectionInner" }, "contract": { "$ref": "#/components/schemas/ContractInner" }, "traits": { "type": "array", "items": { "$ref": "#/components/schemas/TraitData" } }, "numeric_traits": { "type": "array", "items": { "$ref": "#/components/schemas/NumericTraitData" } }, "encoded_token_ids": { "type": "string" } } }, "Item": { "type": "object", "properties": { "itemType": { "type": "integer", "format": "int32" }, "token": { "type": "string" }, "identifierOrCriteria": { "type": "string" }, "startAmount": { "type": "string" }, "endAmount": { "type": "string" } }, "required": [ "endAmount", "identifierOrCriteria", "itemType", "startAmount", "token" ] }, "NumericTraitData": { "type": "object", "properties": { "type": { "type": "string" }, "min": { "type": "number", "format": "float" }, "max": { "type": "number", "format": "float" } }, "required": ["type"] }, "Offer": { "allOf": [ { "$ref": "#/components/schemas/ListingOrOffer" }, { "type": "object", "properties": { "order_hash": { "type": "string" }, "chain": { "type": "string" }, "protocol_data": { "$ref": "#/components/schemas/ProtocolData" }, "protocol_address": { "type": "string" }, "asset": { "$ref": "#/components/schemas/OrderAsset" }, "remaining_quantity": { "type": "integer", "format": "int64" }, "order_created_at": { "type": "integer", "format": "int64" }, "criteria": { "$ref": "#/components/schemas/Criteria" }, "price": { "$ref": "#/components/schemas/Price" }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "FULFILLED", "EXPIRED", "CANCELLED" ] } } } ], "required": [ "chain", "order_hash", "price", "remaining_quantity", "status" ] }, "Order": { "type": "object", "properties": { "order_hash": { "type": "string" }, "chain": { "type": "string" }, "protocol_data": { "$ref": "#/components/schemas/ProtocolData" }, "protocol_address": { "type": "string" }, "asset": { "$ref": "#/components/schemas/OrderAsset" }, "remaining_quantity": { "type": "integer", "format": "int64" }, "order_created_at": { "type": "integer", "format": "int64" } }, "required": ["chain", "order_hash", "remaining_quantity"] }, "OrderAsset": { "type": "object", "properties": { "identifier": { "type": "string" }, "contract": { "type": "string" } }, "required": ["contract"] }, "Parameters": { "type": "object", "properties": { "offerer": { "type": "string" }, "offer": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } }, "consideration": { "type": "array", "items": { "$ref": "#/components/schemas/ConsiderationItem" } }, "startTime": { "type": "string" }, "endTime": { "type": "string" }, "orderType": { "type": "integer", "format": "int32" }, "zone": { "type": "string" }, "zoneHash": { "type": "string" }, "salt": { "type": "string" }, "conduitKey": { "type": "string" }, "totalOriginalConsiderationItems": { "type": "integer", "format": "int32" }, "counter": { "type": "integer" } }, "required": [ "conduitKey", "consideration", "counter", "endTime", "offer", "offerer", "orderType", "salt", "startTime", "totalOriginalConsiderationItems", "zone", "zoneHash" ] }, "Price": { "type": "object", "properties": { "currency": { "type": "string" }, "decimals": { "type": "integer", "format": "int32" }, "value": { "type": "string" } }, "required": ["currency", "decimals", "value"] }, "ProtocolData": { "type": "object", "properties": { "parameters": { "$ref": "#/components/schemas/Parameters" }, "signature": { "type": "string" } }, "required": ["parameters"] }, "TraitData": { "type": "object", "properties": { "type": { "type": "string" }, "value": { "type": "string" } }, "required": ["type", "value"] }, "Listing": { "allOf": [ { "$ref": "#/components/schemas/ListingOrOffer" }, { "type": "object", "properties": { "order_hash": { "type": "string" }, "chain": { "type": "string" }, "protocol_data": { "$ref": "#/components/schemas/ProtocolData" }, "protocol_address": { "type": "string" }, "asset": { "$ref": "#/components/schemas/OrderAsset" }, "remaining_quantity": { "type": "integer", "format": "int64" }, "order_created_at": { "type": "integer", "format": "int64" }, "price": { "$ref": "#/components/schemas/ListingPrice" }, "type": { "type": "string" }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "FULFILLED", "EXPIRED", "CANCELLED" ] } } } ], "required": [ "chain", "order_hash", "price", "remaining_quantity", "status", "type" ] }, "ListingPrice": { "type": "object", "properties": { "current": { "$ref": "#/components/schemas/Price" } }, "required": ["current"] }, "CancelRequest": { "type": "object", "properties": { "offererSignature": { "type": "string" } } }, "CancelResponse": { "type": "object", "properties": { "last_signature_issued_valid_until": { "type": "string" } }, "required": ["last_signature_issued_valid_until"] }, "CollectionCriteria": { "type": "object", "properties": { "slug": { "type": "string" } }, "required": ["slug"] }, "ContractCriteria": { "type": "object", "properties": { "address": { "type": "string" } }, "required": ["address"] }, "CriteriaRequest": { "type": "object", "description": "Criteria for collection or trait offers. When traits are specified, the offer targets NFTs matching those traits. For supported collections, the identifierOrCriteria (merkle root) will be '0' and trait matching is validated server-side at fulfillment time.", "properties": { "collection": { "$ref": "#/components/schemas/CollectionCriteria" }, "contract": { "$ref": "#/components/schemas/ContractCriteria" }, "trait": { "$ref": "#/components/schemas/TraitCriteria", "deprecated": true, "description": "Deprecated: Use 'traits' array instead which supports both single and multiple traits." }, "traits": { "type": "array", "description": "Trait criteria for the offer. Each trait specifies a type and value that target NFTs must match. These traits are validated server-side at fulfillment time.", "items": { "$ref": "#/components/schemas/TraitCriteria" } }, "numericTraits": { "type": "array", "description": "Numeric trait criteria for the offer. Each entry specifies a trait type with optional min/max range bounds. Can be combined with categorical traits.", "items": { "$ref": "#/components/schemas/NumericTraitCriteria" } } }, "required": ["collection"] }, "NumericTraitCriteria": { "type": "object", "properties": { "type": { "type": "string" }, "min": { "type": "number", "format": "double" }, "max": { "type": "number", "format": "double" } }, "required": ["type"] }, "OfferWithCriteriaRequest": { "type": "object", "properties": { "protocol_data": { "$ref": "#/components/schemas/SeaportProtocolDataModel" }, "criteria": { "$ref": "#/components/schemas/CriteriaRequest" }, "protocol_address": { "type": "string" } }, "required": ["criteria", "protocol_address", "protocol_data"] }, "SeaportProtocolDataModel": { "type": "object", "properties": { "parameters": { "$ref": "#/components/schemas/SeaportParameters" }, "signature": { "type": "string" } }, "required": ["parameters", "signature"] }, "TraitCriteria": { "type": "object", "properties": { "type": { "type": "string" }, "value": { "type": "string" } }, "required": ["type", "value"] }, "ConsiderationObject": { "type": "object", "properties": { "asset_contract_address": { "type": "string" }, "token_id": { "type": "string" } }, "required": ["asset_contract_address", "token_id"] }, "FulfillerObject": { "type": "object", "properties": { "address": { "type": "string" } }, "required": ["address"] }, "FullfillmentDataRequest": { "type": "object", "properties": { "offer": { "$ref": "#/components/schemas/OfferObject" }, "fulfiller": { "$ref": "#/components/schemas/FulfillerObject" }, "consideration": { "$ref": "#/components/schemas/ConsiderationObject" }, "units_to_fill": { "type": "integer", "format": "int64", "description": "Optional quantity of units to fulfill; defaults to 1 for offers" }, "include_optional_creator_fees": { "type": "boolean", "default": false, "description": "Whether to include optional creator fees in the fulfillment. If creator fees are already required, this is a no-op. Defaults to false." } }, "required": ["fulfiller", "offer"] }, "OfferObject": { "type": "object", "properties": { "hash": { "type": "string" }, "chain": { "type": "string" }, "protocol_address": { "type": "string" } }, "required": ["chain", "hash", "protocol_address"] }, "AdditionalRecipient": { "type": "object", "properties": { "value": { "type": "array", "items": { "$ref": "#/components/schemas/Type" } }, "amount": { "type": "integer" }, "recipient": { "type": "string" }, "typeAsString": { "type": "string" }, "nativeValueCopy": { "type": "array", "items": {} } } }, "Address": { "type": "object", "properties": { "value": { "type": "string" }, "typeAsString": { "type": "string" } } }, "AdvancedOrder": { "type": "object", "properties": { "value": { "type": "array", "items": { "$ref": "#/components/schemas/Type" } }, "parameters": { "$ref": "#/components/schemas/OrderParameters" }, "numerator": { "type": "integer" }, "denominator": { "type": "integer" }, "signature": { "type": "string", "format": "byte" }, "extraData": { "type": "string", "format": "byte" }, "typeAsString": { "type": "string" }, "nativeValueCopy": { "type": "array", "items": {} } } }, "BasicOrderParameters": { "type": "object", "properties": { "value": { "type": "array", "items": { "$ref": "#/components/schemas/Type" } }, "considerationToken": { "type": "string" }, "considerationIdentifier": { "type": "integer" }, "considerationAmount": { "type": "integer" }, "offerer": { "type": "string" }, "zone": { "type": "string" }, "offerToken": { "type": "string" }, "offerIdentifier": { "type": "integer" }, "offerAmount": { "type": "integer" }, "basicOrderType": { "type": "integer" }, "startTime": { "type": "integer" }, "endTime": { "type": "integer" }, "zoneHash": { "type": "string", "format": "byte" }, "salt": { "type": "integer" }, "offererConduitKey": { "type": "string", "format": "byte" }, "fulfillerConduitKey": { "type": "string", "format": "byte" }, "totalOriginalAdditionalRecipients": { "type": "integer" }, "additionalRecipients": { "type": "array", "items": { "$ref": "#/components/schemas/AdditionalRecipient" } }, "signature": { "type": "string", "format": "byte" }, "typeAsString": { "type": "string" }, "nativeValueCopy": { "type": "array", "items": {} } } }, "CriteriaResolver": { "type": "object", "properties": { "value": { "type": "array", "items": { "$ref": "#/components/schemas/Type" } }, "orderIndex": { "type": "integer" }, "side": { "type": "integer" }, "index": { "type": "integer" }, "identifier": { "type": "integer" }, "criteriaProof": { "type": "array", "items": { "type": "string", "format": "byte" } }, "typeAsString": { "type": "string" }, "nativeValueCopy": { "type": "array", "items": {} } } }, "FulfillAdvancedOrder": { "allOf": [ { "$ref": "#/components/schemas/SeaportCall" }, { "type": "object", "properties": { "advancedOrder": { "$ref": "#/components/schemas/AdvancedOrder" }, "criteriaResolvers": { "type": "array", "items": { "$ref": "#/components/schemas/CriteriaResolver" } }, "fulfillerConduitKey": { "type": "string" }, "recipient": { "$ref": "#/components/schemas/Address" } } } ], "required": [ "advancedOrder", "criteriaResolvers", "fulfillerConduitKey", "recipient" ] }, "FulfillAvailableAdvancedOrders": { "allOf": [ { "$ref": "#/components/schemas/SeaportCall" }, { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/AdvancedOrder" } }, "criteriaResolvers": { "type": "array", "items": { "$ref": "#/components/schemas/CriteriaResolver" } }, "offerFulfillments": { "type": "array", "items": { "type": "array", "items": { "$ref": "#/components/schemas/FulfillmentComponent" } } }, "considerationFulfillments": { "type": "array", "items": { "type": "array", "items": { "$ref": "#/components/schemas/FulfillmentComponent" } } }, "fulfillerConduitKey": { "type": "string" }, "recipient": { "$ref": "#/components/schemas/Address" }, "maximumFulfilled": { "$ref": "#/components/schemas/Uint256" } } } ], "required": [ "considerationFulfillments", "criteriaResolvers", "fulfillerConduitKey", "maximumFulfilled", "offerFulfillments", "orders", "recipient" ] }, "FulfillAvailableOrders": { "allOf": [ { "$ref": "#/components/schemas/SeaportCall" }, { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "offerFulfillments": { "type": "array", "items": { "type": "array", "items": { "$ref": "#/components/schemas/FulfillmentComponent" } } }, "considerationFulfillments": { "type": "array", "items": { "type": "array", "items": { "$ref": "#/components/schemas/FulfillmentComponent" } } }, "fulfillerConduitKey": { "type": "string" }, "maximumFulfilled": { "$ref": "#/components/schemas/Uint256" } } } ], "required": [ "considerationFulfillments", "fulfillerConduitKey", "maximumFulfilled", "offerFulfillments", "orders" ] }, "FulfillBasicOrder": { "allOf": [ { "$ref": "#/components/schemas/SeaportCall" }, { "type": "object", "properties": { "parameters": { "$ref": "#/components/schemas/BasicOrderParameters" } } } ], "required": ["parameters"] }, "FulfillListingResponse": { "type": "object", "properties": { "protocol": { "type": "string" }, "fulfillment_data": { "$ref": "#/components/schemas/FulfillmentData" } }, "required": ["fulfillment_data", "protocol"] }, "FulfillOrder": { "allOf": [ { "$ref": "#/components/schemas/SeaportCall" }, { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/Order" }, "fulfillerConduitKey": { "type": "string" } } } ], "required": ["fulfillerConduitKey", "order"] }, "Fulfillment": { "type": "object", "properties": { "value": { "type": "array", "items": { "$ref": "#/components/schemas/Type" } }, "offerComponents": { "type": "array", "items": { "$ref": "#/components/schemas/FulfillmentComponent" } }, "considerationComponents": { "type": "array", "items": { "$ref": "#/components/schemas/FulfillmentComponent" } }, "typeAsString": { "type": "string" }, "nativeValueCopy": { "type": "array", "items": {} } } }, "FulfillmentComponent": { "type": "object", "properties": { "value": { "type": "array", "items": { "$ref": "#/components/schemas/Type" } }, "orderIndex": { "type": "integer" }, "itemIndex": { "type": "integer" }, "typeAsString": { "type": "string" }, "nativeValueCopy": { "type": "array", "items": {} } } }, "FulfillmentData": { "type": "object", "properties": { "transaction": { "$ref": "#/components/schemas/TransactionData" }, "orders": { "type": "array", "items": { "$ref": "#/components/schemas/OrderData" } } }, "required": ["orders", "transaction"] }, "MatchAdvancedOrders": { "allOf": [ { "$ref": "#/components/schemas/SeaportCall" }, { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/AdvancedOrder" } }, "criteriaResolvers": { "type": "array", "items": { "$ref": "#/components/schemas/CriteriaResolver" } }, "fulfillments": { "type": "array", "items": { "$ref": "#/components/schemas/Fulfillment" } }, "recipient": { "$ref": "#/components/schemas/Address" } } } ], "required": ["criteriaResolvers", "fulfillments", "orders", "recipient"] }, "MatchOrders": { "allOf": [ { "$ref": "#/components/schemas/SeaportCall" }, { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "fulfillments": { "type": "array", "items": { "$ref": "#/components/schemas/Fulfillment" } } } } ], "required": ["fulfillments", "orders"] }, "OrderData": { "type": "object", "properties": { "parameters": { "$ref": "#/components/schemas/Parameters" }, "signature": { "type": "string" } }, "required": ["parameters", "signature"] }, "OrderParameters": { "type": "object", "properties": { "value": { "type": "array", "items": { "$ref": "#/components/schemas/Type" } }, "offerer": { "type": "string" }, "zone": { "type": "string" }, "offer": { "type": "array", "items": { "$ref": "#/components/schemas/OfferItem" } }, "consideration": { "type": "array", "items": { "$ref": "#/components/schemas/ConsiderationItem" } }, "orderType": { "type": "integer" }, "startTime": { "type": "integer" }, "endTime": { "type": "integer" }, "zoneHash": { "type": "string", "format": "byte" }, "salt": { "type": "integer" }, "conduitKey": { "type": "string", "format": "byte" }, "totalOriginalConsiderationItems": { "type": "integer" }, "typeAsString": { "type": "string" }, "nativeValueCopy": { "type": "array", "items": {} } } }, "SeaportCall": {}, "TransactionData": { "type": "object", "properties": { "function": { "type": "string" }, "chain": { "type": "integer", "format": "int32" }, "to": { "type": "string" }, "value": { "type": "string" }, "input_data": { "oneOf": [ { "$ref": "#/components/schemas/FulfillAdvancedOrder" }, { "$ref": "#/components/schemas/FulfillAvailableAdvancedOrders" }, { "$ref": "#/components/schemas/FulfillAvailableOrders" }, { "$ref": "#/components/schemas/FulfillBasicOrder" }, { "$ref": "#/components/schemas/FulfillOrder" }, { "$ref": "#/components/schemas/MatchAdvancedOrders" }, { "$ref": "#/components/schemas/MatchOrders" } ] } }, "required": ["chain", "function", "input_data", "to", "value"] }, "Type": { "type": "object", "properties": { "value": {}, "typeAsString": { "type": "string" } } }, "Uint256": { "type": "object", "properties": { "value": { "type": "integer" }, "bitSize": { "type": "integer", "format": "int32" }, "typeAsString": { "type": "string" } } }, "BuildOfferRequest": { "type": "object", "properties": { "offerer": { "type": "string" }, "quantity": { "type": "integer", "format": "int32" }, "criteria": { "$ref": "#/components/schemas/CriteriaObject" }, "protocol_address": { "type": "string" }, "offer_protection_enabled": { "type": "boolean" } }, "required": [ "criteria", "offer_protection_enabled", "offerer", "protocol_address", "quantity" ] }, "CollectionObject": { "type": "object", "properties": { "slug": { "type": "string" } }, "required": ["slug"] }, "CriteriaObject": { "type": "object", "properties": { "collection": { "$ref": "#/components/schemas/CollectionObject" }, "trait": { "$ref": "#/components/schemas/TraitObject", "deprecated": true, "description": "Deprecated: Use 'traits' array instead which supports both single and multiple traits." }, "traits": { "type": "array", "items": { "$ref": "#/components/schemas/TraitObject" } }, "numericTraits": { "type": "array", "items": { "$ref": "#/components/schemas/NumericTraitCriteria" } } }, "required": ["collection"] }, "TraitObject": { "type": "object", "properties": { "type": { "type": "string" }, "value": { "type": "string" } }, "required": ["type", "value"] }, "BuildOfferResponse": { "type": "object", "properties": { "partialParameters": { "$ref": "#/components/schemas/PartialParameters" }, "criteria": { "$ref": "#/components/schemas/CriteriaRequest", "description": "The criteria to pass through to the POST /api/v2/offers submit step. Includes collection and trait information so trait offers are not accidentally submitted as collection offers." }, "encodedTokenIds": { "type": "string", "description": "Encoded token IDs that can be used to fulfill the criteria offer. When identifierOrCriteria is '0', this field is informational only and not required for order construction." } }, "required": ["criteria", "partialParameters"] }, "Consideration": { "type": "object", "properties": { "itemType": { "type": "integer", "format": "int32" }, "token": { "type": "string" }, "identifierOrCriteria": { "type": "string", "description": "For criteria-based offers, this is the merkle root of eligible token IDs. For trait offers on supported collections, this will be '0' — trait matching is validated server-side at fulfillment time instead of via onchain merkle proof." }, "startAmount": { "type": "string" }, "endAmount": { "type": "string" }, "recipient": { "type": "string" } }, "required": [ "endAmount", "identifierOrCriteria", "itemType", "recipient", "startAmount", "token" ] }, "PartialParameters": { "type": "object", "properties": { "consideration": { "type": "array", "items": { "$ref": "#/components/schemas/Consideration" } }, "zone": { "type": "string" }, "zoneHash": { "type": "string" } }, "required": ["consideration", "zone", "zoneHash"] }, "BatchNftsRequest": { "type": "object", "description": "Request body for batch NFT retrieval by identifiers", "properties": { "identifiers": { "type": "array", "description": "List of NFT identifiers to retrieve", "items": { "$ref": "#/components/schemas/NftIdentifierInput" } } }, "required": ["identifiers"] }, "NftIdentifierInput": { "type": "object", "description": "An NFT identifier consisting of chain, contract address, and token ID", "properties": { "chain": { "type": "string", "description": "The blockchain the NFT is on", "example": "ethereum" }, "contract_address": { "type": "string", "description": "The contract address of the NFT", "example": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D" }, "token_id": { "type": "string", "description": "The token ID of the NFT", "example": 1 } }, "required": ["chain", "contract_address", "token_id"] }, "AgentBindingResponse": { "type": "object", "properties": { "agent_id": { "type": "string" }, "binding_contract": { "type": "string" }, "agent": { "$ref": "#/components/schemas/AgentNftResponse" }, "registered_by": { "type": "string" } }, "required": ["agent", "agent_id", "binding_contract"] }, "AgentNftResponse": { "type": "object", "properties": { "chain": { "type": "string" }, "token_id": { "type": "string" }, "contract_address": { "type": "string" } }, "required": ["chain", "contract_address", "token_id"] }, "Nft": { "type": "object", "properties": { "identifier": { "type": "string" }, "collection": { "type": "string" }, "contract": { "type": "string" }, "token_standard": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "image_url": { "type": "string" }, "display_image_url": { "type": "string" }, "display_animation_url": { "type": "string" }, "metadata_url": { "type": "string" }, "opensea_url": { "type": "string" }, "updated_at": { "type": "string" }, "is_disabled": { "type": "boolean" }, "is_nsfw": { "type": "boolean" }, "original_image_url": { "type": "string" }, "original_animation_url": { "type": "string" }, "traits": { "type": "array", "items": { "$ref": "#/components/schemas/Trait" } } }, "required": [ "collection", "contract", "identifier", "is_disabled", "is_nsfw", "opensea_url", "token_standard", "traits", "updated_at" ] }, "NftBatchResponse": { "type": "object", "properties": { "nfts": { "type": "array", "items": { "$ref": "#/components/schemas/NftDetailed" } } }, "required": ["nfts"] }, "NftDetailed": { "type": "object", "properties": { "identifier": { "type": "string" }, "collection": { "type": "string" }, "contract": { "type": "string" }, "token_standard": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "image_url": { "type": "string" }, "display_image_url": { "type": "string" }, "display_animation_url": { "type": "string" }, "metadata_url": { "type": "string" }, "opensea_url": { "type": "string" }, "updated_at": { "type": "string" }, "is_disabled": { "type": "boolean" }, "is_nsfw": { "type": "boolean" }, "original_image_url": { "type": "string" }, "original_animation_url": { "type": "string" }, "traits": { "type": "array", "items": { "$ref": "#/components/schemas/Trait" } }, "animation_url": { "type": "string" }, "is_suspicious": { "type": "boolean" }, "creator": { "type": "string" }, "owners": { "type": "array", "items": { "$ref": "#/components/schemas/Owner" } }, "rarity": { "$ref": "#/components/schemas/Rarity" }, "subscription": { "$ref": "#/components/schemas/SubscriptionInfoResponse" }, "agent_binding": { "$ref": "#/components/schemas/AgentBindingResponse" } }, "required": [ "collection", "contract", "creator", "identifier", "is_disabled", "is_nsfw", "is_suspicious", "opensea_url", "owners", "token_standard", "traits", "updated_at" ] }, "Owner": { "type": "object", "properties": { "address": { "type": "string" }, "quantity": { "type": "integer", "format": "int32" }, "quantity_string": { "type": "string" } }, "required": ["address", "quantity", "quantity_string"] }, "Rarity": { "type": "object", "properties": { "strategy_id": { "type": "string" }, "strategy_version": { "type": "string" }, "rank": { "type": "integer", "format": "int64" } }, "required": ["strategy_id", "strategy_version"] }, "SubscriptionInfoResponse": { "type": "object", "properties": { "expires_at": { "type": "string", "format": "date-time" }, "is_renewable": { "type": "boolean" }, "is_expired": { "type": "boolean" } }, "required": ["is_expired", "is_renewable"] }, "Trait": { "type": "object", "properties": { "trait_type": { "type": "string" }, "display_type": { "type": "string" }, "max_value": { "type": "string" }, "value": {} }, "required": ["trait_type", "value"] }, "CrossChainPaymentToken": { "type": "object", "description": "Payment token to use for cross-chain fulfillment", "properties": { "chain": { "type": "string", "description": "Chain of the payment token (e.g. 'base', 'ethereum')", "example": "base" }, "token_address": { "type": "string", "description": "Contract address of the payment token (use 0x0000000000000000000000000000000000000000 for native token)", "example": "0x0000000000000000000000000000000000000000" } }, "required": ["chain", "token_address"] }, "SweepCollectionRequest": { "type": "object", "description": "Request to sweep buy items from a collection", "properties": { "collection_slug": { "type": "string", "description": "The slug of the collection to sweep", "example": "pudgypenguins" }, "payment": { "$ref": "#/components/schemas/CrossChainPaymentToken", "description": "The token to pay with" }, "max_items": { "type": "integer", "format": "int32", "description": "Maximum number of items to buy (1-50)", "example": 5 }, "max_price_per_item": { "type": "string", "description": "Maximum price per item in the payment token's units", "example": 10 }, "buyer": { "type": "string", "description": "Address of the buyer", "example": "0x..." }, "recipient": { "type": "string", "description": "Optional recipient address for the purchased items" } }, "required": [ "buyer", "collection_slug", "max_items", "max_price_per_item", "payment" ] }, "JsonNode": {}, "SweepCollectionResponse": { "type": "object", "description": "Response containing ordered blockchain actions to execute for a collection sweep", "properties": { "steps": { "type": "array", "description": "Ordered list of blockchain actions to execute. Each action is a JSON object with a single field indicating the type (e.g. buyItemAction, permit2SignatureAction, paymentApprovalAction) and its associated data. Serialized using proto3 JSON format — fields with default values (empty string, 0, false) may be omitted.", "items": { "$ref": "#/components/schemas/JsonNode" } }, "errors": { "type": "array", "description": "Errors encountered during sweep. Present alongside steps for partial success cases (e.g. some listings became unavailable).", "items": { "$ref": "#/components/schemas/SweepError" } } }, "required": ["steps"] }, "SweepError": { "type": "object", "description": "An error encountered during a sweep operation", "properties": { "message": { "type": "string", "description": "Human-readable error message" } }, "required": ["message"] }, "FullfillListingRequest": { "type": "object", "properties": { "listing": { "$ref": "#/components/schemas/ListingObject" }, "fulfiller": { "$ref": "#/components/schemas/FulfillerObject" }, "consideration": { "$ref": "#/components/schemas/ConsiderationObject" }, "recipient": { "type": "string" }, "units_to_fill": { "type": "integer", "format": "int64", "description": "Optional quantity of units to fulfill; defaults to remaining units for listings" }, "include_optional_creator_fees": { "type": "boolean", "default": false, "description": "Whether to include optional creator fees in the fulfillment. If creator fees are already required, this is a no-op. Defaults to false." } }, "required": ["fulfiller", "listing"] }, "ListingObject": { "type": "object", "properties": { "hash": { "type": "string" }, "chain": { "type": "string" }, "protocol_address": { "type": "string" } }, "required": ["chain", "hash", "protocol_address"] }, "CrossChainFulfillmentRequest": { "type": "object", "description": "Request to fulfill one or more listings using a payment token on a different chain or a different token on the same chain", "properties": { "listings": { "type": "array", "description": "One or more listings to fulfill", "items": { "$ref": "#/components/schemas/ListingObject" } }, "fulfiller": { "$ref": "#/components/schemas/FulfillerObject" }, "payment": { "$ref": "#/components/schemas/CrossChainPaymentToken", "description": "The token to pay with" }, "recipient": { "type": "string", "description": "Optional recipient address for the purchased items" } }, "required": ["fulfiller", "listings", "payment"] }, "CrossChainFulfillmentResponse": { "type": "object", "description": "Response containing ordered transactions to execute for cross-chain fulfillment", "properties": { "transactions": { "type": "array", "description": "Ordered list of transactions to execute. May include approval and buy/swap transactions.", "items": { "$ref": "#/components/schemas/SwapTransactionResponse" } } }, "required": ["transactions"] }, "CreateListingActionsRequest": { "type": "object", "description": "Request to get listing creation actions", "properties": { "items": { "type": "array", "description": "Items to list for sale", "items": { "$ref": "#/components/schemas/ListingItem" } }, "address": { "type": "string", "description": "Maker (seller) wallet address", "example": "0x..." }, "use_creator_fee": { "type": "boolean", "description": "Whether to include creator fees. Defaults to true." }, "taker": { "type": "string", "description": "Optional taker address for private listings" } }, "required": ["address", "items"] }, "ListingItem": { "type": "object", "description": "An item to list for sale", "properties": { "chain": { "type": "string", "description": "Chain of the item (e.g. 'ethereum', 'base')", "example": "ethereum" }, "contract": { "type": "string", "description": "Contract address of the NFT", "example": "0x..." }, "token_id": { "type": "string", "description": "Token ID of the NFT", "example": 1234 }, "quantity": { "type": "integer", "format": "int64", "description": "Quantity to list (use 1 for ERC-721)", "example": 1 }, "price": { "$ref": "#/components/schemas/ListingPrice", "description": "Price per item" }, "start_time": { "type": "string", "description": "Listing start time in ISO 8601 format. Defaults to now.", "example": "2026-05-01T00:00:00Z" }, "end_time": { "type": "string", "description": "Listing end time in ISO 8601 format. Defaults to 30 days from start.", "example": "2026-06-01T00:00:00Z" } }, "required": ["chain", "contract", "price", "quantity", "token_id"] }, "CreateListingActionsResponse": { "type": "object", "description": "Response containing blockchain actions to execute for listing creation", "properties": { "steps": { "type": "array", "description": "Ordered list of blockchain actions to execute. May include approval actions (e.g. setApprovalForAll) and a createListingsAction containing the Seaport order to sign. Serialized using proto3 JSON format — fields with default values (empty string, 0, false) may be omitted.", "items": { "$ref": "#/components/schemas/JsonNode" } } }, "required": ["steps"] }, "DropMintResponse": { "type": "object", "description": "Ready-to-sign mint transaction data", "properties": { "to": { "type": "string", "description": "Transaction target contract address" }, "data": { "type": "string", "description": "Encoded transaction data (hex)" }, "value": { "type": "string", "description": "Transaction value in wei (hex)" }, "chain": { "type": "string", "description": "Chain identifier" } }, "required": ["chain", "data", "to", "value"] }, "V1ErrorWrapper": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "required": ["errors"] }, "DropMintRequest": { "type": "object", "description": "Mint request parameters", "properties": { "minter": { "type": "string", "description": "Wallet address that will receive the minted tokens", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "minLength": 1 }, "quantity": { "type": "integer", "format": "int32", "description": "Number of tokens to mint", "example": 1, "maximum": 100, "minimum": 1 } }, "required": ["minter", "quantity"] }, "DropDeployResponse": { "type": "object", "description": "Ready-to-sign deploy contract transaction data", "properties": { "to": { "type": "string", "description": "Transaction target contract address" }, "data": { "type": "string", "description": "Encoded transaction data (hex)" }, "value": { "type": "string", "description": "Transaction value in wei (hex)" }, "chain": { "type": "string", "description": "Chain identifier" } }, "required": ["chain", "data", "to", "value"] }, "DropDeployRequest": { "type": "object", "description": "Deploy contract request parameters", "properties": { "chain": { "type": "string", "description": "Chain slug (e.g. \"ethereum\", \"base\")", "example": "ethereum", "minLength": 1 }, "contract_name": { "type": "string", "description": "Name for the new contract", "example": "My NFT Collection", "minLength": 1 }, "contract_symbol": { "type": "string", "description": "Symbol for the new contract", "example": "MNFT", "minLength": 1 }, "drop_type": { "type": "string", "description": "Drop type (see validation error for supported values)", "example": "seadrop_v1_erc721", "minLength": 1 }, "token_type": { "type": "string", "description": "Token type (see validation error for supported values)", "example": "erc721_standard", "minLength": 1 }, "sender": { "type": "string", "description": "Deployer wallet address", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "minLength": 1 } }, "required": [ "chain", "contract_name", "contract_symbol", "drop_type", "sender", "token_type" ] }, "BatchCollectionsRequest": { "type": "object", "description": "Request body for batch collection retrieval by slugs", "properties": { "slugs": { "type": "array", "description": "List of collection slugs to retrieve", "example": ["boredapeyachtclub", "doodles-official"], "items": { "type": "string" } } }, "required": ["slugs"] }, "CollectionBatchResponse": { "type": "object", "properties": { "collections": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionResponse" } } }, "required": ["collections"] }, "CollectionResponse": { "type": "object", "properties": { "collection": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "image_url": { "type": "string" }, "banner_image_url": { "type": "string" }, "owner": { "type": "string" }, "safelist_status": { "type": "string" }, "category": { "type": "string" }, "is_disabled": { "type": "boolean" }, "is_nsfw": { "type": "boolean" }, "trait_offers_enabled": { "type": "boolean" }, "collection_offers_enabled": { "type": "boolean" }, "opensea_url": { "type": "string" }, "project_url": { "type": "string" }, "wiki_url": { "type": "string" }, "discord_url": { "type": "string" }, "telegram_url": { "type": "string" }, "twitter_username": { "type": "string" }, "instagram_username": { "type": "string" }, "contracts": { "type": "array", "items": { "$ref": "#/components/schemas/Contract" } } }, "required": [ "collection", "collection_offers_enabled", "contracts", "is_disabled", "is_nsfw", "name", "opensea_url", "safelist_status", "trait_offers_enabled" ] }, "Contract": { "type": "object", "properties": { "address": { "type": "string" }, "chain": { "type": "string" } }, "required": ["address", "chain"] }, "MetadataIngestionError": { "type": "object", "properties": { "errorType": { "type": "string" }, "message": { "type": "string" }, "url": { "type": "string" }, "statusCode": { "type": "integer", "format": "int32" } }, "required": ["errorType", "message"] }, "ValidateMetadataAssetIdentifier": { "type": "object", "properties": { "chain": { "type": "string" }, "contractAddress": { "type": "string" }, "tokenId": { "type": "string" } }, "required": ["chain", "contractAddress", "tokenId"] }, "ValidateMetadataAttribute": { "type": "object", "properties": { "traitType": { "type": "string" }, "value": { "type": "string" }, "displayType": { "type": "string" } }, "required": ["traitType", "value"] }, "ValidateMetadataDetails": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "originalImageUrl": { "type": "string" }, "processedImageUrl": { "type": "string" }, "originalAnimationUrl": { "type": "string" }, "processedAnimationUrl": { "type": "string" }, "externalUrl": { "type": "string" }, "backgroundColor": { "type": "string" }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/ValidateMetadataAttribute" } } }, "required": ["attributes"] }, "ValidateMetadataResponse": { "type": "object", "properties": { "assetIdentifier": { "$ref": "#/components/schemas/ValidateMetadataAssetIdentifier" }, "tokenUri": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/ValidateMetadataDetails" }, "error": { "$ref": "#/components/schemas/MetadataIngestionError" } }, "required": ["assetIdentifier"] }, "InstantApiKeyResponse": { "type": "object", "description": "Instant API key response", "properties": { "api_key": { "type": "string", "description": "The API key to use in X-API-KEY header" }, "name": { "type": "string", "description": "Key name for identification and revocation" }, "expires_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp when the key expires" }, "rate_limits": { "$ref": "#/components/schemas/RateLimitsResponse", "description": "Rate limits for this key" }, "upgrade_url": { "type": "string", "description": "URL to upgrade to higher rate limits" } }, "required": [ "api_key", "expires_at", "name", "rate_limits", "upgrade_url" ] }, "RateLimitsResponse": { "type": "object", "description": "Rate limits for the API key", "properties": { "read": { "type": "string", "description": "Read rate limit", "example": "60/m" }, "write": { "type": "string", "description": "Write rate limit", "example": "5/m" }, "fulfillment": { "type": "string", "description": "Fulfillment rate limit", "example": "5/m" } }, "required": ["fulfillment", "read", "write"] }, "TransferAsset": { "type": "object", "description": "An asset to transfer", "properties": { "chain": { "type": "string", "description": "The chain the asset is on (e.g. ethereum, base, solana)", "example": "ethereum" }, "contract": { "type": "string", "description": "The contract address of the asset", "example": "0xBd3531dA5CF5857e7CfAA92426877b022e612cf8" }, "token_id": { "type": "string", "description": "The token ID of the asset", "example": 1234 }, "quantity": { "type": "string", "description": "The quantity to transfer in raw units (1 for ERC721, raw amount for ERC1155/fungible)", "example": 1 } }, "required": ["chain", "contract", "quantity", "token_id"] }, "TransferRequest": { "type": "object", "description": "Request to transfer NFTs or tokens between wallets", "properties": { "assets": { "type": "array", "description": "List of assets to transfer", "items": { "$ref": "#/components/schemas/TransferAsset" } }, "from_address": { "type": "string", "description": "Address of the sender wallet", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }, "to_address": { "type": "string", "description": "Address of the recipient wallet", "example": "0x28c6c06298d514db089934071355e5743bf21d60" } }, "required": ["assets", "from_address", "to_address"] }, "TransferResponse": { "type": "object", "description": "Response containing ordered blockchain actions to execute for an asset transfer", "properties": { "steps": { "type": "array", "description": "Ordered list of blockchain actions to execute. Each action is a JSON object with a single field indicating the type (e.g. transferAction, approvalAction) and its associated data. Serialized using proto3 JSON format — fields with default values (empty string, 0, false) may be omitted.", "items": { "$ref": "#/components/schemas/JsonNode" } } }, "required": ["steps"] }, "ToolListItemResponse": { "type": "object", "properties": { "tool_id": { "type": "string" }, "registry_chain": { "type": "string" }, "registry_addr": { "type": "string" }, "creator": { "type": "string" }, "metadata_uri": { "type": "string" }, "manifest_hash": { "type": "string" }, "endpoint_url": { "type": "string" }, "endpoint_domain": { "type": "string" }, "manifest_hash_verified": { "type": "boolean" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "created_at", "creator", "is_active", "manifest_hash", "manifest_hash_verified", "metadata_uri", "registry_addr", "registry_chain", "tool_id", "updated_at" ] }, "ToolListPaginatedResponse": { "type": "object", "properties": { "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolListItemResponse" } }, "next": { "type": "string" } }, "required": ["tools"] }, "RegisteredToolResponse": { "type": "object", "properties": { "tool_id": { "type": "string" }, "registry_chain": { "type": "string" }, "registry_addr": { "type": "string" }, "creator": { "type": "string" }, "metadata_uri": { "type": "string" }, "manifest_hash": { "type": "string" }, "endpoint_url": { "type": "string" }, "endpoint_domain": { "type": "string" }, "manifest_hash_verified": { "type": "boolean" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "inputs": {}, "outputs": {}, "creator_address": { "type": "string" }, "endpoint": { "type": "string" }, "access": { "$ref": "#/components/schemas/ToolAccessResponse" }, "pricing_recipients": { "type": "array", "items": { "$ref": "#/components/schemas/ToolPricingRecipientResponse" } } }, "required": [ "created_at", "creator", "is_active", "manifest_hash", "manifest_hash_verified", "metadata_uri", "pricing_recipients", "registry_addr", "registry_chain", "tool_id", "updated_at" ] }, "ToolAccessResponse": { "type": "object", "properties": { "open_access": { "type": "boolean" }, "logic": { "type": "string" }, "requirements": { "type": "array", "items": { "$ref": "#/components/schemas/ToolRequirementResponse" } } }, "required": ["logic", "open_access", "requirements"] }, "ToolCollectionResponse": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "image_url": { "type": "string" }, "opensea_url": { "type": "string" }, "contracts": { "type": "array", "items": { "$ref": "#/components/schemas/Contract" } } }, "required": ["contracts", "name", "opensea_url", "slug"] }, "ToolPricingRecipientResponse": { "type": "object", "properties": { "recipient": { "type": "string" }, "payment_chain": { "type": "string" }, "asset": { "type": "string" }, "protocol": { "type": "string" }, "amount_per_call": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "amount_per_call", "asset", "created_at", "payment_chain", "protocol", "recipient" ] }, "ToolRequirementResponse": { "type": "object", "properties": { "kind": { "type": "string" }, "type": { "type": "string" }, "collection_address": { "type": "string" }, "token_id": { "type": "string" }, "min_tier": { "type": "integer", "format": "int32" }, "token_address": { "type": "string" }, "min_balance": { "type": "string" }, "data": { "type": "string" }, "label": { "type": "string" }, "links": { "type": "object", "additionalProperties": { "type": "string" } }, "collection": { "$ref": "#/components/schemas/ToolCollectionResponse" } }, "required": ["kind", "type"] }, "ToolPaymentStatsResponse": { "type": "object", "properties": { "total_payments": { "type": "integer", "format": "int64" }, "total_volume_usd": { "type": "number", "format": "double" }, "unique_buyers": { "type": "integer", "format": "int64" }, "payments_last_24h": { "type": "integer", "format": "int64" }, "payments_last_7d": { "type": "integer", "format": "int64" } }, "required": [ "payments_last_24h", "payments_last_7d", "total_payments", "total_volume_usd", "unique_buyers" ] }, "ToolSearchPaginatedResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ToolSearchResultResponse" } }, "next": { "type": "string" } }, "required": ["results"] }, "ToolSearchResultResponse": { "type": "object", "properties": { "tool_id": { "type": "string" }, "registry_chain": { "type": "string" }, "registry_addr": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "creator": { "type": "string" }, "creator_display_name": { "type": "string" }, "endpoint_domain": { "type": "string" }, "access_type": { "type": "string" }, "payment_stats": { "$ref": "#/components/schemas/ToolPaymentStatsResponse" }, "created_at": { "type": "string" }, "pricing_recipients": { "type": "array", "items": { "$ref": "#/components/schemas/ToolPricingRecipientResponse" } }, "access": { "$ref": "#/components/schemas/ToolAccessResponse" } }, "required": [ "access_type", "created_at", "creator", "creator_display_name", "description", "endpoint_domain", "name", "registry_addr", "registry_chain", "tags", "tool_id" ] }, "TokenPaginatedResponse": { "type": "object", "description": "Paginated list of tokens", "properties": { "tokens": { "type": "array", "description": "List of tokens", "items": { "$ref": "#/components/schemas/TokenResponse" } }, "next": { "type": "string", "description": "Cursor for the next page of results" } }, "required": ["tokens"] }, "TokenResponse": { "type": "object", "description": "A token with summary market data", "properties": { "address": { "type": "string", "description": "The contract address of the token", "example": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }, "chain": { "type": "string", "description": "The blockchain the token is on", "example": "ethereum" }, "name": { "type": "string", "description": "The display name of the token", "example": "USD Coin" }, "symbol": { "type": "string", "description": "The ticker symbol of the token", "example": "USDC" }, "image_url": { "type": "string", "description": "URL of the token's image" }, "usd_price": { "type": "string", "description": "Current price in USD", "example": 1 }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimal places", "example": 6 }, "opensea_url": { "type": "string", "description": "URL to the token page on OpenSea" }, "market_cap_usd": { "type": "number", "format": "double", "description": "Market capitalization in USD" }, "volume_24h": { "type": "number", "format": "double", "description": "24-hour trading volume in USD" }, "price_change_24h": { "type": "number", "format": "double", "description": "Price change percentage over the last 24 hours" } }, "required": [ "address", "chain", "decimals", "name", "opensea_url", "symbol", "usd_price" ] }, "TokenGroupCurrencyResponse": { "type": "object", "description": "A currency within a token group", "properties": { "address": { "type": "string", "description": "The contract address of the currency", "example": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" }, "chain": { "type": "string", "description": "The blockchain the currency is on", "example": "ethereum" }, "name": { "type": "string", "description": "The display name of the currency", "example": "Wrapped Ether" }, "symbol": { "type": "string", "description": "The ticker symbol of the currency", "example": "WETH" }, "image_url": { "type": "string", "description": "URL of the currency's image" }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimal places", "example": 18 }, "usd_price": { "type": "string", "description": "Current price in USD", "example": 2345.67 } }, "required": [ "address", "chain", "decimals", "name", "symbol", "usd_price" ] }, "TokenGroupPaginatedResponse": { "type": "object", "description": "Paginated list of token groups", "properties": { "token_groups": { "type": "array", "description": "List of token groups", "items": { "$ref": "#/components/schemas/TokenGroupResponse" } }, "next": { "type": "string", "description": "Cursor for the next page of results" } }, "required": ["token_groups"] }, "TokenGroupResponse": { "type": "object", "description": "A token group representing equivalent currencies across different blockchains", "properties": { "slug": { "type": "string", "description": "Unique slug identifier for the token group", "example": "eth" }, "display_name": { "type": "string", "description": "Display name of the token group", "example": "Ethereum" }, "symbol": { "type": "string", "description": "Ticker symbol of the token group", "example": "ETH" }, "description": { "type": "string", "description": "Description of the token group" }, "image_url": { "type": "string", "description": "URL of the token group's image" }, "opensea_url": { "type": "string", "description": "URL to the token group page on OpenSea" }, "currencies": { "type": "array", "description": "Currencies in this token group", "items": { "$ref": "#/components/schemas/TokenGroupCurrencyResponse" } }, "primary_currency": { "$ref": "#/components/schemas/TokenGroupCurrencyResponse", "description": "The primary currency for this token group" }, "stats": { "$ref": "#/components/schemas/TokenGroupStatsResponse", "description": "Market statistics for the token group" }, "socials": { "$ref": "#/components/schemas/TokenGroupSocialsResponse", "description": "Social media links for the token group" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp when the token group was created" }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp when the token group was last updated" } }, "required": [ "created_at", "currencies", "display_name", "opensea_url", "primary_currency", "slug", "updated_at" ] }, "TokenGroupRollingStatsResponse": { "type": "object", "description": "Rolling statistics for a token group over multiple time periods", "properties": { "volume_1d": { "type": "string", "description": "1-day trading volume in USD" }, "volume_7d": { "type": "string", "description": "7-day trading volume in USD" }, "volume_30d": { "type": "string", "description": "30-day trading volume in USD" }, "price_change_1d": { "type": "number", "format": "double", "description": "1-day price change percentage" }, "price_change_7d": { "type": "number", "format": "double", "description": "7-day price change percentage" }, "price_change_30d": { "type": "number", "format": "double", "description": "30-day price change percentage" } } }, "TokenGroupSocialsResponse": { "type": "object", "description": "Social media links for a token group", "properties": { "website": { "type": "string", "description": "The token group's website URL" }, "twitter": { "type": "string", "description": "The token group's Twitter/X handle" }, "discord": { "type": "string", "description": "The token group's Discord invite URL" }, "telegram": { "type": "string", "description": "The token group's Telegram identifier" }, "coinmarketcap": { "type": "string", "description": "CoinMarketCap listing URL" }, "coingecko": { "type": "string", "description": "CoinGecko listing URL" } } }, "TokenGroupStatsResponse": { "type": "object", "description": "Market statistics for a token group", "properties": { "market_cap_usd": { "type": "string", "description": "Total market capitalization in USD" }, "volume_usd_24h": { "type": "string", "description": "24-hour trading volume in USD" }, "price_usd": { "type": "string", "description": "Current price in USD (from primary currency)" }, "price_change_percent_24h": { "type": "number", "format": "double", "description": "Price change percentage over the last 24 hours" }, "total_supply": { "type": "string", "description": "Total supply across all currencies in the group" }, "holders": { "type": "integer", "format": "int32", "description": "Number of holders" }, "rolling_stats": { "$ref": "#/components/schemas/TokenGroupRollingStatsResponse", "description": "Rolling statistics over multiple time periods" } }, "required": ["market_cap_usd", "volume_usd_24h"] }, "SwapQuoteResponse": { "type": "object", "description": "Swap quote with price details and executable transactions", "properties": { "quote": { "$ref": "#/components/schemas/SwapQuoteDetails", "description": "Price and fee details for the swap" }, "transactions": { "type": "array", "description": "Transactions to execute the swap", "items": { "$ref": "#/components/schemas/SwapTransactionResponse" } } }, "required": ["quote", "transactions"] }, "AccountSearchResponse": { "type": "object", "description": "Account search result", "properties": { "address": { "type": "string", "description": "Primary wallet address of the account" }, "username": { "type": "string", "description": "Username of the account" }, "profile_image_url": { "type": "string", "description": "URL of the account's profile image" }, "opensea_url": { "type": "string", "description": "URL to the account on OpenSea" } }, "required": ["address", "opensea_url"] }, "CollectionSearchResponse": { "type": "object", "description": "Collection search result", "properties": { "collection": { "type": "string", "description": "The collection slug", "example": "bored-ape-yacht-club" }, "name": { "type": "string", "description": "The collection name", "example": "Bored Ape Yacht Club" }, "image_url": { "type": "string", "description": "URL of the collection image" }, "is_disabled": { "type": "boolean", "description": "Whether trading is disabled for this collection" }, "is_nsfw": { "type": "boolean", "description": "Whether this collection is marked as NSFW" }, "opensea_url": { "type": "string", "description": "URL to the collection on OpenSea" } }, "required": [ "collection", "is_disabled", "is_nsfw", "name", "opensea_url" ] }, "NftSearchResponse": { "type": "object", "description": "NFT search result", "properties": { "identifier": { "type": "string", "description": "Token ID of the NFT", "example": 1234 }, "collection": { "type": "string", "description": "Collection slug the NFT belongs to", "example": "bored-ape-yacht-club" }, "contract": { "type": "string", "description": "Contract address of the NFT" }, "name": { "type": "string", "description": "Name of the NFT" }, "image_url": { "type": "string", "description": "URL of the NFT image" }, "opensea_url": { "type": "string", "description": "URL to the NFT on OpenSea" } }, "required": ["collection", "contract", "identifier", "opensea_url"] }, "SearchResponse": { "type": "object", "description": "Search results response", "properties": { "results": { "type": "array", "description": "List of search results ranked by relevance", "items": { "$ref": "#/components/schemas/SearchResultResponse" } } }, "required": ["results"] }, "SearchResultResponse": { "type": "object", "description": "A single search result with a type discriminator and the corresponding typed object", "properties": { "type": { "type": "string", "description": "The type of search result", "example": "collection" }, "collection": { "$ref": "#/components/schemas/CollectionSearchResponse", "description": "Collection details, present when type is 'collection'" }, "token": { "$ref": "#/components/schemas/TokenSearchResponse", "description": "Token details, present when type is 'token'" }, "nft": { "$ref": "#/components/schemas/NftSearchResponse", "description": "NFT details, present when type is 'nft'" }, "account": { "$ref": "#/components/schemas/AccountSearchResponse", "description": "Account details, present when type is 'account'" } }, "required": ["type"] }, "TokenSearchResponse": { "type": "object", "description": "Token (currency) search result", "properties": { "address": { "type": "string", "description": "The contract address of the token", "example": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }, "chain": { "type": "string", "description": "The blockchain the token is on", "example": "ethereum" }, "name": { "type": "string", "description": "The display name of the token", "example": "USD Coin" }, "symbol": { "type": "string", "description": "The ticker symbol of the token", "example": "USDC" }, "image_url": { "type": "string", "description": "URL of the token's image" }, "usd_price": { "type": "string", "description": "Current price in USD", "example": 1 }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimal places", "example": 6 }, "opensea_url": { "type": "string", "description": "URL to the token page on OpenSea" } }, "required": [ "address", "chain", "decimals", "name", "opensea_url", "symbol", "usd_price" ] }, "GetOrderResponse": { "type": "object", "properties": { "order": { "oneOf": [ { "$ref": "#/components/schemas/Listing" }, { "$ref": "#/components/schemas/Offer" } ] } }, "required": ["order"] }, "ListingOrOffer": {}, "OffersResponse": { "type": "object", "properties": { "offers": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" } }, "next": { "type": "string" } }, "required": ["offers"] }, "AssetMetadataResponse": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string" }, "external_link": { "type": "string" }, "animation_url": { "type": "string" }, "traits": { "type": "array", "items": { "$ref": "#/components/schemas/Trait" } } }, "required": ["traits"] }, "ListingsResponse": { "type": "object", "properties": { "listings": { "type": "array", "items": { "$ref": "#/components/schemas/Listing" } }, "next": { "type": "string" } }, "required": ["listings"] }, "AssetEventsResponse": { "type": "object", "properties": { "asset_events": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/OrderEvent" }, { "$ref": "#/components/schemas/SaleEvent" }, { "$ref": "#/components/schemas/TransferEvent" } ] } }, "next": { "type": "string" } }, "required": ["asset_events"] }, "Event": {}, "EventBase": { "type": "object", "properties": { "event_type": { "type": "string" }, "event_timestamp": { "type": "integer", "format": "int64" }, "transaction": { "type": "string" }, "order_hash": { "type": "string" }, "protocol_address": { "type": "string" }, "chain": { "type": "string" }, "payment": { "$ref": "#/components/schemas/Payment" } }, "required": ["chain", "event_timestamp", "event_type"] }, "OrderEvent": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "event_type": { "type": "string" }, "event_timestamp": { "type": "integer", "format": "int64" }, "transaction": { "type": "string" }, "order_hash": { "type": "string" }, "protocol_address": { "type": "string" }, "chain": { "type": "string" }, "payment": { "$ref": "#/components/schemas/Payment" }, "order_type": { "type": "string" }, "start_date": { "type": "integer", "format": "int64" }, "expiration_date": { "type": "integer", "format": "int64" }, "asset": { "$ref": "#/components/schemas/Nft" }, "quantity": { "type": "integer", "format": "int64" }, "maker": { "type": "string" }, "taker": { "type": "string" }, "criteria": { "$ref": "#/components/schemas/Criteria" }, "is_private_listing": { "type": "boolean" } } } ], "required": [ "chain", "event_timestamp", "event_type", "is_private_listing", "maker", "order_type", "quantity" ] }, "Payment": { "type": "object", "properties": { "quantity": { "type": "string" }, "token_address": { "type": "string" }, "decimals": { "type": "integer", "format": "int32" }, "symbol": { "type": "string" } }, "required": ["decimals", "quantity", "symbol", "token_address"] }, "SaleEvent": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "event_type": { "type": "string" }, "event_timestamp": { "type": "integer", "format": "int64" }, "transaction": { "type": "string" }, "order_hash": { "type": "string" }, "protocol_address": { "type": "string" }, "chain": { "type": "string" }, "payment": { "$ref": "#/components/schemas/Payment" }, "closing_date": { "type": "integer", "format": "int64" }, "seller": { "type": "string" }, "buyer": { "type": "string" }, "quantity": { "type": "integer", "format": "int64" }, "nft": { "$ref": "#/components/schemas/Nft" } } } ], "required": [ "buyer", "chain", "closing_date", "event_timestamp", "event_type", "quantity", "seller" ] }, "TransferEvent": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "event_type": { "type": "string" }, "event_timestamp": { "type": "integer", "format": "int64" }, "transaction": { "type": "string" }, "order_hash": { "type": "string" }, "protocol_address": { "type": "string" }, "chain": { "type": "string" }, "payment": { "$ref": "#/components/schemas/Payment" }, "transfer_type": { "type": "string" }, "from_address": { "type": "string" }, "to_address": { "type": "string" }, "nft": { "$ref": "#/components/schemas/Nft" }, "quantity": { "type": "integer", "format": "int64" } } } ], "required": [ "chain", "event_timestamp", "event_type", "from_address", "quantity", "to_address", "transfer_type" ] }, "DropPaginatedResponse": { "type": "object", "description": "Paginated list of drops", "properties": { "drops": { "type": "array", "description": "List of drops", "items": { "$ref": "#/components/schemas/DropResponse" } }, "next": { "type": "string", "description": "Cursor for the next page. May be present even when drops is empty if all items in the page were filtered by visibility rules; continue paginating until next is null." } }, "required": ["drops"] }, "DropResponse": { "type": "object", "description": "Summary of an NFT drop", "properties": { "collection_slug": { "type": "string", "description": "Collection slug", "example": "cool-cats" }, "collection_name": { "type": "string", "description": "Collection name", "example": "Cool Cats" }, "chain": { "type": "string", "description": "Blockchain the drop is on", "example": "ethereum" }, "contract_address": { "type": "string", "description": "Contract address" }, "drop_type": { "type": "string", "description": "Drop type", "example": "seadrop_v1_erc721" }, "is_minting": { "type": "boolean", "description": "Whether the drop is currently minting" }, "image_url": { "type": "string", "description": "Collection image URL" }, "opensea_url": { "type": "string", "description": "OpenSea URL for the drop" }, "active_stage": { "$ref": "#/components/schemas/DropStageResponse", "description": "The currently-minting stage, if the drop is live. Null if not minting." }, "next_stage": { "$ref": "#/components/schemas/DropStageResponse", "description": "The earliest upcoming stage by start_time when the drop is not currently minting (e.g. before it starts or between stages). Null if the drop is live or has no future stages." } }, "required": [ "chain", "collection_slug", "contract_address", "drop_type", "is_minting", "opensea_url" ] }, "DropStageResponse": { "type": "object", "description": "A mint stage within a drop", "properties": { "uuid": { "type": "string", "description": "Stage UUID" }, "stage_type": { "type": "string", "description": "Stage type", "example": "public_sale" }, "label": { "type": "string", "description": "Stage label/name" }, "price": { "type": "string", "description": "Mint price per token in wei (decimal string)" }, "price_currency_address": { "type": "string", "description": "Currency contract address (e.g. 0x0000...0000 for native token)" }, "start_time": { "type": "string", "description": "Stage start time (ISO 8601)" }, "end_time": { "type": "string", "description": "Stage end time (ISO 8601)" }, "max_per_wallet": { "type": "string", "description": "Max tokens mintable per wallet in this stage" } }, "required": [ "end_time", "max_per_wallet", "price_currency_address", "stage_type", "start_time", "uuid" ] }, "DropDetailedResponse": { "type": "object", "description": "Detailed drop information including stages and supply", "properties": { "collection_slug": { "type": "string", "description": "Collection slug", "example": "cool-cats" }, "collection_name": { "type": "string", "description": "Collection name", "example": "Cool Cats" }, "chain": { "type": "string", "description": "Blockchain the drop is on", "example": "ethereum" }, "contract_address": { "type": "string", "description": "Contract address" }, "drop_type": { "type": "string", "description": "Drop type", "example": "seadrop_v1_erc721" }, "is_minting": { "type": "boolean", "description": "Whether the drop is currently minting" }, "image_url": { "type": "string", "description": "Collection image URL" }, "opensea_url": { "type": "string", "description": "OpenSea URL for the drop" }, "active_stage": { "$ref": "#/components/schemas/DropStageResponse", "description": "The currently-minting stage, if the drop is live. Null if not minting." }, "next_stage": { "$ref": "#/components/schemas/DropStageResponse", "description": "The earliest upcoming stage by start_time when the drop is not currently minting (e.g. before it starts or between stages). Null if the drop is live or has no future stages." }, "stages": { "type": "array", "description": "Drop stages (public sale, presale, etc.)", "items": { "$ref": "#/components/schemas/DropStageResponse" } }, "total_supply": { "type": "string", "description": "Total minted supply" }, "max_supply": { "type": "string", "description": "Maximum supply" } }, "required": [ "chain", "collection_slug", "contract_address", "drop_type", "is_minting", "opensea_url", "stages" ] }, "DropDeployReceiptResponse": { "type": "object", "description": "Deploy contract receipt status", "properties": { "status": { "type": "string", "description": "Deployment status: pending, success, or failed", "example": "success" }, "contract_address": { "type": "string", "description": "Deployed contract address (only present on success)" }, "chain": { "type": "string", "description": "Chain slug (only present on success)" }, "collection_slug": { "type": "string", "description": "Linked collection slug (only present on success, may take time to materialize)" } }, "required": ["status"] }, "CollectionPaginatedResponse": { "type": "object", "properties": { "collections": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionResponse" } }, "next": { "type": "string" } }, "required": ["collections"] }, "CollectionDetailedResponse": { "type": "object", "properties": { "collection": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "image_url": { "type": "string" }, "banner_image_url": { "type": "string" }, "owner": { "type": "string" }, "safelist_status": { "type": "string" }, "category": { "type": "string" }, "is_disabled": { "type": "boolean" }, "is_nsfw": { "type": "boolean" }, "trait_offers_enabled": { "type": "boolean" }, "collection_offers_enabled": { "type": "boolean" }, "opensea_url": { "type": "string" }, "project_url": { "type": "string" }, "wiki_url": { "type": "string" }, "discord_url": { "type": "string" }, "telegram_url": { "type": "string" }, "twitter_username": { "type": "string" }, "instagram_username": { "type": "string" }, "contracts": { "type": "array", "items": { "$ref": "#/components/schemas/Contract" } }, "editors": { "type": "array", "items": { "type": "string" } }, "fees": { "type": "array", "items": { "$ref": "#/components/schemas/Fee" } }, "required_zone": { "type": "string" }, "rarity": { "$ref": "#/components/schemas/CollectionRarity" }, "total_supply": { "type": "integer", "format": "int64" }, "unique_item_count": { "type": "integer", "format": "int64" }, "created_date": { "type": "string", "format": "date-time" }, "pricing_currencies": { "$ref": "#/components/schemas/PricingCurrencies" } }, "required": [ "collection", "collection_offers_enabled", "contracts", "created_date", "editors", "fees", "is_disabled", "is_nsfw", "name", "opensea_url", "pricing_currencies", "safelist_status", "total_supply", "trait_offers_enabled", "unique_item_count" ] }, "CollectionRarity": { "type": "object", "properties": { "calculated_at": { "type": "string" }, "max_rank": { "type": "integer", "format": "int32" }, "total_supply": { "type": "integer", "format": "int64" }, "strategy_id": { "type": "string" }, "strategy_version": { "type": "string" } }, "required": [ "calculated_at", "max_rank", "strategy_id", "strategy_version", "total_supply" ] }, "Fee": { "type": "object", "properties": { "fee": { "type": "number", "format": "double" }, "recipient": { "type": "string" }, "required": { "type": "boolean" } }, "required": ["fee", "recipient", "required"] }, "PaymentToken": { "type": "object", "properties": { "symbol": { "type": "string" }, "address": { "type": "string" }, "chain": { "type": "string" }, "image": { "type": "string" }, "name": { "type": "string" }, "decimals": { "type": "integer", "format": "int32" }, "eth_price": { "type": "string" }, "usd_price": { "type": "string" } }, "required": [ "address", "chain", "decimals", "eth_price", "image", "name", "symbol", "usd_price" ] }, "PricingCurrencies": { "type": "object", "properties": { "listing_currency": { "$ref": "#/components/schemas/PaymentToken" }, "offer_currency": { "$ref": "#/components/schemas/PaymentToken" } }, "required": ["listing_currency", "offer_currency"] }, "CollectionStatsResponse": { "type": "object", "properties": { "total": { "$ref": "#/components/schemas/Total" }, "intervals": { "type": "array", "items": { "$ref": "#/components/schemas/IntervalStat" } } }, "required": ["intervals", "total"] }, "IntervalStat": { "type": "object", "properties": { "interval": { "type": "string" }, "volume": { "type": "number", "format": "double" }, "sales": { "type": "integer", "format": "int32" } }, "required": ["interval", "sales", "volume"] }, "Total": { "type": "object", "properties": { "volume": { "type": "number", "format": "double" }, "sales": { "type": "integer", "format": "int32" }, "num_owners": { "type": "integer", "format": "int64" }, "floor_price": { "type": "number", "format": "double" }, "floor_price_symbol": { "type": "string" } }, "required": [ "floor_price", "floor_price_symbol", "num_owners", "sales", "volume" ] }, "BidderResponse": { "type": "object", "description": "A bidder in an offer aggregate", "properties": { "address": { "type": "string", "description": "Wallet address of the bidder" }, "quantity": { "type": "integer", "format": "int32", "description": "Number of offers from this bidder" } }, "required": ["address", "quantity"] }, "CollectionOfferAggregateResponse": { "type": "object", "description": "An aggregated offer bucket", "properties": { "offer_price": { "$ref": "#/components/schemas/OfferAggregatePriceResponse", "description": "Offer price level" }, "total_value": { "$ref": "#/components/schemas/OfferAggregatePriceResponse", "description": "Total value of offers at this level" }, "total_offers": { "type": "integer", "format": "int32", "description": "Total number of offers at this level" }, "bidders": { "type": "array", "description": "Bidders at this price level", "items": { "$ref": "#/components/schemas/BidderResponse" } } }, "required": ["bidders", "offer_price", "total_offers", "total_value"] }, "CollectionOfferAggregatesPaginatedResponse": { "type": "object", "description": "Paginated list of collection offer aggregates", "properties": { "offer_aggregates": { "type": "array", "description": "List of offer aggregates", "items": { "$ref": "#/components/schemas/CollectionOfferAggregateResponse" } }, "next": { "type": "string", "description": "Cursor for the next page of results" } }, "required": ["offer_aggregates"] }, "OfferAggregatePriceResponse": { "type": "object", "description": "Price information for an offer aggregate", "properties": { "usd_price": { "type": "string", "description": "Price in USD" }, "token_unit": { "type": "number", "format": "double", "description": "Price in token units" }, "symbol": { "type": "string", "description": "Payment token symbol" }, "chain": { "type": "string", "description": "Blockchain chain" } }, "required": ["chain", "token_unit", "usd_price"] }, "CollectionHolderResponse": { "type": "object", "description": "A collection holder", "properties": { "address": { "type": "string", "description": "Wallet address of the holder" }, "quantity": { "type": "integer", "format": "int32", "description": "Number of items held" }, "percentage": { "type": "number", "format": "float", "description": "Ownership percentage of the collection" } }, "required": ["address", "percentage", "quantity"] }, "CollectionHoldersPaginatedResponse": { "type": "object", "description": "Paginated list of collection holders", "properties": { "holders": { "type": "array", "description": "List of holders", "items": { "$ref": "#/components/schemas/CollectionHolderResponse" } }, "next": { "type": "string", "description": "Cursor for the next page of results" } }, "required": ["holders"] }, "FloorPriceHistoryResponse": { "type": "object", "description": "Floor price history for a collection", "properties": { "floor_prices": { "type": "array", "description": "List of floor price data points", "items": { "$ref": "#/components/schemas/FloorPricePointResponse" } } }, "required": ["floor_prices"] }, "FloorPricePointResponse": { "type": "object", "description": "A floor price data point", "properties": { "time": { "type": "string", "format": "date-time", "description": "Timestamp of the data point" }, "usd_price": { "type": "string", "description": "Floor price in USD" }, "token_unit": { "type": "number", "format": "double", "description": "Floor price in token units" }, "symbol": { "type": "string", "description": "Payment token symbol" }, "chain": { "type": "string", "description": "Blockchain chain" } }, "required": ["time"] }, "NftListResponse": { "type": "object", "properties": { "nfts": { "type": "array", "items": { "$ref": "#/components/schemas/Nft" } }, "next": { "type": "string" } }, "required": ["nfts"] }, "ChainListResponse": { "type": "object", "description": "List of supported blockchains", "properties": { "chains": { "type": "array", "description": "List of supported chains", "items": { "$ref": "#/components/schemas/ChainResponse" } } }, "required": ["chains"] }, "ChainResponse": { "type": "object", "description": "Information about a supported blockchain", "properties": { "chain": { "type": "string", "description": "The chain identifier slug used in API paths", "example": "ethereum" }, "name": { "type": "string", "description": "Human-readable chain name", "example": "Ethereum" }, "symbol": { "type": "string", "description": "Native currency symbol", "example": "ETH" }, "supports_swaps": { "type": "boolean", "description": "Whether token swaps are supported on this chain" }, "block_explorer": { "type": "string", "description": "Block explorer name", "example": "Etherscan" }, "block_explorer_url": { "type": "string", "description": "Block explorer base URL", "example": "https://etherscan.io" } }, "required": [ "block_explorer", "block_explorer_url", "chain", "name", "supports_swaps", "symbol" ] }, "PriceHistoryPointResponse": { "type": "object", "description": "A price history data point", "properties": { "time": { "type": "string", "format": "date-time", "description": "Timestamp of the price point" }, "usd_price": { "type": "string", "description": "Price in USD", "example": 1 } }, "required": ["time", "usd_price"] }, "PriceHistoryResponse": { "type": "object", "description": "List of price history data points", "properties": { "prices": { "type": "array", "description": "List of price history points", "items": { "$ref": "#/components/schemas/PriceHistoryPointResponse" } } }, "required": ["prices"] }, "OhlcvCandleResponse": { "type": "object", "description": "An OHLCV candle data point", "properties": { "time": { "type": "string", "format": "date-time", "description": "Candle timestamp" }, "open": { "type": "number", "description": "Opening price in USD" }, "high": { "type": "number", "description": "Highest price in USD" }, "low": { "type": "number", "description": "Lowest price in USD" }, "close": { "type": "number", "description": "Closing price in USD" }, "volume": { "type": "number", "description": "Trading volume in USD" } }, "required": ["close", "high", "low", "open", "time", "volume"] }, "OhlcvResponse": { "type": "object", "description": "List of OHLCV candle data points", "properties": { "candles": { "type": "array", "description": "List of OHLCV candles", "items": { "$ref": "#/components/schemas/OhlcvCandleResponse" } } }, "required": ["candles"] }, "TokenLiquidityPoolResponse": { "type": "object", "description": "A liquidity pool for a token", "properties": { "pool_type": { "type": "string", "description": "Pool protocol type (e.g. UNISWAP_V2, UNISWAP_V3)" }, "pool_identifier": { "type": "string", "description": "Unique identifier for the pool" }, "pool_address": { "type": "string", "description": "On-chain address of the pool contract" }, "base_token": { "type": "string", "description": "Base token contract identifier (chain/address)" }, "quote_token": { "type": "string", "description": "Quote token contract identifier (chain/address)" }, "base_reserve_usd": { "type": "number", "description": "USD value of base token reserves" }, "quote_reserve_usd": { "type": "number", "description": "USD value of quote token reserves" }, "total_reserve_usd": { "type": "number", "description": "Total USD value of reserves in the pool" }, "bonding_curve_progress": { "type": "number", "format": "float", "description": "Bonding curve progress percentage (0-100)" }, "is_graduated": { "type": "boolean", "description": "Whether the token has graduated from its bonding curve" } }, "required": [ "base_token", "pool_identifier", "pool_type", "quote_token" ] }, "TokenLiquidityPoolsResponse": { "type": "object", "description": "Paginated list of liquidity pools for a token", "properties": { "pools": { "type": "array", "description": "List of liquidity pools", "items": { "$ref": "#/components/schemas/TokenLiquidityPoolResponse" } }, "next": { "type": "string", "description": "Cursor for the next page of results" } }, "required": ["pools"] }, "TokenHolderDistributionResponse": { "type": "object", "description": "Holder distribution health metrics for a token", "properties": { "total_holders": { "type": "integer", "format": "int32", "description": "Total number of holders with a non-zero balance" }, "top_one_percent_concentration": { "type": "number", "format": "float", "description": "Percentage of total supply held by the top 1% of holders (0-100)" }, "health_score": { "type": "integer", "format": "int32", "description": "Health score from 0-100 (higher = more distributed)" }, "health_label": { "type": "string", "description": "Human-readable label for the health score", "enum": ["STRONG", "HEALTHY", "CONCERNING", "BAD"] } }, "required": [ "health_label", "health_score", "top_one_percent_concentration", "total_holders" ] }, "TokenHolderResponse": { "type": "object", "description": "A holder of a token", "properties": { "quantity": { "type": "number", "description": "Token quantity in display units" }, "percentage_held": { "type": "number", "format": "float", "description": "Percentage of total supply held by this address" }, "usd_value": { "type": "number", "description": "USD value of the holding" }, "owner_address": { "type": "string", "description": "Wallet address of the holder" }, "owner_display_name": { "type": "string", "description": "Display name of the holder" } }, "required": ["owner_address", "quantity"] }, "TokenHoldersResponse": { "type": "object", "description": "Paginated list of token holders", "properties": { "holders": { "type": "array", "description": "List of token holders", "items": { "$ref": "#/components/schemas/TokenHolderResponse" } }, "total_count": { "type": "integer", "format": "int32", "description": "Total number of holders" }, "distribution": { "$ref": "#/components/schemas/TokenHolderDistributionResponse", "description": "Holder distribution health metrics" }, "next": { "type": "string", "description": "Cursor for the next page of results" } }, "required": ["holders"] }, "TokenAmountResponse": { "type": "object", "description": "Token amount with contract and value information", "properties": { "address": { "type": "string", "description": "Contract address of the token" }, "chain": { "type": "string", "description": "Blockchain the token is on" }, "amount_token": { "type": "number", "format": "double", "description": "Amount in token units" }, "amount_usd": { "type": "string", "description": "Amount in USD" }, "amount_native": { "type": "number", "format": "double", "description": "Amount in chain-native units" } }, "required": [ "address", "amount_native", "amount_token", "amount_usd", "chain" ] }, "TokenSwapActivityPaginatedResponse": { "type": "object", "description": "Paginated list of token swap activity events", "properties": { "swap_events": { "type": "array", "description": "List of swap activity events", "items": { "$ref": "#/components/schemas/TokenSwapActivityResponse" } }, "next": { "type": "string", "description": "Cursor for the next page of results" } }, "required": ["swap_events"] }, "TokenSwapActivityResponse": { "type": "object", "description": "A token swap activity event", "properties": { "id": { "type": "string", "description": "Unique identifier for the swap event" }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp of the swap" }, "sender_address": { "type": "string", "description": "Address of the sender" }, "from_token": { "$ref": "#/components/schemas/TokenAmountResponse", "description": "Token sold in the swap" }, "to_token": { "$ref": "#/components/schemas/TokenAmountResponse", "description": "Token bought in the swap" }, "transaction_hash": { "type": "string", "description": "Transaction hash" }, "user_op_hash": { "type": "string", "description": "User operation hash (for account abstraction)" }, "swap_protocol": { "type": "string", "description": "Swap protocol used" }, "chain": { "type": "string", "description": "Blockchain the swap occurred on" } }, "required": [ "chain", "from_token", "id", "sender_address", "timestamp", "to_token", "transaction_hash" ] }, "ContractResponse": { "type": "object", "properties": { "address": { "type": "string" }, "chain": { "type": "string" }, "collection": { "type": "string" }, "contract_standard": { "type": "string" }, "name": { "type": "string" } }, "required": [ "address", "chain", "collection", "contract_standard", "name" ] }, "NftResponse": { "type": "object", "properties": { "nft": { "$ref": "#/components/schemas/NftDetailed" } }, "required": ["nft"] }, "OwnersPaginatedResponse": { "type": "object", "properties": { "owners": { "type": "array", "items": { "$ref": "#/components/schemas/Owner" } }, "next": { "type": "string" } }, "required": ["owners"] }, "NftAnalyticsResponse": { "type": "object", "description": "Analytics data for an NFT including sales and floor price history", "properties": { "sales": { "type": "array", "description": "List of sale data points", "items": { "$ref": "#/components/schemas/NftSalePointResponse" } }, "floor_prices": { "type": "array", "description": "List of floor price data points", "items": { "$ref": "#/components/schemas/FloorPricePointResponse" } } }, "required": ["floor_prices", "sales"] }, "NftSalePointResponse": { "type": "object", "description": "A sale data point for an NFT", "properties": { "time": { "type": "string", "format": "date-time", "description": "Timestamp of the sale" }, "usd_price": { "type": "string", "description": "Sale price in USD" }, "token_unit": { "type": "number", "format": "double", "description": "Sale price in token units" }, "symbol": { "type": "string", "description": "Payment token symbol" }, "chain": { "type": "string", "description": "Blockchain chain" } }, "required": ["chain", "time", "token_unit", "usd_price"] }, "AccountResponse": { "type": "object", "properties": { "address": { "type": "string" }, "username": { "type": "string" }, "profile_image_url": { "type": "string" }, "banner_image_url": { "type": "string" }, "website": { "type": "string" }, "social_media_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/SocialMediaAccount" } }, "bio": { "type": "string" }, "joined_date": { "type": "string", "format": "date-time" } }, "required": ["address", "bio", "joined_date", "social_media_accounts"] }, "SocialMediaAccount": { "type": "object", "properties": { "platform": { "type": "string" }, "username": { "type": "string" } }, "required": ["platform", "username"] }, "AccountResolveResponse": { "type": "object", "description": "Resolved account info", "properties": { "address": { "type": "string", "description": "The resolved wallet address", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }, "username": { "type": "string", "description": "OpenSea username, if available" }, "ens_name": { "type": "string", "description": "Primary ENS name, if available", "example": "vitalik.eth" } }, "required": ["address"] }, "TokenBalancePaginatedResponse": { "type": "object", "description": "Paginated list of token balances", "properties": { "token_balances": { "type": "array", "description": "List of token balances", "items": { "$ref": "#/components/schemas/TokenBalanceResponse" } }, "next": { "type": "string", "description": "Cursor for the next page of results" } }, "required": ["token_balances"] }, "TokenBalanceResponse": { "type": "object", "description": "Token balance for a wallet address", "properties": { "address": { "type": "string", "description": "The contract address of the token", "example": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }, "chain": { "type": "string", "description": "The blockchain the token is on", "example": "ethereum" }, "name": { "type": "string", "description": "The display name of the token", "example": "USD Coin" }, "symbol": { "type": "string", "description": "The ticker symbol of the token", "example": "USDC" }, "image_url": { "type": "string", "description": "URL of the token's image" }, "usd_price": { "type": "string", "description": "Current price in USD", "example": 1 }, "decimals": { "type": "integer", "format": "int32", "description": "Number of decimal places", "example": 6 }, "opensea_url": { "type": "string", "description": "URL to the token page on OpenSea" }, "quantity": { "type": "string", "description": "Token balance in display units (divided by 10^decimals), not raw/wei", "example": 1.5 }, "usd_value": { "type": "string", "description": "Total USD value of the balance (quantity * usd_price)", "example": 3518.51835185 }, "status": { "type": "string", "default": "OK", "description": "Token status relative to OpenSea's spam-classification rules. `OK` for tokens that pass all spam filters (the normal case); populated with a more specific value for tokens surfaced via `disable_spam_filtering=true` that would normally be hidden. Categories are intentionally broad and may evolve. Possible values, in decreasing severity: `WARNING` (flagged as risky/suspicious — caution advised), `SPAM` (flagged as spam), `LOW_LIQUIDITY` (insufficient pool liquidity), `LOW_VALUE` (dust holding < $0.01), `OK` (passes all filters).", "enum": ["OK", "WARNING", "SPAM", "LOW_LIQUIDITY", "LOW_VALUE"] }, "base_token_liquidity_usd": { "type": "string", "description": "USD value of base token reserves in the top liquidity pool paired with a curated quote token", "example": 125000.5 }, "quote_token_liquidity_usd": { "type": "string", "description": "USD value of quote token reserves in the top liquidity pool paired with a curated quote token", "example": 125000.5 } }, "required": [ "address", "chain", "decimals", "name", "opensea_url", "quantity", "symbol", "usd_price", "usd_value" ] }, "PortfolioStatsResponse": { "type": "object", "description": "Portfolio stats including total value, P&L, and asset breakdown", "properties": { "total_value_usd": { "type": "string", "description": "Total portfolio value in USD", "example": 125430.5 }, "nft_value_usd": { "type": "string", "description": "NFT portfolio value in USD", "example": 98200 }, "token_value_usd": { "type": "string", "description": "Token portfolio value in USD", "example": 27230.5 }, "pnl_absolute": { "type": "string", "description": "Absolute P&L in USD over the timeframe", "example": "+1250.00" }, "pnl_percentage": { "type": "string", "description": "Percentage P&L over the timeframe", "example": "+1.01" }, "timeframe": { "type": "string", "description": "The queried timeframe", "example": "WEEK" } }, "required": [ "nft_value_usd", "timeframe", "token_value_usd", "total_value_usd" ] }, "PortfolioHistoryDataPoint": { "type": "object", "description": "A single net worth data point", "properties": { "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp of the data point", "example": "2026-04-28T00:00:00Z" }, "value_usd": { "type": "string", "description": "Total portfolio value in USD", "example": 124180 }, "token_value_usd": { "type": "string", "description": "Token value in USD", "example": 26000 }, "nft_value_usd": { "type": "string", "description": "NFT value in USD", "example": 98180 } }, "required": [ "nft_value_usd", "timestamp", "token_value_usd", "value_usd" ] }, "PortfolioHistoryResponse": { "type": "object", "description": "Net worth time series data", "properties": { "data_points": { "type": "array", "description": "Time series data points", "items": { "$ref": "#/components/schemas/PortfolioHistoryDataPoint" } }, "timeframe": { "type": "string", "description": "The queried timeframe", "example": "WEEK" } }, "required": ["data_points", "timeframe"] }, "ProfileCollectionResponse": { "type": "object", "properties": { "collection": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "image_url": { "type": "string" }, "banner_image_url": { "type": "string" }, "owner": { "type": "string" }, "safelist_status": { "type": "string" }, "category": { "type": "string" }, "is_disabled": { "type": "boolean" }, "is_nsfw": { "type": "boolean" }, "trait_offers_enabled": { "type": "boolean" }, "collection_offers_enabled": { "type": "boolean" }, "opensea_url": { "type": "string" }, "project_url": { "type": "string" }, "wiki_url": { "type": "string" }, "discord_url": { "type": "string" }, "telegram_url": { "type": "string" }, "twitter_username": { "type": "string" }, "instagram_username": { "type": "string" }, "contracts": { "type": "array", "items": { "$ref": "#/components/schemas/Contract" } }, "item_count": { "type": "integer", "format": "int32" }, "total_quantity": { "type": "integer", "format": "int32" }, "usd_value": { "type": "number", "format": "double" } }, "required": [ "collection", "collection_offers_enabled", "contracts", "is_disabled", "is_nsfw", "item_count", "name", "opensea_url", "safelist_status", "total_quantity", "trait_offers_enabled" ] }, "ProfileCollectionsResponse": { "type": "object", "properties": { "collections": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileCollectionResponse" } }, "next": { "type": "string" } }, "required": ["collections"] } }, "responses": { "BadRequest": { "description": "For error reasons, review the response data." }, "Unauthorized": { "description": "Invalid or missing API key" }, "NotFound": { "description": "Resource not found" }, "RateLimit": { "description": "Rate limit exceeded" }, "InternalError": { "description": "Internal server error. Please open a support ticket so OpenSea can investigate." } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests per rate limit window", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "Unix epoch timestamp when the rate limit window resets", "schema": { "type": "integer", "format": "int32" } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "description": "API key required for authentication", "name": "x-api-key", "in": "header" } } }, "x-tagGroups": [ { "name": "Data & Discovery", "tags": [ "Chain Endpoints", "Account Endpoints", "Collection Endpoints", "NFT Endpoints", "Contract Endpoints", "Token Endpoints", "Search Endpoints" ] }, { "name": "Marketplace & Trading", "tags": [ "Listing Endpoints", "Offer Endpoints", "Order Endpoints", "Swap Endpoints", "Drops Endpoints" ] }, { "name": "Analytics & Events", "tags": ["Analytics Endpoints"] }, { "name": "Tools [Beta]", "tags": ["Tool Endpoints [Beta]"] }, { "name": "Transactions", "tags": ["Transaction Endpoints"] } ] }