{ "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": "OpenSea API 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" }, { "name": "Auth Endpoints", "description": "Authentication endpoints for obtaining an API key and for exchanging a scoped token for a short-lived wallet access token" } ], "paths": { "/api/v2/drops/{slug}/items/{token_id}": { "put": { "tags": ["Drops Endpoints"], "summary": "Build transaction data for updating a SelfMint drop item", "description": "Returns ready-to-sign onchain transaction data for updating a SelfMint drop item. The caller is responsible for signing and broadcasting the transaction.", "operationId": "update_self_mint_drop_item", "parameters": [ { "name": "slug", "in": "path", "description": "Collection slug", "required": true, "schema": { "type": "string" }, "example": "cool-cats" }, { "name": "token_id", "in": "path", "description": "Drop item token id", "required": true, "schema": { "type": "string" }, "example": 123 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSelfMintDropItemRequest" } } }, "required": true }, "responses": { "200": { "description": "Ready-to-sign transaction data", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SelfMintDropItemResponse" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/V1ErrorWrapper" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SelfMintDropItemResponse" } } } }, "404": { "description": "Not Found", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/V1ErrorWrapper" } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:drops"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:drops"] }, "patch": { "tags": ["Drops Endpoints"], "summary": "Update drop item", "description": "Update drop item metadata.", "operationId": "update_drop_item", "parameters": [ { "name": "slug", "in": "path", "description": "Collection slug", "required": true, "schema": { "type": "string" }, "example": "cool-cats" }, { "name": "token_id", "in": "path", "description": "Drop item token id", "required": true, "schema": { "type": "string" }, "example": 123 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDropItemRequest" } } }, "required": true }, "responses": { "200": { "description": "Drop item updated successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/DropItemResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/DropItemResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:drops"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:drops"] } }, "/api/v2/accounts/wallets/{wallet}/private": { "put": { "tags": ["Account Endpoints"], "summary": "Make a registered wallet private", "description": "Hides the wallet's public account linkage, including agent ownership relationships.", "operationId": "make_wallet_private", "parameters": [ { "name": "wallet", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletVisibilityResponse" } } } } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:wallets"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:wallets"] }, "delete": { "tags": ["Account Endpoints"], "summary": "Make a registered wallet public", "description": "Allows the wallet's public account linkage, including eligible agent ownership relationships.", "operationId": "make_wallet_public", "parameters": [ { "name": "wallet", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletVisibilityResponse" } } } } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:wallets"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:wallets"] } }, "/api/v2/accounts/agent": { "put": { "tags": ["Account Endpoints"], "summary": "Declare the authenticated account an agent", "description": "Self-reported and not OpenSea verification. Independent of ownership: an agent nobody owns is valid.", "operationId": "declare_agent_account", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAccountStatusResponse" } } } } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:wallets"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:wallets"] }, "delete": { "tags": ["Account Endpoints"], "summary": "Withdraw the authenticated account's agent declaration", "operationId": "withdraw_agent_account_declaration", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAccountStatusResponse" } } } } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:wallets"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:wallets"] } }, "/api/v2/watchlist": { "post": { "tags": ["Account Endpoints"], "summary": "Add a watchlist entry", "description": "Add an NFT, token, collection, or perpetual to the authenticated account's watchlist.", "operationId": "add_watchlist_entry", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchlistRequest" } } }, "required": true }, "responses": { "200": { "description": "Watchlist entry added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FavoriteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:favorites"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:favorites"] }, "delete": { "tags": ["Account Endpoints"], "summary": "Remove a watchlist entry", "description": "Remove an NFT, token, collection, or perpetual from the authenticated account's watchlist.", "operationId": "remove_watchlist_entry", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchlistRequest" } } }, "required": true }, "responses": { "200": { "description": "Watchlist entry removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FavoriteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:favorites"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:favorites"] } }, "/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). Identify the tool by providing tool_chain_id + tool_registry_address (an onchain EVM address, or x402_bazaar / x402_bankr for x402 tools) + tool_onchain_id, or alternatively just tool_endpoint (the tool's canonical URL). 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/saved-tools": { "get": { "tags": ["Tool Endpoints [Beta]"], "summary": "[Beta] List saved tools", "description": "List tools saved by the authenticated account.", "operationId": "list_saved_tools", "parameters": [ { "name": "toolkit_name", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 255, "minLength": 0, "pattern": "(?s).*\\S.*" } }, { "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", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Saved tools returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedToolsPaginatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["read:tools"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["read:tools"] }, "post": { "tags": ["Tool Endpoints [Beta]"], "summary": "[Beta] Save a tool", "description": "Save a registered tool for the authenticated account.", "operationId": "save_tool", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedToolRequest" } } }, "required": true }, "responses": { "200": { "description": "Tool saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedToolResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:tools"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:tools"] }, "delete": { "tags": ["Tool Endpoints [Beta]"], "summary": "[Beta] Remove a saved tool", "description": "Idempotently remove a registered tool from the authenticated account's saved tools. Removed is false when the tool was already absent.", "operationId": "unsave_tool", "parameters": [ { "name": "tool_id", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "registry_chain", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "registry_addr", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "toolkit_name", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 255, "minLength": 0, "pattern": "(?s).*\\S.*" } } ], "responses": { "200": { "description": "Saved-tool removal result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedToolActionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:tools"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:tools"] } }, "/api/v2/profile/username": { "post": { "tags": ["Account Endpoints"], "summary": "Claim a profile username", "description": "Claim a username for the authenticated wallet.", "operationId": "claim_profile_username", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimAccountUsernameRequest" } } }, "required": true }, "responses": { "200": { "description": "Username claimed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimAccountUsernameResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:profile"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:profile"] } }, "/api/v2/profile/shelves": { "get": { "tags": ["Account Endpoints"], "summary": "Get profile shelves", "description": "Get the shelves for a public wallet address.", "operationId": "get_profile_shelves", "parameters": [ { "name": "address", "in": "query", "description": "Wallet address to retrieve shelves for", "required": true, "schema": { "type": "string" }, "example": "0x8ba1f109551bd432803012645ac136c94c19d6e" } ], "responses": { "200": { "description": "Shelves retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileShelfResponse" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyAuth": [] }, { "ApiKeyAuth": [], "WalletAuth": [] } ], "x-opensea-auth-required": false, "x-opensea-auth-scopes": [] }, "post": { "tags": ["Account Endpoints"], "summary": "Create a profile shelf", "description": "Create a shelf for the authenticated wallet.", "operationId": "create_profile_shelf", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProfileShelfRequest" } } }, "required": true }, "responses": { "200": { "description": "Shelf created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileShelfResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:profile"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:profile"] }, "patch": { "tags": ["Account Endpoints"], "summary": "Reorder profile shelves", "description": "Reorder the authenticated wallet's shelves.", "operationId": "reorder_profile_shelves", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderProfileShelvesRequest" } } }, "required": true }, "responses": { "200": { "description": "Shelves reordered successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileShelfActionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:profile"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:profile"] } }, "/api/v2/profile/nft-pfp": { "post": { "tags": ["Account Endpoints"], "summary": "Set NFT profile picture", "description": "Set an onchain NFT owned by the authenticated wallet as its verified profile picture. The NFT must be from a verified collection and owned by one of the account's wallets.", "operationId": "set_profile_nft_pfp", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetNftPfpRequest" } } }, "required": true }, "responses": { "200": { "description": "NFT profile picture set successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NftPfpResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:profile"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:profile"] }, "delete": { "tags": ["Account Endpoints"], "summary": "Clear NFT profile picture", "description": "Clear the authenticated wallet's NFT profile picture. This operation is idempotent: it returns 200 with `success=false` when no NFT profile picture was set, and `success=true` when one was cleared.", "operationId": "clear_profile_nft_pfp", "responses": { "200": { "description": "NFT profile picture cleared", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClearNftPfpResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:profile"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:profile"] } }, "/api/v2/profile/images": { "post": { "tags": ["Account Endpoints"], "summary": "Upload a profile image", "description": "Set contentType in the context request to the exact MIME type of the image bytes. This response starts a three-step upload flow. First, request this context from OpenSea. Second, call the returned method at the returned URL. For POST, add every fields entry unchanged as a multipart text field, then add a file part containing the bytes. The file part must be last. Let the HTTP library generate the multipart boundary; do not set the overall multipart Content-Type header yourself. POST storage uploads normally return 204. For PUT, upload the raw bytes, use only headers explicitly required by the endpoint, and expect 200. Treat any 2xx storage response as success. The URL and fields are short-lived sensitive credentials. Do not log, persist, alter, or put them in tickets. Third, after storage succeeds, pass the returned token to the documented OpenSea API endpoint. Do not use the token before the storage upload succeeds. Pass the token as the matching profile image field in PATCH /api/v2/profile.", "operationId": "upload_profile_image", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadProfileImageRequest" } } }, "required": true }, "responses": { "200": { "description": "Upload context returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadContext" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:profile"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:profile"] } }, "/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", "description": "The blockchain on which to filter the results", "required": true, "schema": { "$ref": "#/components/schemas/ChainIdentifier" }, "example": "ethereum" }, { "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", "description": "The blockchain on which to filter the results", "required": true, "schema": { "$ref": "#/components/schemas/ChainIdentifier" }, "example": "ethereum" }, { "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", "description": "The blockchain on which to filter the results", "required": true, "schema": { "$ref": "#/components/schemas/ChainIdentifier" }, "example": "ethereum" }, { "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" } }, "security": [ { "ApiKeyAuth": [] }, { "ApiKeyAuth": [], "WalletAuth": ["write:orders"] } ], "x-opensea-auth-required": false, "x-opensea-auth-scopes": ["write:orders"] } }, "/api/v2/orders/chain/{chain}/protocol/{protocol_address}/{order_hash}/cancel/actions": { "post": { "tags": ["Order Endpoints"], "summary": "Get order cancellation actions", "description": "Returns the blockchain actions needed to cancel an order onchain, for orders that cannot be cancelled offchain through the cancel endpoint. A Solana order is always cancelled this way, because it lives onchain from the moment it is created. The order is addressed by the same identifier the get-order endpoint uses, and only its maker may cancel it.", "operationId": "create_cancel_order_actions", "parameters": [ { "name": "chain", "in": "path", "description": "The blockchain on which to filter the results", "required": true, "schema": { "$ref": "#/components/schemas/ChainIdentifier" }, "example": "ethereum" }, { "name": "protocol_address", "in": "path", "description": "Protocol contract address", "required": true, "schema": { "type": "string" } }, { "name": "order_hash", "in": "path", "description": "Order identifier, as returned by the get-order endpoint: a Seaport order hash on EVM chains, and a creation signature paired with the order state account on Solana.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelOrderActionsRequest" } } }, "required": true }, "responses": { "200": { "description": "Cancellation actions retrieved successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CancelOrderActionsResponse" } } } }, "400": { "description": "The request is invalid. Possible reasons: order not found, invalid address, or the address is not the order's maker.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CancelOrderActionsResponse" } } } }, "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/fulfillment/actions": { "post": { "tags": ["Offer Endpoints"], "summary": "Get offer fulfillment actions", "description": "Returns the blockchain actions a seller needs to accept an offer, for offers that cannot be accepted with Seaport calldata. A Solana offer is always accepted this way, because it settles through an onchain program rather than a signed order. The offer is addressed by the same identifier the get-order endpoint uses, and a criteria offer additionally requires a consideration naming the token being sold.\n\nOn Solana two fields on the returned action are load-bearing. When `partially_signed_transaction` is present the transaction is already cosigned: append your signature to those exact bytes and broadcast them, and do not rebuild the message from `instructions`, which invalidates the cosigner signature. When `sponsored_fee_payer` is present an OpenSea relayer pays the fee and your wallet is only a co-signer; when it is absent you pay your own fee.\n\nAccepting fewer units than an offer's remaining quantity leaves the offer live, so a successful fill does not imply the offer is consumed.", "operationId": "create_offer_fulfillment_actions", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FullfillmentDataRequest" } } }, "required": true }, "responses": { "200": { "description": "Offer fulfillment actions retrieved successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/FulfillmentActionsResponse" } } } }, "400": { "description": "The request is invalid. Possible reasons: order not found, order not valid, order is not an offer, consideration missing for a criteria offer, or no actions could be composed.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/FulfillmentActionsResponse" } } } }, "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/offers/actions": { "post": { "tags": ["Offer Endpoints"], "summary": "Get offer creation actions", "description": "Returns the blockchain actions needed to offer on an NFT, the offer-side counterpart of the listing actions endpoint. On EVM chains these are payment approvals followed by a Seaport order to sign, which the signature endpoints then accept. On Solana the actions instead carry an unsigned bid transaction to sign and submit onchain; there is no order to post back to OpenSea afterwards.", "operationId": "create_offer_actions", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOfferActionsRequest" } } }, "required": true }, "responses": { "200": { "description": "Offer creation actions retrieved successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CreateOfferActionsResponse" } } } }, "400": { "description": "The request is invalid. Possible reasons: invalid addresses, item not found, invalid currency, or price/quantity not positive.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CreateOfferActionsResponse" } } } }, "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. Collections on EVM chains only; a collection on any other chain is rejected.", "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/fulfillment/actions": { "post": { "tags": ["Listing Endpoints"], "summary": "Get listing fulfillment actions", "description": "Returns the blockchain actions needed to fulfill a listing, for listings that cannot be fulfilled with Seaport calldata. A Solana listing is always fulfilled this way, because it settles through an onchain program rather than a signed order. The listing is addressed by the same identifier the get-order endpoint uses.", "operationId": "create_listing_fulfillment_actions", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FullfillListingRequest" } } }, "required": true }, "responses": { "200": { "description": "Listing fulfillment actions retrieved successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/FulfillmentActionsResponse" } } } }, "400": { "description": "The request is invalid. Possible reasons: order not found, order not valid, order is not a listing, or no actions could be composed.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/FulfillmentActionsResponse" } } } }, "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. Listings on EVM chains only; a listing on any other chain is rejected.", "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}": { "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" } } }, "post": { "tags": ["Drops Endpoints"], "summary": "Update Creator Studio drop edits", "description": "Update an existing ERC-721 SeaDrop V1 drop and its stages.\n\nSaves a Creator Studio draft. It does not change the live drop: SeaDrop stages are onchain contract state, so the draft has to be published separately before buyers see it. A 200 here means the draft was accepted, not that the drop changed.\n\n`stages` replaces the whole set rather than merging, so send every stage the drop should end up with, including ones you are not changing. Reuse an existing stage uuid to update it, supply a new UUID to add one, and omit a stage to delete it.\n\nThe stage list has four rules, and rules 2 and 4 interact in a way worth reading before the first attempt:\n\n1. Exactly one stage must be `public_sale`.\n2. That public stage must be first in the array.\n3. The presales, meaning every stage after the first, must be contiguous among themselves: each one starts exactly when the previous presale ended. The first presale start time is not constrained.\n4. The last presale must end exactly when the public stage starts.\n\nTogether, 2 and 4 mean array order is not chronological order: the public stage is listed first and runs last, with the presales running in array order before it. A drop with two allowlist stages therefore sends `[public, presale1, presale2]` while time runs presale1, then presale2, then public. Rule 3 does not tie presale1 back to the public stage, which is why the chain reads forward from presale1 rather than from the array head.\n\nPer-wallet mint limits are cumulative across stages, so `max_total_mintable_by_wallet` on a later stage is a running total for the wallet rather than a fresh allowance.", "operationId": "save_drop_edits", "parameters": [ { "name": "slug", "in": "path", "description": "The collection slug identifying the drop to update", "required": true, "schema": { "type": "string" }, "example": "cool-cats" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveDropEditsRequest" } } }, "required": true }, "responses": { "200": { "description": "Drop edits saved successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SaveDropResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SaveDropResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:drops"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:drops"] } }, "/api/v2/drops/{slug}/prereveal-item": { "post": { "tags": ["Drops Endpoints"], "summary": "Save prereveal drop item", "description": "Save prereveal drop item metadata.", "operationId": "save_prereveal_drop_item", "parameters": [ { "name": "slug", "in": "path", "description": "Collection slug", "required": true, "schema": { "type": "string" }, "example": "cool-cats" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavePrerevealDropItemRequest" } } }, "required": true }, "responses": { "200": { "description": "Prereveal drop item saved successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PrerevealDropItemResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PrerevealDropItemResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:drops"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:drops"] } }, "/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: insufficient native balance, wallet not in allowlist, mint limit exceeded, or supply exhausted", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/V1ErrorWrapper" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/drops/{slug}/items": { "post": { "tags": ["Drops Endpoints"], "summary": "Build transaction data for creating a SelfMint drop item", "description": "Returns ready-to-sign onchain transaction data for creating a SelfMint drop item. The caller is responsible for signing and broadcasting the transaction.", "operationId": "save_self_mint_drop_item", "parameters": [ { "name": "slug", "in": "path", "description": "Collection slug", "required": true, "schema": { "type": "string" }, "example": "cool-cats" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveSelfMintDropItemRequest" } } }, "required": true }, "responses": { "200": { "description": "Ready-to-sign transaction data", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SelfMintDropItemResponse" } } } }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/V1ErrorWrapper" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SelfMintDropItemResponse" } } } }, "404": { "description": "Not Found", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/V1ErrorWrapper" } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:drops"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:drops"] } }, "/api/v2/drops/{slug}/items/media": { "post": { "tags": ["Drops Endpoints"], "summary": "Upload drop item media", "description": "This response starts a three-step upload flow. First, request this context from OpenSea. Second, call the returned method at the returned URL. For POST, add every fields entry unchanged as a multipart text field, then add a file part containing the bytes. The file part must be last. Let the HTTP library generate the multipart boundary; do not set the overall multipart Content-Type header yourself. POST storage uploads normally return 204. For PUT, upload the raw bytes, use only headers explicitly required by the endpoint, and expect 200. Treat any 2xx storage response as success. The URL and fields are short-lived sensitive credentials. Do not log, persist, alter, or put them in tickets. Third, after storage succeeds, pass the returned token to the documented OpenSea API endpoint. Do not use the token before the storage upload succeeds. Pass each token as media_token to POST /api/v2/drops/{slug}/items or POST /api/v2/drops/{slug}/prereveal-item, as media_tokens to POST /api/v2/drops/{slug}/items/media/save, or as media_token to PUT /api/v2/drops/{slug}/items/{token_id}.", "operationId": "upload_drop_item_media", "parameters": [ { "name": "slug", "in": "path", "description": "Collection slug", "required": true, "schema": { "type": "string" }, "example": "cool-cats" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadDropItemMediaRequest" } } }, "required": true }, "responses": { "200": { "description": "Upload contexts generated successfully", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UploadContext" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UploadContext" } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:drops"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:drops"] } }, "/api/v2/drops/{slug}/items/media/save": { "post": { "tags": ["Drops Endpoints"], "summary": "Save drop item media", "description": "Persist drop item media references.", "operationId": "save_drop_item_media", "parameters": [ { "name": "slug", "in": "path", "description": "Collection slug", "required": true, "schema": { "type": "string" }, "example": "cool-cats" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveDropItemMediaRequest" } } }, "required": true }, "responses": { "200": { "description": "Drop item media saved successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SaveDropItemMediaResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SaveDropItemMediaResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:drops"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:drops"] } }, "/api/v2/drops/{slug}/cross_chain_mint": { "post": { "tags": ["Drops Endpoints"], "summary": "Build cross-chain mint transactions for a drop", "description": "Returns an ordered list of transactions for minting a drop using a token on another chain. The payer signs each transaction in order, and the minter receives the NFT. After submission, pass receipt_request to POST /api/v2/transactions/receipt and poll until the status is terminal.", "operationId": "build_cross_chain_drop_mint_transactions", "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/CrossChainDropMintRequest" } } }, "required": true }, "responses": { "200": { "description": "Ordered transactions required to complete the mint", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CrossChainDropMintResponse" } } } }, "400": { "description": "Invalid address, payment chain, payment token, quantity, or request body", "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", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/V1ErrorWrapper" } } } }, "422": { "description": "Minting precondition failed, including an ineligible wallet, exhausted supply, insufficient balance, or a payer that is not allowed for the active presale", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/V1ErrorWrapper" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/drops/{slug}/allowlist": { "post": { "tags": ["Drops Endpoints"], "summary": "Upload drop allowlist", "description": "The file is CSV with a header row, and the wallet column must be named address or walletaddress. Optional per-row columns are a custom mint limit and a custom price. This response starts a three-step upload flow. First, request this context from OpenSea. Second, call the returned method at the returned URL. For POST, add every fields entry unchanged as a multipart text field, then add a file part containing the bytes. The file part must be last. Let the HTTP library generate the multipart boundary; do not set the overall multipart Content-Type header yourself. POST storage uploads normally return 204. For PUT, upload the raw bytes, use only headers explicitly required by the endpoint, and expect 200. Treat any 2xx storage response as success. The URL and fields are short-lived sensitive credentials. Do not log, persist, alter, or put them in tickets. Third, after storage succeeds, pass the returned token to the documented OpenSea API endpoint. Do not use the token before the storage upload succeeds. Pass the token as allowlist_file_token to POST /api/v2/drops/{slug}/allowlist/validate, which returns a different token. That second token is the one a stage takes: send it as allowlist_file_token on the stage in POST /api/v2/drops/{slug}, or the uploaded file is never attached to anything. The presigned upload expires about a minute after it is issued, so request the context and upload in one go rather than requesting it ahead of time.", "operationId": "upload_drop_allowlist", "parameters": [ { "name": "slug", "in": "path", "description": "Collection slug", "required": true, "schema": { "type": "string" }, "example": "cool-cats" } ], "responses": { "200": { "description": "Upload context generated successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/UploadContext" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/UploadContext" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:drops"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:drops"] } }, "/api/v2/drops/{slug}/allowlist/validate": { "post": { "tags": ["Drops Endpoints"], "summary": "Validate drop allowlist", "description": "Validate an uploaded drop allowlist file token.", "operationId": "validate_drop_allowlist", "parameters": [ { "name": "slug", "in": "path", "description": "Collection slug", "required": true, "schema": { "type": "string" }, "example": "cool-cats" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateDropAllowlistRequest" } } }, "required": true }, "responses": { "200": { "description": "Validated file token", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidateDropAllowlistResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ValidateDropAllowlistResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:drops"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:drops"] } }, "/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/{slug}/images/{image_type}": { "post": { "tags": ["Collection Endpoints"], "summary": "Upload collection image", "description": "Set the content_type query parameter to the exact MIME type of the image bytes. This response starts a three-step upload flow. First, request this context from OpenSea. Second, call the returned method at the returned URL. For POST, add every fields entry unchanged as a multipart text field, then add a file part containing the bytes. The file part must be last. Let the HTTP library generate the multipart boundary; do not set the overall multipart Content-Type header yourself. POST storage uploads normally return 204. For PUT, upload the raw bytes, use only headers explicitly required by the endpoint, and expect 200. Treat any 2xx storage response as success. The URL and fields are short-lived sensitive credentials. Do not log, persist, alter, or put them in tickets. Third, after storage succeeds, pass the returned token to the documented OpenSea API endpoint. Do not use the token before the storage upload succeeds. Pass the token as the matching image field in PATCH /api/v2/collections/{slug}.", "operationId": "upload_collection_image", "parameters": [ { "name": "slug", "in": "path", "description": "Collection slug", "required": true, "schema": { "type": "string" }, "example": "boredapeyachtclub" }, { "name": "image_type", "in": "path", "description": "Image type", "required": true, "schema": { "type": "string" }, "example": "profile_picture" }, { "name": "content_type", "in": "query", "description": "Exact MIME type of the image bytes", "required": true, "schema": { "type": "string" }, "example": "image/png" } ], "responses": { "200": { "description": "Upload context generated successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/UploadContext" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/UploadContext" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:collections"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:collections"] } }, "/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 to filter the results", "required": true, "schema": { "$ref": "#/components/schemas/ChainIdentifier" }, "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": "The blockchain on which to filter the results", "required": true, "schema": { "$ref": "#/components/schemas/ChainIdentifier" }, "example": "ethereum" }, { "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. Keys expire after 7 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/accounts/{address_or_username}/watch": { "post": { "tags": ["Account Endpoints"], "summary": "Watch a followed profile", "operationId": "watch_account", "parameters": [ { "name": "address_or_username", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256, "minLength": 0 } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ProfileSocialMutationResponse" } } } } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:social"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:social"] }, "delete": { "tags": ["Account Endpoints"], "summary": "Stop watching a profile", "operationId": "unwatch_account", "parameters": [ { "name": "address_or_username", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256, "minLength": 0 } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ProfileSocialMutationResponse" } } } } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:social"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:social"] } }, "/api/v2/accounts/{address_or_username}/follow": { "post": { "tags": ["Account Endpoints"], "summary": "Follow a profile", "operationId": "follow_account", "parameters": [ { "name": "address_or_username", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256, "minLength": 0 } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ProfileSocialMutationResponse" } } } } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:social"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:social"] }, "delete": { "tags": ["Account Endpoints"], "summary": "Unfollow a profile", "operationId": "unfollow_account", "parameters": [ { "name": "address_or_username", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256, "minLength": 0 } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ProfileSocialMutationResponse" } } } } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:social"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:social"] } }, "/api/v2/accounts/wallets/siwx": { "post": { "tags": ["Account Endpoints"], "summary": "Link a wallet to the authenticated account", "description": "Verify control of a wallet using a SIWX signature and link it to the authenticated account.", "operationId": "link_wallet_with_siwx", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkWalletSiwxRequest" } } }, "required": true }, "responses": { "200": { "description": "Wallet linked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletLinkResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletLinkResponse" } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:wallets"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:wallets"] } }, "/api/v2/accounts/agent-relationships": { "get": { "tags": ["Account Endpoints"], "summary": "List the authenticated account's agent relationships", "description": "Includes proposals still awaiting either party. Pending relationships appear here only; they are never shown on a public profile. Truncated to the 100 most recent confirmed relationships and the 50 most recent live proposals, bounded separately so unanswered proposals cannot displace confirmed relationships. No total is returned. Confirming or revoking names the counterparty's account id, which this listing is the source of.", "operationId": "list_own_agent_relationships", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRelationshipListResponse" } } } } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["read:wallets"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["read:wallets"] }, "post": { "tags": ["Account Endpoints"], "summary": "Propose an agent ownership relationship", "description": "Both accounts must agree. Proposing a relationship that is already awaiting you confirms it, so a client that cannot tell who moved first can simply propose.", "operationId": "propose_agent_relationship", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposeAgentRelationshipRequestBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRelationshipMutationResponse" } } } } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:wallets"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:wallets"] }, "delete": { "tags": ["Account Endpoints"], "summary": "Withdraw a proposal or revoke a confirmed agent relationship", "description": "Either party may remove the relationship at any point. Addressed exactly as confirm is: `counterparty_account_id` or `counterparty_address`, one of the two, plus your own side.", "operationId": "revoke_agent_relationship", "parameters": [ { "name": "counterparty_account_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "counterparty_address", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "caller_role", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRelationshipRemovalResponse" } } } } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:wallets"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:wallets"] } }, "/api/v2/accounts/agent-relationships/confirm": { "post": { "tags": ["Account Endpoints"], "summary": "Confirm an agent relationship proposed to the authenticated account", "description": "Name the other party by `counterparty_account_id`, from `agent_account_id` or `owner_account_id` on a listed relationship, or by `counterparty_address`. Prefer the account: the relationship is the pair of accounts, so it stays addressable after either party unlinks the wallet it was proposed with, whereas an address stops resolving once unlinked.", "operationId": "confirm_agent_relationship", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmAgentRelationshipRequestBody" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRelationshipMutationResponse" } } } } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:wallets"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:wallets"] } }, "/api/v2/profile": { "patch": { "tags": ["Account Endpoints"], "summary": "Update profile settings", "description": "Update the authenticated wallet's profile settings.", "operationId": "update_profile_settings", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProfileSettingsRequest" } } }, "required": true }, "responses": { "200": { "description": "Profile settings updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProfileSettingsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:profile"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:profile"] } }, "/api/v2/profile/shelves/{shelf_id}": { "delete": { "tags": ["Account Endpoints"], "summary": "Delete a profile shelf", "description": "Delete the authenticated wallet's shelf.", "operationId": "delete_profile_shelf", "parameters": [ { "name": "shelf_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Shelf deleted successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ProfileShelfActionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:profile"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:profile"] }, "patch": { "tags": ["Account Endpoints"], "summary": "Update a profile shelf", "description": "Update shelf fields and optionally item descriptions. Shelf field updates are applied first; if a later item description update fails, earlier changes are not rolled back.", "operationId": "update_profile_shelf", "parameters": [ { "name": "shelf_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProfileShelfRequest" } } }, "required": true }, "responses": { "200": { "description": "Shelf updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileShelfResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:profile"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:profile"] } }, "/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" } } }, "patch": { "tags": ["Collection Endpoints"], "summary": "Modify collection metadata", "description": "Update an existing collection's metadata.", "operationId": "modify_collection", "parameters": [ { "name": "slug", "in": "path", "description": "Collection slug", "required": true, "schema": { "type": "string" }, "example": "boredapeyachtclub" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModifyCollectionRequest" } } }, "required": true }, "responses": { "200": { "description": "Collection metadata updated successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ModifyCollectionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ModifyCollectionResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:collections"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:collections"] } }, "/api/v2/collections/{slug}/visibility": { "patch": { "tags": ["Collection Endpoints"], "summary": "Set collection visibility", "description": "Hide or unhide a collection.", "operationId": "set_collection_visibility", "parameters": [ { "name": "slug", "in": "path", "description": "Collection slug", "required": true, "schema": { "type": "string" }, "example": "boredapeyachtclub" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetCollectionVisibilityRequest" } } }, "required": true }, "responses": { "200": { "description": "Visibility updated successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SetCollectionVisibilityResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:collections"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:collections"] } }, "/api/v2/collections/{slug}/metadata": { "patch": { "tags": ["Collection Endpoints"], "summary": "Update collection metadata", "description": "Update collection about, hero, overview, and logo image metadata.", "operationId": "update_collection_metadata", "parameters": [ { "name": "slug", "in": "path", "description": "Collection slug", "required": true, "schema": { "type": "string" }, "example": "boredapeyachtclub" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCollectionMetadataRequest" } } }, "required": true }, "responses": { "200": { "description": "Collection metadata updated successfully", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/UpdateCollectionMetadataResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/UpdateCollectionMetadataResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:collections"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:collections"] } }, "/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/traits/{slug}/floors": { "get": { "tags": ["Collection Endpoints"], "summary": "Get trait floor prices", "description": "Get the cheapest active listing for every trait value in a collection, in one request. Trait values with no active listing are omitted. Results are ordered by trait type, then value, then price.\n\nOnly traits with text values are included. A numeric trait has no enumerable set of values, so it is reported as a min/max range by 'GET /api/v2/traits/{slug}' rather than as a floor per value here.\n\nPrices come from each item's best listing across every marketplace OpenSea aggregates, the same basis as 'floor_price' in 'GET /api/v2/collections/{slug}/stats'. A floor can therefore be below the cheapest listing fulfillable through this API, because 'GET /api/v2/listings/collection/{slug}/best' serves only the OpenSea order book.\n\nPrices are not converted to a common currency: a trait value listed in more than one currency appears once per currency, and prices are only comparable within the same 'payment_token_symbol'.", "operationId": "get_collection_trait_floors", "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/TraitFloorsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "Aggregation timed out; the collection is too large to serve", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/V1ErrorWrapper" } } } } } } }, "/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": "source", "in": "query", "description": "Filter by source: onchain, x402_bazaar, x402_bankr. Defaults to all sources when omitted.", "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", "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: an onchain EVM address, or x402_bazaar / x402_bankr for x402 tools", "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/{registry_chain}/{registry_addr}/{tool_id}/activity": { "get": { "tags": ["Tool Endpoints [Beta]"], "summary": "[Beta] Get activity for a registered tool", "description": "[Beta] Returns merged x402 payment events and usage reports for a tool, deduplicated by transaction hash. Each event includes an attribution field indicating confidence level. This endpoint is under active development and may change without notice.", "operationId": "get_tool_activity", "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: an onchain EVM address, or x402_bazaar / x402_bankr for x402 tools", "required": true, "schema": { "type": "string" } }, { "name": "tool_id", "in": "path", "description": "Numeric tool ID", "required": true, "schema": { "type": "string" } }, { "name": "include_creator_payments", "in": "query", "description": "Include payments attributed only by creator address", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "description": "Maximum number of results (1-100)", "required": false, "schema": { "type": "integer", "format": "int32", "default": 25 } }, { "name": "offset", "in": "query", "description": "Offset for pagination", "required": false, "schema": { "type": "integer", "format": "int32", "default": 0 } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ToolActivityPaginatedResponse" } } } }, "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": "source", "in": "query", "description": "Filter by source: onchain, x402_bazaar, x402_bankr. Defaults to all sources when omitted.", "required": false, "schema": { "type": "string" } }, { "name": "collection", "in": "query", "description": "Filter to tools gated by owning an NFT in this collection (slug). Unknown slugs return no results.", "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", "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. Pass `sort_by` and `sort_direction` to order the same set of tokens differently.", "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": "sort_by", "in": "query", "description": "Sort field (default: score)", "required": false, "schema": { "type": "string", "description": "Sort field for the token ranking endpoints", "enum": [ "market_cap", "one_hour_volume", "one_day_volume", "one_hour_price_change", "one_day_price_change", "seven_day_price_change", "fourteen_day_price_change", "thirty_day_price_change", "two_hundred_day_price_change", "one_year_price_change", "price", "genesis_date", "score" ] }, "example": "score" }, { "name": "sort_direction", "in": "query", "description": "Sort direction (default: desc)", "required": false, "schema": { "type": "string", "enum": ["asc", "desc"] }, "example": "desc" }, { "name": "cursor", "in": "query", "description": "Pagination cursor for next page. A cursor is only valid for the query that produced it: keep `sort_by`, `sort_direction` and `chains` identical across pages, and start a new page-one request when any of them changes.", "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. Pass `sort_by` and `sort_direction` to order the same set of tokens differently.", "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": "sort_by", "in": "query", "description": "Sort field (default: one_day_volume)", "required": false, "schema": { "type": "string", "description": "Sort field for the token ranking endpoints", "enum": [ "market_cap", "one_hour_volume", "one_day_volume", "one_hour_price_change", "one_day_price_change", "seven_day_price_change", "fourteen_day_price_change", "thirty_day_price_change", "two_hundred_day_price_change", "one_year_price_change", "price", "genesis_date", "score" ] }, "example": "one_day_volume" }, { "name": "sort_direction", "in": "query", "description": "Sort direction (default: desc)", "required": false, "schema": { "type": "string", "enum": ["asc", "desc"] }, "example": "desc" }, { "name": "cursor", "in": "query", "description": "Pagination cursor for next page. A cursor is only valid for the query that produced it: keep `sort_by`, `sort_direction` and `chains` identical across pages, and start a new page-one request when any of them changes.", "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": "The blockchain on which to filter the results", "required": true, "schema": { "$ref": "#/components/schemas/ChainIdentifier" }, "example": "ethereum" }, { "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", "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", "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", "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", "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": { "$ref": "#/components/schemas/ChainIdentifier" }, "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", "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" }, "503": { "description": "Trait filter query timed out; try a more selective filter", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/V1ErrorWrapper" } } } } } } }, "/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", "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", "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", "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": { "$ref": "#/components/schemas/ChainIdentifier" }, "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", "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": { "$ref": "#/components/schemas/ChainIdentifier" }, "example": "ethereum" }, { "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", "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}/eligibility": { "get": { "tags": ["Drops Endpoints"], "summary": "Get drop eligibility for the authenticated wallet", "description": "Returns per-stage eligibility for the authenticated wallet, including pricing and mint limits.", "operationId": "get_drop_eligibility", "parameters": [ { "name": "slug", "in": "path", "description": "Collection slug", "required": true, "schema": { "type": "string" }, "example": "cool-cats" } ], "responses": { "200": { "description": "Eligibility results per drop stage", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/DropEligibilityResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/DropEligibilityResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["read:eligibility"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["read:eligibility"] } }, "/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": "The blockchain on which to filter the results", "required": true, "schema": { "$ref": "#/components/schemas/ChainIdentifier" }, "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", "default": 50, "description": "Number of items to return per page", "example": 20, "maximum": 100, "minimum": 1 }, "example": 20 }, { "name": "next", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "chain", "in": "query", "description": "Blockchain to filter by", "required": false, "schema": { "$ref": "#/components/schemas/ChainIdentifier" }, "example": "ethereum" }, { "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}/stats": { "get": { "tags": ["Collection Endpoints", "Analytics Endpoints"], "summary": "Get collection stats", "description": "Get statistics for a collection including volume, floor price, and trading metrics. Each currency-denominated figure carries its own symbol: volume is reported in the currency named by volume_symbol, and the floor in the currency named by floor_price_symbol. The two can differ, so read each number against its own symbol.", "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", "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 to filter the results", "required": true, "schema": { "$ref": "#/components/schemas/ChainIdentifier" }, "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 to filter the results", "required": true, "schema": { "$ref": "#/components/schemas/ChainIdentifier" }, "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 to filter the results", "required": true, "schema": { "$ref": "#/components/schemas/ChainIdentifier" }, "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 to filter the results", "required": true, "schema": { "$ref": "#/components/schemas/ChainIdentifier" }, "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 to filter the results", "required": true, "schema": { "$ref": "#/components/schemas/ChainIdentifier" }, "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 to filter the results", "required": true, "schema": { "$ref": "#/components/schemas/ChainIdentifier" }, "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}/token/{address}/activity/stats": { "get": { "tags": ["Token Endpoints"], "summary": "Get token trading activity stats", "description": "Get materialized trade count, USD volume, and average trade size for a token. Windows with no swaps are omitted; an omitted requested key means zero trades in that window. Each window ends at its own materialized snapshot; computed_at is the oldest snapshot among the returned windows and can precede request time because the response is cached. The 1h and 24h windows also carry unique_buyer_count and unique_seller_count, which are null when the counts are unavailable for that token; 5m and 4h never carry them.", "operationId": "get_token_activity_stats", "parameters": [ { "name": "chain", "in": "path", "description": "The blockchain on which to filter the results", "required": true, "schema": { "$ref": "#/components/schemas/ChainIdentifier" }, "example": "ethereum" }, { "name": "address", "in": "path", "description": "The token contract address", "required": true, "schema": { "type": "string" }, "example": "0x0000000000000000000000000000000000000000" }, { "name": "windows", "in": "query", "description": "Comma-separated windows. Defaults to 5m,1h,4h,24h.", "required": false, "schema": { "type": "string", "maxLength": 32, "minLength": 0, "pattern": "^(5m|1h|4h|24h)(,(5m|1h|4h|24h))*$" }, "example": "1h,24h" } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/TokenActivityStatsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "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": { "$ref": "#/components/schemas/ChainIdentifier" }, "example": "ethereum" } ], "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": { "$ref": "#/components/schemas/ChainIdentifier" }, "example": "ethereum" } ], "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": "The blockchain on which to filter the results", "required": true, "schema": { "$ref": "#/components/schemas/ChainIdentifier" }, "example": "ethereum" }, { "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", "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": { "$ref": "#/components/schemas/ChainIdentifier" }, "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": { "$ref": "#/components/schemas/ChainIdentifier" }, "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": { "$ref": "#/components/schemas/ChainIdentifier" }, "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": { "$ref": "#/components/schemas/ChainIdentifier" }, "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": "The blockchain on which to filter the results", "required": true, "schema": { "$ref": "#/components/schemas/ChainIdentifier" }, "example": "ethereum" }, { "name": "collection", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "include_auto_hidden", "in": "query", "description": "Include NFTs that were hidden automatically because a third party minted or sent them to this account. NFTs the account holder hid themselves are not returned, and this does not surface NFTs removed for policy violations.", "required": false, "schema": { "type": "boolean", "default": false } }, { "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", "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", "maxLength": 256, "minLength": 0 }, "example": "0x8ba1f109551bD432803012645fAc136c94C19D6e" } ], "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/{address_or_username}/relationship": { "get": { "tags": ["Account Endpoints"], "summary": "Get the authenticated account's relationship with a profile", "operationId": "get_account_relationship", "parameters": [ { "name": "address_or_username", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256, "minLength": 0 } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ProfileRelationshipResponse" } } } } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["read:social"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["read:social"] } }, "/api/v2/accounts/{address_or_username}/following": { "get": { "tags": ["Account Endpoints"], "summary": "Get profiles followed", "description": "Returns the profiles followed by an address or username profile, including followed wallets.", "operationId": "get_account_following", "parameters": [ { "name": "address_or_username", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256, "minLength": 0 } }, { "name": "limit", "in": "query", "description": "Number of items to return per page", "required": false, "schema": { "type": "integer", "format": "int32", "default": 50, "description": "Number of items to return per page", "example": 20, "maximum": 100, "minimum": 1 }, "example": 20 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SocialProfilePageResponse" } } } } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["read:social"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["read:social"] } }, "/api/v2/accounts/{address_or_username}/followers": { "get": { "tags": ["Account Endpoints"], "summary": "Get profile followers", "operationId": "get_account_followers", "parameters": [ { "name": "address_or_username", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256, "minLength": 0 } }, { "name": "limit", "in": "query", "description": "Number of items to return per page", "required": false, "schema": { "type": "integer", "format": "int32", "default": 50, "description": "Number of items to return per page", "example": 20, "maximum": 100, "minimum": 1 }, "example": 20 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SocialProfilePageResponse" } } } } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["read:social"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["read:social"] } }, "/api/v2/accounts/{address_or_username}/agent-relationships": { "get": { "tags": ["Account Endpoints"], "summary": "Get public agent ownership relationships for a profile", "description": "Returns the account confirmed to own this one as its agent, and the accounts it is the confirmed owner of. Only relationships both accounts confirmed appear; a proposal one side has not accepted is visible to the two parties alone. Ownership is a declaration and not an authorization, and is self-reported rather than verified by OpenSea. Standard API-key quotas and an additional 30-per-hour per-profile limit apply.", "operationId": "get_agent_profile_relationships", "parameters": [ { "name": "address_or_username", "in": "path", "description": "The blockchain address or username of the profile to retrieve.", "required": true, "schema": { "type": "string", "maxLength": 256, "minLength": 0 }, "example": "0x8ba1f109551bD432803012645fAc136c94C19D6e" } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/AgentProfileRelationshipsResponse" } } } } } } }, "/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}/token_watchlist": { "get": { "tags": ["Account Endpoints"], "summary": "Get tokens watched by an account", "description": "Get the tokens watched by the authenticated account. Requires wallet identity authentication; the requested address must belong to the authenticated account.", "operationId": "get_account_token_watchlist", "parameters": [ { "name": "address", "in": "path", "description": "The wallet address", "required": true, "schema": { "type": "string" }, "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" } ], "responses": { "200": { "description": "Watched tokens", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/TokenPaginatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/TokenPaginatedResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["read:favorites"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["read:favorites"] } }, "/api/v2/account/{address}/token-activity": { "get": { "tags": ["Token Endpoints"], "summary": "Get account token activity", "description": "Get paginated fungible token activity (transfers, swaps, wraps, and unwraps) for an account across all chains. Optionally filter by chain, token, and/or activity type.", "operationId": "get_account_token_activity", "parameters": [ { "name": "address", "in": "path", "description": "The account address to query token activity for", "required": true, "schema": { "type": "string" }, "example": "0x0000000000000000000000000000000000000000" }, { "name": "chains", "in": "query", "description": "Chain(s) to filter by (e.g. ethereum). Repeat for multiple chains. Omit to query all chains.", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChainIdentifier" } }, "example": "ethereum" }, { "name": "tokens", "in": "query", "description": "Token contract address(es) to filter by. Repeat for multiple tokens. Omit to include all tokens.", "required": false, "schema": { "type": "array", "items": { "type": "string", "description": "A blockchain address in its chain's native format. EVM: `0x` or `0X` followed by 40 hex digits, matching `^0[xX][0-9a-fA-F]{40}$`, and not checksum-verified. Solana: a base58-encoded 32-byte public key, 32 to 44 characters, which must decode to exactly 32 bytes. Bitcoin: base58check or bech32, checksum-verified. Only the EVM form is a pure pattern, so this field publishes none.", "example": "0x0000000000000000000000000000000000000000" } }, "example": "0x0000000000000000000000000000000000000000" }, { "name": "type", "in": "query", "description": "Activity types to include (send, receive, swap, wrap, unwrap). Repeat for multiple types. Omit to include all. Note: swap also includes wrap and unwrap activities.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "limit", "in": "query", "description": "Number of items to return per page", "required": false, "schema": { "type": "integer", "format": "int32", "default": 20, "description": "Number of items to return per page", "example": 20, "maximum": 50, "minimum": 1 }, "example": 20 }, { "name": "next", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/TokenAccountActivityPaginatedResponse" } } } }, "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"] } }, { "name": "chains", "in": "query", "description": "Comma-separated chains to restrict the portfolio to (e.g. ethereum,base). When omitted, all supported chains are included. Returns 400 if all specified chains are unsupported.", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChainIdentifier" } }, "example": "ethereum,base" } ], "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}/pnl": { "get": { "tags": ["Account Endpoints"], "summary": "Get trading P&L for an account", "description": "Get aggregated realized and unrealized trading profit and loss across all currencies held by a wallet address. Returns 200 with figures (which may be zero for a real but flat wallet) when OpenSea has indexed P&L for the wallet, and 404 only when no P&L has been indexed for it — letting consumers distinguish \"indexed but flat\" from \"not indexed\".", "operationId": "get_wallet_pnl", "parameters": [ { "name": "address", "in": "path", "description": "The wallet address", "required": true, "schema": { "type": "string" }, "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" } ], "responses": { "200": { "description": "Wallet trading P&L. Indexed wallets return 200 even when all figures are zero (real but flat).", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/WalletPnlResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/account/{address}/pnl/token-transfers": { "get": { "tags": ["Account Endpoints"], "summary": "Get token transfers for a wallet's position in a currency", "description": "Get a paginated, transfer-level breakdown of a wallet's position in a single currency (identified by contract_address + chain). Combine `direction` and `transfer_type` to distinguish zero-cost acquisitions (airdrops, CEX transfers) from buys.", "operationId": "get_wallet_token_transfers", "parameters": [ { "name": "address", "in": "path", "description": "The wallet address", "required": true, "schema": { "type": "string" }, "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }, { "name": "contract_address", "in": "query", "description": "The currency's contract address", "required": true, "schema": { "type": "string" }, "example": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }, { "name": "chain", "in": "query", "description": "The chain the currency is on", "required": true, "schema": { "$ref": "#/components/schemas/ChainIdentifier" }, "example": "ethereum" }, { "name": "limit", "in": "query", "description": "Number of results to return per page (1-200, default 20)", "required": false, "schema": { "type": "integer", "format": "int32", "default": 20 } }, { "name": "next", "in": "query", "description": "Cursor for the next page of results", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Position token transfers", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PositionTokenTransfersResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/account/{address}/pnl/closed-positions": { "get": { "tags": ["Account Endpoints"], "summary": "Get closed (realized) trading positions for an account", "description": "Get a paginated, per-trade breakdown of a wallet's realized P&L. Each closed position reflects FIFO (first-in, first-out) cost-basis lot matching.", "operationId": "get_wallet_closed_positions", "parameters": [ { "name": "address", "in": "path", "description": "The wallet address", "required": true, "schema": { "type": "string" }, "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }, { "name": "sort_by", "in": "query", "description": "Sort order: TOP_TRADES (default) or RECENT", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page (1-200, default 20)", "required": false, "schema": { "type": "integer", "format": "int32", "default": 20 } }, { "name": "next", "in": "query", "description": "Cursor for the next page of results", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Closed positions", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ClosedPositionsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v2/account/{address}/perpetual_watchlist": { "get": { "tags": ["Account Endpoints"], "summary": "Get perpetuals watched by an account", "description": "Get the perpetual futures watched by the authenticated account. Requires wallet identity authentication; the requested address must belong to the authenticated account.", "operationId": "get_account_perpetual_watchlist", "parameters": [ { "name": "address", "in": "path", "description": "The wallet address", "required": true, "schema": { "type": "string" }, "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" } ], "responses": { "200": { "description": "Watched perpetuals", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PerpetualFuturePaginatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PerpetualFuturePaginatedResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["read:favorites"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["read:favorites"] } }, "/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. Requires wallet identity authentication; the requested address must belong to the authenticated account.", "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" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/NftListResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["read:favorites"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["read:favorites"] } }, "/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" } } } }, "/api/v2/accounts/wallets/{wallet}": { "delete": { "tags": ["Account Endpoints"], "summary": "Unlink a wallet from the authenticated account", "description": "Unlink a wallet from the authenticated account using a scoped wallet token.", "operationId": "unlink_wallet", "parameters": [ { "name": "wallet", "in": "path", "description": "The linked wallet address to remove", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Wallet unlinked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletUnlinkResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletUnlinkResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "ApiKeyAuth": [], "WalletAuth": ["write:wallets"] } ], "x-opensea-auth-required": true, "x-opensea-auth-scopes": ["write:wallets"] } }, "/api/v2/auth/tokens/exchange": { "post": { "tags": ["Auth Endpoints"], "summary": "Exchange a scoped token for an access token", "description": "Exchanges an opaque scoped token (personal access token) for a short-lived access token that satisfies `WalletAuth` on wallet-scoped endpoints. Send the returned `accessToken` as `Authorization: Bearer `.\n\nThis is the credential path for headless callers that hold no signing key: the scoped token in the request body is the only credential, so no session cookie, wallet signature, or API key is required. The alternative is the OAuth 2.1 authorization-code flow described by the `WalletAuth` security scheme.\n\nFailures are deliberately opaque. An unknown, revoked, rotated, or non-scoped subject token and a disabled integration all return the same 403 `Token exchange is not available`, so a 403 is not by itself evidence that the endpoint is unavailable.", "operationId": "exchange_scoped_token", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenExchangeRequest" } } }, "required": true }, "responses": { "200": { "description": "Access token minted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenExchangeResponse" } } } }, "400": { "description": "Request body failed validation, for example a `subjectToken` outside the 10 to 8192 character range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "Token exchange is not available. Returned for an unknown, revoked, or non-scoped subject token as well as for a disabled integration; the two are not distinguishable by design.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "422": { "description": "Body could not be read: malformed JSON, a missing required field, or an unsupported `subjectTokenType`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "500": { "description": "Exchange failed after the token was minted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "502": { "description": "Upstream auth service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "503": { "description": "Upstream auth service temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } } }, "security": [] } } }, "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", "robinhood", "stablechain", "arc" ], "example": "ethereum" }, "SelfMintDropItemResponse": { "type": "object", "description": "Ready-to-sign SelfMint drop item 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"] }, "SelfMintDropItemTraitRequest": { "type": "object", "description": "Trait identifier for a SelfMint drop item", "properties": { "trait_type": { "type": "string", "description": "Trait type", "minLength": 1 }, "value": { "type": "string", "description": "Trait value", "minLength": 1 } }, "required": ["trait_type", "value"] }, "UpdateSelfMintDropItemRequest": { "type": "object", "description": "Request to update a SelfMint drop item", "properties": { "media_token": { "type": "string", "description": "Media token reference", "minLength": 1 }, "name": { "type": "string", "description": "Item name", "maxLength": 100, "minLength": 0 }, "description": { "type": "string", "description": "Item description", "maxLength": 2000, "minLength": 0 }, "external_url": { "type": "string", "description": "External URL", "maxLength": 1000, "minLength": 0 }, "animation_url": { "type": "string", "description": "Animated media for the item, alongside its image. Omit to leave the stored value alone; send an empty string to remove it.", "maxLength": 1000, "minLength": 0 }, "traits": { "type": "array", "description": "Item traits", "items": { "$ref": "#/components/schemas/SelfMintDropItemTraitRequest" }, "maxItems": 40, "minItems": 0 } }, "required": ["media_token", "name"] }, "WalletVisibilityResponse": { "type": "object", "properties": { "address": { "type": "string" }, "is_private": { "type": "boolean" } }, "required": ["address", "is_private"] }, "AgentAccountStatusResponse": { "type": "object", "properties": { "is_agent": { "type": "boolean" }, "changed": { "type": "boolean" } }, "required": ["changed", "is_agent"] }, "WatchlistRequest": { "type": "object", "description": "Request body for managing a watchlist entry", "properties": { "type": { "type": "string", "description": "Watchlist entity type", "enum": ["ITEM", "TOKEN", "COLLECTION", "PERPETUAL"] }, "chain": { "type": "string", "description": "Blockchain chain slug", "example": "ethereum" }, "contract_address": { "type": "string", "description": "Contract address" }, "token_id": { "type": "string", "description": "Token ID" }, "slug": { "type": "string", "description": "Collection slug" }, "id": { "type": "string", "description": "Perpetual ID" } }, "required": ["type"] }, "FavoriteResponse": { "type": "object", "description": "Response for a favorites write operation", "properties": { "success": { "type": "boolean", "description": "Whether the operation succeeded" } }, "required": ["success"] }, "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" }, "tool_endpoint": { "type": "string" }, "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": "USDC" }, "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": "USDC" }, "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" }, "description_source": { "type": "string", "description": "Source of the description. `TOKEN_METADATA` is supplied by token metadata; `AI_GENERATED` is OpenSea's generated token-page description.", "enum": ["TOKEN_METADATA", "AI_GENERATED"] }, "description_generated_at": { "type": "number", "format": "double", "description": "When an AI-generated description was generated" }, "description_sources": { "type": "array", "description": "Sources used for an AI-generated description", "items": { "type": "string" } }, "stats": { "$ref": "#/components/schemas/TokenStatsResponse", "description": "Market statistics for the token" }, "socials": { "$ref": "#/components/schemas/TokenSocialsResponse", "description": "Social media links for the token" }, "holders_count": { "type": "integer", "format": "int64", "description": "Number of token holders" }, "is_verified": { "type": "boolean", "description": "Whether OpenSea has verified the token" }, "created_at": { "type": "number", "format": "double", "description": "When OpenSea first recorded the token" }, "genesis_date": { "type": "number", "format": "double", "description": "Earliest known onchain activity 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", "is_verified", "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" }, "subreddit_identifier": { "type": "string", "description": "The token's subreddit identifier" }, "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"] }, "SvmInstructionAccountResponse": { "type": "object", "description": "An account referenced by a Solana instruction", "properties": { "pubkey": { "type": "string", "description": "Base58-encoded account address", "example": "So11111111111111111111111111111111111111112" }, "signer": { "type": "boolean", "description": "Whether the account must sign the transaction" }, "writable": { "type": "boolean", "description": "Whether the instruction writes to the account" } }, "required": ["pubkey", "signer", "writable"] }, "SvmInstructionResponse": { "type": "object", "description": "A Solana instruction to include in the transaction", "properties": { "program_id": { "type": "string", "description": "Base58-encoded program address the instruction invokes", "example": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4" }, "accounts": { "type": "array", "description": "Accounts the instruction reads or writes, in order", "items": { "$ref": "#/components/schemas/SvmInstructionAccountResponse" } }, "data": { "type": "string", "description": "Hex-encoded instruction payload, optionally 0x-prefixed", "example": "01020304" } }, "required": ["accounts", "program_id"] }, "SvmTransactionDetailsResponse": { "type": "object", "description": "Everything needed to compile and sign a Solana v0 transaction. The client supplies a recent blockhash.", "properties": { "from": { "type": "string", "description": "Base58-encoded address the transaction is built for" }, "instructions": { "type": "array", "description": "Instructions to include, in order", "items": { "$ref": "#/components/schemas/SvmInstructionResponse" } }, "address_lookup_tables": { "type": "array", "description": "Base58-encoded address lookup tables the compiled message must reference to stay under the transaction size limit", "items": { "type": "string" } } }, "required": ["address_lookup_tables", "from", "instructions"] }, "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", "EXECUTION" ], "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 }, "refresh_after_ms": { "type": "integer", "format": "int32", "description": "Recommended delay in milliseconds before re-requesting this quote; absent when there is no actionable route", "example": 2000 }, "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 (decimal)" }, "value_hex": { "type": "string", "description": "The native token value to send with the transaction (hex, 0x-prefixed)" }, "svm": { "$ref": "#/components/schemas/SvmTransactionDetailsResponse", "description": "Structured Solana transaction contents. Set for SVM chains only; `data` is a lossy summary of the same instructions." }, "gas_limit": { "type": "string", "description": "Gas limit for the transaction, in gas units. Already includes a safety buffer over the estimate — use it as-is (or take the max of this and your own buffered estimate) and do not shrink it. Null when no reliable estimate is available." } }, "required": ["chain", "data"] }, "SavedToolRequest": { "type": "object", "description": "A registered tool to save or remove from saved tools", "properties": { "tool_id": { "type": "string", "description": "Numeric registered tool ID", "example": 42, "minLength": 1 }, "registry_chain": { "type": "string", "description": "Numeric registry chain ID", "example": 8453, "minLength": 1 }, "registry_addr": { "type": "string", "description": "Registry contract address or supported x402 registry identifier", "example": "0x0000000000000000000000000000000000000000", "minLength": 1 }, "toolkit_name": { "type": "string", "description": "Saved-tools toolkit name", "example": "All", "maxLength": 255, "minLength": 0, "pattern": "(?s).*\\S.*" } }, "required": ["registry_addr", "registry_chain", "tool_id"] }, "SavedToolResponse": { "type": "object", "description": "A tool saved by the authenticated account", "properties": { "id": { "type": "string", "description": "Saved-tool record ID" }, "tool_id": { "type": "string", "description": "Numeric registered tool ID" }, "registry_chain": { "type": "string", "description": "Numeric registry chain ID" }, "registry_addr": { "type": "string", "description": "Registry contract address or x402 registry identifier" } }, "required": ["id", "registry_addr", "registry_chain", "tool_id"] }, "ClaimAccountUsernameRequest": { "type": "object", "description": "Request body for claiming a profile username", "properties": { "username": { "type": "string", "description": "Username to claim", "maxLength": 50, "minLength": 1 } }, "required": ["username"] }, "ClaimAccountUsernameResponse": { "type": "object", "description": "Response for claiming a profile username", "properties": { "success": { "type": "boolean", "description": "Whether the username claim succeeded" } }, "required": ["success"] }, "ProfileShelfItemIdentifierResponse": { "type": "object", "description": "Identifier for a shelf item", "properties": { "chain": { "type": "string" }, "contract_address": { "type": "string" }, "token_id": { "type": "string" } }, "required": ["chain", "contract_address", "token_id"] }, "ProfileShelfItemMetadataResponse": { "type": "object", "description": "Metadata for a shelf item", "properties": { "description": { "type": "string" } } }, "ProfileShelfResponse": { "type": "object", "description": "Profile shelf", "properties": { "id": { "type": "string" }, "account_address": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "display_order": { "type": "integer", "format": "int32" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileShelfItemIdentifierResponse" } }, "icon": { "type": "string" }, "view": { "type": "string" }, "single_item_shelf_side": { "type": "string" }, "shelf_item_metadata": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ProfileShelfItemMetadataResponse" } } }, "required": [ "display_order", "id", "items", "shelf_item_metadata", "title" ] }, "CreateProfileShelfRequest": { "type": "object", "description": "Request body for creating a profile shelf", "properties": { "title": { "type": "string", "description": "Shelf title", "maxLength": 100, "minLength": 1 }, "description": { "type": "string", "description": "Shelf description", "maxLength": 500, "minLength": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileShelfItemRequest" }, "maxItems": 50, "minItems": 1 }, "icon": { "type": "string", "description": "Shelf icon" }, "view": { "type": "string", "description": "Shelf view" }, "single_item_shelf_side": { "type": "string", "description": "Single-item shelf side" } }, "required": ["items", "title"] }, "ProfileShelfItemRequest": { "type": "object", "description": "A shelf item identifier", "properties": { "token_id": { "type": "string", "description": "Item token ID", "maxLength": 200, "minLength": 0 }, "chain": { "type": "string", "description": "Blockchain chain slug" }, "contract_address": { "type": "string", "description": "Contract address" } }, "required": ["chain", "contract_address", "token_id"] }, "NftPfpResponse": { "type": "object", "properties": { "contract_address": { "type": "string" }, "token_id": { "type": "string" }, "chain": { "type": "string" }, "collection_slug": { "type": "string" }, "image_url": { "type": "string" }, "is_verified": { "type": "boolean" } }, "required": [ "chain", "contract_address", "image_url", "is_verified", "token_id" ] }, "SetNftPfpRequest": { "type": "object", "description": "Request body for setting an NFT as the profile picture", "properties": { "contractAddress": { "type": "string", "description": "Contract address of the NFT", "example": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d", "maxLength": 200, "minLength": 0 }, "tokenId": { "type": "string", "description": "Token ID of the NFT", "example": 1, "maxLength": 200, "minLength": 0 }, "chain": { "type": "string", "description": "Chain the NFT is on", "example": "ethereum", "maxLength": 100, "minLength": 0 } }, "required": ["chain", "contractAddress", "tokenId"] }, "UploadContext": { "type": "object", "description": "This response starts a three-step upload flow. First, request this context from OpenSea. Second, call the returned method at the returned URL. For POST, add every fields entry unchanged as a multipart text field, then add a file part containing the bytes. The file part must be last. Let the HTTP library generate the multipart boundary; do not set the overall multipart Content-Type header yourself. POST storage uploads normally return 204. For PUT, upload the raw bytes, use only headers explicitly required by the endpoint, and expect 200. Treat any 2xx storage response as success. The URL and fields are short-lived sensitive credentials. Do not log, persist, alter, or put them in tickets. Third, after storage succeeds, pass the returned token to the documented OpenSea API endpoint. Do not use the token before the storage upload succeeds.", "properties": { "url": { "type": "string", "description": "Short-lived storage URL. Use it exactly as returned and treat it as sensitive.", "example": "https://uploads.example.com/" }, "method": { "type": "string", "description": "HTTP method to use at url. Current upload contexts use POST.", "enum": ["POST", "PUT"], "example": "POST" }, "fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Short-lived sensitive multipart text fields for POST. Submit every entry unchanged before the file part. Content-Type contains the exact MIME type required by the signed policy. This map is empty for PUT.", "example": { "key": "uploads/example.png", "Content-Type": "image/png" } }, "token": { "type": "string", "description": "Reference for the next OpenSea API call. Use it only after storage returns 2xx.", "example": "upload-token-example" } }, "required": ["fields", "method", "token", "url"] }, "UploadProfileImageRequest": { "type": "object", "description": "Request body for uploading a profile image", "properties": { "imageType": { "type": "string", "description": "Image type to upload" }, "contentType": { "type": "string", "description": "Exact MIME type of the image bytes", "example": "image/png", "minLength": 1 } }, "required": ["contentType", "imageType"] }, "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", "description": "Seaport order hash, a 0x-prefixed 32-byte value. Absent on an order that settles through a Solana marketplace program, which has no Seaport identity and carries `svm_order` instead. Every EVM order has one." }, "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" }, "protocol": { "type": "string", "description": "Marketplace protocol a Solana order settles through, which is what tells you which identity shape the order uses. Absent on a Seaport order, whose payload is unchanged. Only orders we can build fulfillment for carry a value here." }, "svm_order": { "$ref": "#/components/schemas/SvmOrderIdentity", "description": "Identity of a Solana order, present in place of `order_hash`. A client that assumes `order_hash` is always set should read this field first and fall back to `order_hash`." }, "criteria": { "$ref": "#/components/schemas/Criteria" }, "price": { "$ref": "#/components/schemas/Price" }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "FULFILLED", "EXPIRED", "CANCELLED" ] } } } ], "required": ["chain", "price", "remaining_quantity", "status"] }, "Order": { "type": "object", "properties": { "order_hash": { "type": "string", "description": "Seaport order hash, a 0x-prefixed 32-byte value. Absent on an order that settles through a Solana marketplace program, which has no Seaport identity and carries `svm_order` instead. Every EVM order has one." }, "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" }, "protocol": { "type": "string", "description": "Marketplace protocol a Solana order settles through, which is what tells you which identity shape the order uses. Absent on a Seaport order, whose payload is unchanged. Only orders we can build fulfillment for carry a value here." }, "svm_order": { "$ref": "#/components/schemas/SvmOrderIdentity", "description": "Identity of a Solana order, present in place of `order_hash`. A client that assumes `order_hash` is always set should read this field first and fall back to `order_hash`." } }, "required": ["chain", "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"] }, "SvmOrderIdentity": { "type": "object", "description": "Identity of an order that settles through a Solana marketplace program. Such an order has no Seaport order hash, so `order_hash` is absent from its payload and it is addressed instead by `id`, the transaction signature that created it joined to the onchain state account holding it. Pass that `id` wherever an endpoint takes an order hash.", "properties": { "id": { "type": "string", "description": "`creation_signature:order_state`. This is what an endpoint expecting an order hash takes for a Solana order, for example `GET /api/v2/orders/chain/solana/protocol/{protocol_address}/{order_hash}`. Base58 and case-sensitive; do not lowercase it.", "example": "5j7s1QzqC8sT4Kz1oB9dYnUZ4qHnKX6h9YmZ6Zt7Zb3Q:CvhyBLWDcNwMatkNvMYuHALvbG1NzYrGw32dGzREaQKc" }, "order_state": { "type": "string", "description": "Address of the onchain account holding the order's state. The second half of `id`." }, "creation_signature": { "type": "string", "description": "Signature of the transaction that created the order. The first half of `id`." }, "asset_id": { "type": "string", "description": "Mint of the asset the order is for, where the program records one. Absent otherwise." }, "maker": { "type": "string", "description": "Wallet that created the order." } }, "required": ["creation_signature", "id", "maker", "order_state"] }, "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", "description": "Seaport order hash, a 0x-prefixed 32-byte value. Absent on an order that settles through a Solana marketplace program, which has no Seaport identity and carries `svm_order` instead. Every EVM order has one." }, "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" }, "protocol": { "type": "string", "description": "Marketplace protocol a Solana order settles through, which is what tells you which identity shape the order uses. Absent on a Seaport order, whose payload is unchanged. Only orders we can build fulfillment for carry a value here." }, "svm_order": { "$ref": "#/components/schemas/SvmOrderIdentity", "description": "Identity of a Solana order, present in place of `order_hash`. A client that assumes `order_hash` is always set should read this field first and fall back to `order_hash`." }, "price": { "$ref": "#/components/schemas/ListingPrice" }, "type": { "type": "string" }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "FULFILLED", "EXPIRED", "CANCELLED" ] } } } ], "required": ["chain", "price", "remaining_quantity", "status", "type"] }, "ListingPrice": { "type": "object", "properties": { "current": { "$ref": "#/components/schemas/Price", "description": "What a buyer pays to fill this listing through OpenSea. For most listings this equals the sum of the consideration items in protocolData. A listing ingested from another marketplace may additionally include OpenSea's marketplace fee, which is applied to the transaction at fulfillment rather than being part of the order the seller signed; where that applies, the consideration in protocolData sums to less than this value." } }, "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"] }, "CancelOrderActionsRequest": { "type": "object", "description": "Request to get order cancellation actions", "properties": { "address": { "type": "string", "description": "Maker wallet address that owns the order", "example": "0x..." } }, "required": ["address"] }, "CancelOrderActionsResponse": { "type": "object", "description": "Response containing blockchain actions to execute for order cancellation", "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"] }, "JsonNode": {}, "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" }, "value_hex": { "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" } ] }, "calldata_suffix": { "type": "string", "description": "4-byte hex attribution suffix (e.g. 0xcdb44011) to append to the ABI-encoded calldata before submitting the transaction onchain. Appending this suffix attributes the fill to OpenSea; omitting it does not affect execution." } }, "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" } } }, "FulfillmentActionsResponse": { "type": "object", "description": "Response containing blockchain actions to execute to fulfill an order", "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"] }, "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"] }, "CreateOfferActionItem": { "type": "object", "description": "An item to make an offer on", "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 } }, "required": ["chain", "contract", "token_id"] }, "CreateOfferActionsRequest": { "type": "object", "description": "Request to get offer creation actions", "properties": { "item": { "$ref": "#/components/schemas/CreateOfferActionItem", "description": "Item to make an offer on" }, "address": { "type": "string", "description": "Maker (buyer) wallet address", "example": "0x..." }, "quantity": { "type": "integer", "format": "int64", "description": "Quantity to offer on (use 1 for ERC-721)", "example": 1 }, "price": { "$ref": "#/components/schemas/ListingPriceInput", "description": "Price per item" }, "start_time": { "type": "string", "description": "Offer start time in ISO 8601 format. Defaults to now.", "example": "2026-05-01T00:00:00Z" }, "end_time": { "type": "string", "description": "Offer end time in ISO 8601 format. Defaults to 30 days from start.", "example": "2026-06-01T00:00:00Z" }, "use_creator_fee": { "type": "boolean", "description": "Whether to include optional creator fees. Defaults to false." } }, "required": ["address", "item", "price", "quantity"] }, "ListingPriceInput": { "type": "object", "description": "Price for a listing item", "properties": { "amount": { "type": "string", "description": "Price amount in the currency's unit (e.g. '5.0' for 5 ETH)", "example": 5 }, "currency": { "type": "string", "description": "Contract address of the payment currency (use 0x0000000000000000000000000000000000000000 for native token)", "example": "0x0000000000000000000000000000000000000000" } }, "required": ["amount", "currency"] }, "CreateOfferActionsResponse": { "type": "object", "description": "Response containing blockchain actions to execute for offer 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"] }, "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" } }, "estimated_value_usd": { "type": "number", "format": "double" }, "decimals": { "type": "integer", "format": "int32" } }, "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" } }, "estimated_value_usd": { "type": "number", "format": "double" }, "decimals": { "type": "integer", "format": "int32" }, "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": "number", "format": "double", "description": "Unix timestamp in seconds, including fractional seconds" }, "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 a cross-chain transaction", "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" ] }, "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/ListingPriceInput", "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"] }, "SaveDropResponse": { "type": "object", "description": "Response for saving Creator Studio drop edits", "properties": { "success": { "type": "boolean", "description": "Whether the drop edits were saved successfully" } }, "required": ["success"] }, "SaveDropEditsPriceRequest": { "type": "object", "description": "Native token price for a Creator Studio drop stage", "properties": { "unit": { "type": "string", "description": "Price unit as a decimal string" }, "contract_address": { "type": "string", "description": "Contract address for the price token" } }, "required": ["contract_address", "unit"] }, "SaveDropEditsRequest": { "type": "object", "description": "Request to save Creator Studio drop edits", "properties": { "stages": { "type": "array", "description": "The drop's complete stage set, replacing any existing stages rather than merging with them. Exactly one stage must be `public_sale` and it must be first in this array. The presales that follow must be contiguous among themselves, each starting exactly when the previous presale ended, and the last must end exactly when the public stage starts. The first presale start time is not constrained. Array order is therefore not chronological: the public stage is listed first and runs last.", "items": { "$ref": "#/components/schemas/SaveDropEditsStageRequest" }, "maxItems": 2147483647, "minItems": 1 }, "max_supply": { "type": "string", "description": "Maximum supply for the drop as a decimal string" }, "creator_payout_address": { "type": "string", "description": "Creator payout address" }, "launch_date_pending": { "type": "boolean", "default": false, "description": "Set when saving a configuration the creator has not chosen a launch date for. Stage start and end times are still required, but they are held as a placeholder rather than a schedule: the whole stage set is shifted so the earliest stage opens at the Unix epoch, preserving each stage's duration and the gaps between them, and publishing the drop is refused until a launch date is set. Omit it to leave the drop scheduled; an explicit null is rejected." } }, "required": ["stages"] }, "SaveDropEditsStageRequest": { "type": "object", "description": "A drop stage for Creator Studio edits", "properties": { "uuid": { "type": "string", "description": "Stage UUID. Reuse an existing stage UUID to update that stage, or supply a new one to add a stage. Because `stages` replaces the whole set, omitting a stage deletes it." }, "stage_type": { "type": "string", "description": "Stage type. `public_sale` for the open stage, `signed_presale` for an allowlist stage. `merkle_presale` exists in the underlying enum but is rejected: no drop has ever used one and mints against such a stage fail.", "enum": ["public_sale", "signed_presale"], "example": "signed_presale" }, "start_time": { "type": "string", "format": "date-time", "description": "Stage start time", "example": "2024-01-01T00:00:00Z" }, "end_time": { "type": "string", "format": "date-time", "description": "Stage end time", "example": "2024-01-01T01:00:00Z" }, "price": { "$ref": "#/components/schemas/SaveDropEditsPriceRequest", "description": "Stage price" }, "max_total_mintable_by_wallet": { "type": "string", "description": "Maximum tokens mintable per wallet as a decimal string. Cumulative across stages rather than per stage, so this is a running total for the wallet. A wallet that has already reached a later stage's cap cannot mint on it." }, "max_token_supply_for_stage": { "type": "string", "description": "Maximum token supply for this stage as a decimal string" }, "label": { "type": "string", "description": "Stage label" }, "description": { "type": "string", "description": "Stage description" }, "allowlist_file_token": { "type": "string", "description": "Allowlist file token" } }, "required": [ "end_time", "max_total_mintable_by_wallet", "price", "stage_type", "start_time", "uuid" ] }, "PrerevealDropItemResponse": { "type": "object", "description": "Response body for saving a prereveal drop item", "properties": { "name": { "type": "string", "description": "Item name" }, "description": { "type": "string", "description": "Item description" }, "image_url": { "type": "string", "description": "Item image URL" }, "media_token": { "type": "string", "description": "Image media token" }, "media_type": { "type": "string", "description": "Item media type" } }, "required": ["image_url", "media_token", "name"] }, "SavePrerevealDropItemRequest": { "type": "object", "description": "Request body for saving a prereveal drop item", "properties": { "media_token": { "type": "string", "description": "Media token reference", "minLength": 1 }, "name": { "type": "string", "description": "Item name", "maxLength": 100, "minLength": 0 }, "description": { "type": "string", "description": "Item description" }, "media_type": { "type": "string", "description": "Media type" } }, "required": ["media_token", "name"] }, "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"] }, "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"] }, "SaveSelfMintDropItemRequest": { "type": "object", "description": "Request to create a SelfMint drop item", "properties": { "media_token": { "type": "string", "description": "Media token reference", "minLength": 1 }, "name": { "type": "string", "description": "Item name", "maxLength": 100, "minLength": 0 }, "supply": { "type": "string", "description": "Item supply as a decimal string", "minLength": 1 }, "description": { "type": "string", "description": "Item description", "maxLength": 2000, "minLength": 0 }, "external_url": { "type": "string", "description": "External URL", "maxLength": 1000, "minLength": 0 }, "animation_url": { "type": "string", "description": "Animated media for the item, alongside its image. Blank is treated as no animation, the same as omitting the field.", "maxLength": 1000, "minLength": 0 }, "traits": { "type": "array", "description": "Item traits", "items": { "$ref": "#/components/schemas/SelfMintDropItemTraitRequest" }, "maxItems": 40, "minItems": 0 } }, "required": ["media_token", "name", "supply"] }, "UploadDropItemMediaRequest": { "type": "object", "description": "Request body for uploading drop item media", "properties": { "filenames": { "type": "array", "description": "Filenames to upload", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } }, "required": ["filenames"] }, "SaveDropItemMediaResponse": { "type": "object", "description": "Response body for saving drop item media", "properties": { "success": { "type": "boolean", "description": "Whether the save succeeded" } }, "required": ["success"] }, "SaveDropItemMediaRequest": { "type": "object", "description": "Request body for saving drop item media", "properties": { "media_tokens": { "type": "array", "description": "Media tokens to save", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } }, "required": ["media_tokens"] }, "CrossChainDropMintResponse": { "type": "object", "description": "Ordered transactions required to complete a cross-chain mint", "properties": { "transactions": { "type": "array", "description": "Ordered list of transactions to sign and submit", "items": { "$ref": "#/components/schemas/SwapTransactionResponse" } }, "receipt_request": { "$ref": "#/components/schemas/TransactionReceiptRequest", "description": "Pass this object to POST /api/v2/transactions/receipt after submitting the transactions, and poll until the returned status is terminal" } }, "required": ["receipt_request", "transactions"] }, "CrossChainDropMintRequest": { "type": "object", "description": "Cross-chain mint request parameters", "properties": { "payer": { "type": "string", "description": "Wallet address that will sign and pay for the transactions", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "minLength": 1 }, "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 }, "payment": { "$ref": "#/components/schemas/CrossChainPaymentToken", "description": "Token used to pay for the mint" } }, "required": ["minter", "payer", "payment", "quantity"] }, "ValidateDropAllowlistResponse": { "type": "object", "description": "Response body for validating a drop allowlist", "properties": { "token": { "type": "string", "description": "Token for the validated allowlist file" } }, "required": ["token"] }, "ValidateDropAllowlistRequest": { "type": "object", "description": "Request body for validating a drop allowlist", "properties": { "allowlist_file_token": { "type": "string", "description": "Token for the uploaded allowlist file", "minLength": 1 } }, "required": ["allowlist_file_token"] }, "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": "600/h" }, "write": { "type": "string", "description": "Write rate limit", "example": "30/h" }, "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"] }, "ProfileSocialMutationResponse": { "type": "object", "properties": { "status": { "type": "string" } }, "required": ["status"] }, "LinkWalletSiwxRequest": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/JsonNode" }, "signature": { "type": "string", "maxLength": 20000, "minLength": 10 }, "chainArch": { "type": "string", "minLength": 1 } }, "required": ["chainArch", "message", "signature"] }, "WalletLinkResponse": { "type": "object", "properties": { "linkedWalletAddress": { "type": "string" } }, "required": ["linkedWalletAddress"] }, "ProposeAgentRelationshipRequestBody": { "type": "object", "properties": { "counterparty_address": { "type": "string" }, "caller_role": { "type": "string", "description": "Which side of the relationship the caller is on", "enum": ["AGENT", "OWNER"] } }, "required": ["caller_role", "counterparty_address"] }, "AgentRelationshipMutationResponse": { "type": "object", "properties": { "relation": { "$ref": "#/components/schemas/AgentRelationshipResponse" }, "created": { "type": "boolean" } }, "required": ["created", "relation"] }, "AgentRelationshipResponse": { "type": "object", "properties": { "agent_account_id": { "type": "string" }, "owner_account_id": { "type": "string" }, "status": { "type": "string" }, "awaiting_confirmation_from": { "type": "string" }, "created_at": { "type": "number", "format": "double", "description": "Unix timestamp in seconds, including fractional seconds" }, "confirmed_at": { "type": "number", "format": "double", "description": "Unix timestamp in seconds, including fractional seconds" } }, "required": [ "agent_account_id", "created_at", "owner_account_id", "status" ] }, "ConfirmAgentRelationshipRequestBody": { "type": "object", "properties": { "counterparty_account_id": { "type": "string", "description": "The other party's account id. Preferred over an address." }, "counterparty_address": { "type": "string", "description": "A wallet the other party has linked publicly, resolved to their account. Stops resolving once unlinked." }, "caller_role": { "type": "string", "description": "Which side of the relationship the caller is on", "enum": ["AGENT", "OWNER"] } }, "required": ["caller_role"] }, "UpdateProfileSettingsRequest": { "type": "object", "description": "Request body for updating profile settings", "properties": { "displayName": { "type": "string", "description": "Profile display name", "maxLength": 50, "minLength": 0 }, "bio": { "type": "string", "description": "Profile bio", "maxLength": 500, "minLength": 0 }, "externalUrl": { "type": "string", "description": "Profile external URL", "maxLength": 2048, "minLength": 0 }, "profileImageToken": { "type": "string", "description": "Profile image upload token" }, "bannerImageToken": { "type": "string", "description": "Banner image upload token" } } }, "UpdateProfileSettingsResponse": { "type": "object", "description": "Response for updating profile settings", "properties": { "displayName": { "type": "string", "description": "Display name" }, "bio": { "type": "string", "description": "Profile bio" }, "externalUrl": { "type": "string", "description": "Profile external URL" } } }, "ProfileShelfActionResponse": { "type": "object", "description": "Response body for a profile shelf action", "properties": { "success": { "type": "boolean" } }, "required": ["success"] }, "ReorderProfileShelvesRequest": { "type": "object", "description": "Request body for reordering profile shelves", "properties": { "shelf_ids": { "type": "array", "description": "Ordered shelf IDs", "items": { "type": "string" }, "maxItems": 2147483647, "minItems": 1 } }, "required": ["shelf_ids"] }, "ProfileShelfItemUpdateRequest": { "type": "object", "description": "A shelf item entry that can include an optional description", "properties": { "item": { "$ref": "#/components/schemas/ProfileShelfItemRequest" }, "description": { "type": "string", "description": "Optional item description", "maxLength": 500, "minLength": 0 } }, "required": ["item"] }, "UpdateProfileShelfRequest": { "type": "object", "description": "Request body for updating a profile shelf", "properties": { "title": { "type": "string", "description": "Shelf title", "maxLength": 100, "minLength": 1 }, "description": { "type": "string", "description": "Shelf description", "maxLength": 500, "minLength": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileShelfItemUpdateRequest" }, "maxItems": 50, "minItems": 1 }, "icon": { "type": "string", "description": "Shelf icon" }, "view": { "type": "string", "description": "Shelf view" }, "single_item_shelf_side": { "type": "string", "description": "Single-item shelf side" } } }, "DropItemAttributeResponse": { "type": "object", "description": "Response body for a drop item attribute", "properties": { "traitType": { "type": "string", "description": "Trait type" }, "value": { "type": "string", "description": "Trait value" } }, "required": ["traitType", "value"] }, "DropItemResponse": { "type": "object", "description": "Response body for a drop item", "properties": { "token_id": { "type": "string", "description": "Token ID" }, "name": { "type": "string", "description": "Item name" }, "description": { "type": "string", "description": "Item description" }, "image_url": { "type": "string", "description": "Item image URL" }, "attributes": { "type": "array", "description": "Item attributes", "items": { "$ref": "#/components/schemas/DropItemAttributeResponse" } }, "media_token": { "type": "string", "description": "Image media token" }, "contract_standard": { "type": "string", "description": "Contract standard" }, "external_url": { "type": "string", "description": "External URL" }, "animation_url": { "type": "string", "description": "Animated media for the item, alongside its image" }, "chain": { "type": "string", "description": "Chain identifier" }, "contract_address": { "type": "string", "description": "Contract address" } }, "required": [ "attributes", "chain", "contract_address", "contract_standard", "image_url", "media_token", "token_id" ] }, "UpdateDropItemRequest": { "type": "object", "description": "Request body for updating a drop item", "properties": { "media_token": { "type": "string", "description": "Media token reference", "minLength": 1 }, "name": { "type": "string", "description": "Item name", "maxLength": 100, "minLength": 0 }, "external_url": { "type": "string", "description": "External URL" }, "animation_url": { "type": "string", "description": "Animated media for the item, alongside its image. Omit to leave the stored value alone; send an empty string to remove it.", "maxLength": 1000, "minLength": 0 }, "description": { "type": "string", "description": "Item description" }, "traits": { "type": "array", "description": "Traits to apply", "items": { "$ref": "#/components/schemas/SelfMintDropItemTraitRequest" } } }, "required": ["media_token", "name"] }, "ModifyCollectionResponse": { "type": "object", "description": "Response for modifying collection metadata", "properties": { "success": { "type": "boolean", "description": "Whether the collection metadata was modified successfully" } }, "required": ["success"] }, "ModifyCollectionCreatorFeeRequest": { "type": "object", "description": "A creator fee entry for collection edits", "properties": { "basis_points": { "type": "integer", "format": "int32", "description": "Creator fee basis points", "maximum": 1000, "minimum": 0 }, "address": { "type": "string", "description": "Creator fee recipient address" } }, "required": ["address", "basis_points"] }, "ModifyCollectionRequest": { "type": "object", "description": "Request body for modifying collection metadata", "properties": { "name": { "type": "string", "description": "Collection name", "maxLength": 100, "minLength": 1, "pattern": "^[\\x20-\\x7E]+$" }, "description": { "type": "string", "description": "Collection description", "maxLength": 1000, "minLength": 0 }, "logo_image_token": { "type": "string", "description": "Logo image token" }, "banner_image_token": { "type": "string", "description": "Banner image token" }, "category": { "type": "string", "description": "Collection category" }, "slug": { "type": "string", "description": "New collection slug", "maxLength": 50, "minLength": 1, "pattern": "^[a-z0-9-]+$" }, "is_nsfw": { "type": "boolean", "description": "Whether the collection is NSFW" }, "is_trait_offers_enabled": { "type": "boolean", "description": "Whether trait offers are enabled" }, "is_rarity_disabled": { "type": "boolean", "description": "Whether rarity is disabled" }, "authorized_editors": { "type": "array", "description": "Authorized editors", "items": { "type": "string" }, "maxItems": 10, "minItems": 0 }, "external_url": { "type": "string", "description": "Collection external URL", "pattern": "^$|^(https?)://.+$" }, "telegram_url": { "type": "string", "description": "Collection Telegram URL", "pattern": "^$|^(https?)://.+$" }, "medium_username": { "type": "string", "description": "Medium username", "maxLength": 50, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "creator_fees": { "type": "array", "description": "Creator fees", "items": { "$ref": "#/components/schemas/ModifyCollectionCreatorFeeRequest" }, "maxItems": 5, "minItems": 0 }, "buyer_side_creator_fee_enabled": { "type": "boolean", "description": "Whether buyer-side creator fees are enabled" }, "buyer_side_creator_fee_basis_points": { "type": "integer", "format": "int32", "description": "Buyer-side creator fee basis points", "maximum": 1000, "minimum": 0 }, "buyer_side_creator_fee_recipient": { "type": "string", "description": "Buyer-side creator fee recipient" } } }, "SetCollectionVisibilityResponse": { "type": "object", "description": "Response body for setting collection visibility", "properties": { "success": { "type": "boolean", "description": "Whether the visibility update succeeded" } }, "required": ["success"] }, "SetCollectionVisibilityRequest": { "type": "object", "description": "Request body for setting collection visibility", "properties": { "hidden": { "type": "boolean", "description": "Whether the collection should be hidden" } }, "required": ["hidden"] }, "UpdateCollectionMetadataResponse": { "type": "object", "description": "Response for updating collection metadata", "properties": { "success": { "type": "boolean", "description": "Whether the metadata update succeeded" } }, "required": ["success"] }, "AboutMetadataRequest": { "type": "object", "description": "Collection about content", "properties": { "preview_media": { "type": "array", "description": "Preview media", "items": { "$ref": "#/components/schemas/MediaInputRequest" }, "maxItems": 10, "minItems": 0 }, "sections": { "type": "array", "description": "About sections", "items": { "$ref": "#/components/schemas/AboutSectionRequest" }, "maxItems": 10, "minItems": 0 } } }, "AboutSectionRequest": { "type": "object", "description": "A section within collection about content", "properties": { "id": { "type": "string", "description": "Section ID" }, "title": { "type": "string", "description": "Section title", "maxLength": 100, "minLength": 1 }, "description": { "type": "string", "description": "Section description", "maxLength": 1000, "minLength": 1 }, "media": { "type": "array", "description": "Section media", "items": { "$ref": "#/components/schemas/MediaInputRequest" } } }, "required": ["description", "title"] }, "ContentBlockModuleRequest": { "type": "object", "description": "A content block overview module", "properties": { "index": { "type": "integer", "format": "int32", "description": "Module index" }, "id": { "type": "string", "description": "Module ID" }, "title": { "type": "string", "description": "Module title", "maxLength": 100, "minLength": 0 }, "description": { "type": "string", "description": "Module description", "maxLength": 1000, "minLength": 0 }, "sections": { "type": "array", "description": "Module sections", "items": { "$ref": "#/components/schemas/ContentBlockSectionRequest" } } }, "required": ["index"] }, "ContentBlockSectionRequest": { "type": "object", "description": "A content block section", "properties": { "id": { "type": "string", "description": "Section ID" }, "title": { "type": "string", "description": "Section title", "maxLength": 100, "minLength": 0 }, "description": { "type": "string", "description": "Section description", "maxLength": 1000, "minLength": 0 }, "external_link": { "$ref": "#/components/schemas/LinkRequest", "description": "Section external link" }, "media": { "$ref": "#/components/schemas/MediaInputRequest", "description": "Section media" }, "module_type": { "type": "string", "description": "Section module type", "minLength": 1 }, "date": { "type": "string", "description": "Section date" }, "collection_slug": { "type": "string", "description": "Collection slug" }, "token_id": { "type": "string", "description": "Token ID" } }, "required": ["module_type"] }, "FaqBlockModuleRequest": { "type": "object", "description": "A FAQ overview module", "properties": { "index": { "type": "integer", "format": "int32", "description": "Module index" }, "hidden": { "type": "boolean", "description": "Whether the module is hidden" }, "title": { "type": "string", "description": "Module title", "maxLength": 100, "minLength": 0 }, "description": { "type": "string", "description": "Module description", "maxLength": 1000, "minLength": 0 }, "sections": { "type": "array", "description": "Module sections", "items": { "$ref": "#/components/schemas/FaqSectionRequest" } } }, "required": ["index"] }, "FaqSectionRequest": { "type": "object", "description": "A FAQ section", "properties": { "id": { "type": "string", "description": "Section ID" }, "question": { "type": "string", "description": "Question", "maxLength": 200, "minLength": 0 }, "answer": { "type": "string", "description": "Answer", "maxLength": 2000, "minLength": 0 } }, "required": ["answer", "question"] }, "HeroMetadataRequest": { "type": "object", "description": "Collection hero content", "properties": { "desktop_hero_media": { "$ref": "#/components/schemas/MediaInputRequest", "description": "Desktop hero media" }, "mobile_hero_media": { "$ref": "#/components/schemas/MediaInputRequest", "description": "Mobile hero media" } } }, "ImageMediaRequest": { "type": "object", "description": "An image media input", "properties": { "token": { "type": "string", "description": "Image token", "minLength": 1 } }, "required": ["token"] }, "LinkRequest": { "type": "object", "description": "A link input", "properties": { "href": { "type": "string", "description": "Link URL", "minLength": 1, "pattern": "^(https?)://.+$" }, "label": { "type": "string", "description": "Link label", "maxLength": 100, "minLength": 0 } }, "required": ["href", "label"] }, "MediaInputRequest": { "type": "object", "description": "A generic media input", "properties": { "image": { "$ref": "#/components/schemas/ImageMediaRequest", "description": "Image media" }, "video": { "$ref": "#/components/schemas/VideoMediaRequest", "description": "Video media" } } }, "NarrativeModuleRequest": { "type": "object", "description": "A narrative overview module", "properties": { "id": { "type": "string", "description": "Module ID" }, "index": { "type": "integer", "format": "int32", "description": "Module index" }, "title": { "type": "string", "description": "Module title", "maxLength": 100, "minLength": 0 }, "description": { "type": "string", "description": "Module description", "maxLength": 1000, "minLength": 0 }, "media": { "type": "array", "description": "Module media", "items": { "$ref": "#/components/schemas/MediaInputRequest" } }, "horizontal_text_position": { "type": "string", "description": "Horizontal text position", "pattern": "(?i)^(left|center|right)$" }, "vertical_text_position": { "type": "string", "description": "Vertical text position", "pattern": "(?i)^(top|center|bottom)$" }, "desktop_background_media": { "$ref": "#/components/schemas/MediaInputRequest", "description": "Desktop background media" }, "mobile_background_media": { "$ref": "#/components/schemas/MediaInputRequest", "description": "Mobile background media" }, "variant": { "type": "string", "description": "Module variant", "pattern": "(?i)^(text|background|text_and_background|text_and_media)$" }, "background_image": { "$ref": "#/components/schemas/ImageMediaRequest", "description": "Background image" }, "background_media": { "$ref": "#/components/schemas/MediaInputRequest", "description": "Background media" } }, "required": ["description", "index", "title"] }, "OverviewMetadataRequest": { "type": "object", "description": "Collection overview content", "properties": { "modules": { "$ref": "#/components/schemas/OverviewModuleRequest", "description": "Overview modules" } }, "required": ["modules"] }, "OverviewModuleRequest": { "type": "object", "description": "Overview modules", "properties": { "narrative": { "type": "array", "description": "Narrative modules", "items": { "$ref": "#/components/schemas/NarrativeModuleRequest" }, "maxItems": 50, "minItems": 0 }, "content_block": { "type": "array", "description": "Content block modules", "items": { "$ref": "#/components/schemas/ContentBlockModuleRequest" }, "maxItems": 10, "minItems": 0 }, "team": { "type": "array", "description": "Team modules", "items": { "$ref": "#/components/schemas/TeamBlockModuleRequest" }, "maxItems": 5, "minItems": 0 }, "faq": { "type": "array", "description": "FAQ modules", "items": { "$ref": "#/components/schemas/FaqBlockModuleRequest" }, "maxItems": 5, "minItems": 0 } } }, "TeamBlockModuleRequest": { "type": "object", "description": "A team overview module", "properties": { "index": { "type": "integer", "format": "int32", "description": "Module index" }, "hidden": { "type": "boolean", "description": "Whether the module is hidden" }, "title": { "type": "string", "description": "Module title", "maxLength": 100, "minLength": 0 }, "description": { "type": "string", "description": "Module description", "maxLength": 1000, "minLength": 0 }, "sections": { "type": "array", "description": "Module sections", "items": { "$ref": "#/components/schemas/TeamSectionRequest" } } }, "required": ["index"] }, "TeamSectionRequest": { "type": "object", "description": "A team section", "properties": { "id": { "type": "string", "description": "Section ID" }, "name": { "type": "string", "description": "Section name", "maxLength": 100, "minLength": 0 }, "title": { "type": "string", "description": "Section title", "maxLength": 100, "minLength": 0 }, "bio": { "type": "string", "description": "Section bio", "maxLength": 500, "minLength": 0 }, "website_url": { "type": "string", "description": "Website URL", "pattern": "^$|^(https?)://.+$" }, "twitter_url": { "type": "string", "description": "Twitter URL", "pattern": "^$|^(https?)://.+$" }, "instagram_url": { "type": "string", "description": "Instagram URL", "pattern": "^$|^(https?)://.+$" }, "media": { "type": "array", "description": "Section media", "items": { "$ref": "#/components/schemas/MediaInputRequest" } } }, "required": ["bio", "name", "title"] }, "UpdateCollectionMetadataRequest": { "type": "object", "description": "Request body for updating collection metadata", "properties": { "about": { "$ref": "#/components/schemas/AboutMetadataRequest", "description": "Collection about content" }, "hero": { "$ref": "#/components/schemas/HeroMetadataRequest", "description": "Collection hero media" }, "overview": { "$ref": "#/components/schemas/OverviewMetadataRequest", "description": "Collection overview content" }, "logo_image_token": { "type": "string", "description": "Collection logo image token" } } }, "VideoMediaRequest": { "type": "object", "description": "A video media input", "properties": { "token": { "type": "string", "description": "Video token", "minLength": 1 }, "enable_static_video": { "type": "boolean", "description": "Enable static video" } }, "required": ["token"] }, "TraitFloorResponse": { "type": "object", "description": "Floor price for one trait value in one payment currency", "properties": { "trait_type": { "type": "string", "description": "Trait category, for example Background" }, "value": { "type": "string", "description": "Trait value, for example Purple" }, "floor_price": { "type": "number", "format": "double", "description": "Price of the cheapest listing carrying this trait value, across every marketplace OpenSea aggregates. This matches the basis of the collection's floor_price and may be below the cheapest listing fulfillable through this API." }, "payment_token_symbol": { "type": "string", "description": "Payment token this floor is denominated in, on the response's chain. Floors are not converted to a common currency, so a trait value listed in more than one currency appears once per currency and prices are only comparable within the same symbol." } }, "required": [ "floor_price", "payment_token_symbol", "trait_type", "value" ] }, "TraitFloorsResponse": { "type": "object", "description": "Floor price per trait value for a collection", "properties": { "chain": { "type": "string", "description": "Chain every floor in this response is denominated on. A collection lives on one chain, so the payment token is identified by this plus 'payment_token_symbol'." }, "floors": { "type": "array", "description": "One entry per text trait value and payment currency that has at least one active listing, ordered by trait type, then value, then price. Numeric traits are not enumerated here; see GET /api/v2/traits/{slug} for their min/max range.", "items": { "$ref": "#/components/schemas/TraitFloorResponse" } } }, "required": ["chain", "floors"] }, "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" }, "display_name": { "type": "string" }, "health_status": { "type": "string" }, "access_tier": { "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" }, "image_url": { "type": "string" }, "featured_image_url": { "type": "string" }, "pricing_recipients": { "type": "array", "items": { "$ref": "#/components/schemas/ToolPricingRecipientResponse" } } }, "required": [ "access_tier", "created_at", "creator", "display_name", "health_status", "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" }, "asset_symbol": { "type": "string" }, "asset_decimals": { "type": "integer", "format": "int32" }, "asset_image_url": { "type": "string" }, "amount_per_call_usd": { "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"] }, "ToolActivityEventResponse": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "attribution": { "type": "string" }, "paid": { "type": "boolean" }, "caller_address": { "type": "string" }, "seller_address": { "type": "string" }, "timestamp": { "type": "string" }, "amount": { "type": "string" }, "asset": { "type": "string" }, "chain_id": { "type": "integer", "format": "int64" }, "tx_hash": { "type": "string" }, "candidate_tool_slugs": { "type": "array", "items": { "type": "string" } } }, "required": [ "attribution", "caller_address", "candidate_tool_slugs", "id", "paid", "timestamp", "type" ] }, "ToolActivityPaginatedResponse": { "type": "object", "properties": { "activity": { "type": "array", "items": { "$ref": "#/components/schemas/ToolActivityEventResponse" } }, "next": { "type": "string" } }, "required": ["activity"] }, "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" }, "display_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" }, "image_url": { "type": "string" }, "featured_image_url": { "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", "display_name", "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": "USDC" }, "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" }, "holders_count": { "type": "integer", "format": "int64", "description": "Number of token holders" }, "is_verified": { "type": "boolean", "description": "Whether OpenSea has verified the token" }, "created_at": { "type": "number", "format": "double", "description": "When OpenSea first recorded the token" }, "genesis_date": { "type": "number", "format": "double", "description": "Earliest known onchain activity for the token" } }, "required": [ "address", "chain", "decimals", "is_verified", "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": "USDC" }, "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" ] }, "SavedToolsPaginatedResponse": { "type": "object", "description": "A page of tools saved by the authenticated account", "properties": { "tools": { "type": "array", "items": { "$ref": "#/components/schemas/SavedToolResponse" } }, "next": { "type": "string", "description": "Cursor for the next page, or null when this is the last page" } }, "required": ["tools"] }, "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" } }, "decimals": { "type": "integer", "format": "int32" } }, "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": "Ceiling on the wallet's mints for the whole drop, not this stage alone. Cumulative: SeaDrop checks it against the wallet's lifetime minted count on the contract, so caps on different stages do not add together. Matches max_total_mintable_by_wallet on the eligibility response." }, "allowlist_wallet_count": { "type": "integer", "format": "int32", "description": "Wallets on this stage's allowlist when the drop service last synced it. Null when the stage has no synced allowlist, which includes every public sale stage; that is distinct from 0, which means the allowlist is empty. Equivalent to allowlistMemberCount on the GraphQL DropStage.", "example": 1200 } }, "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" ] }, "DropEligibilityResponse": { "type": "object", "description": "Drop eligibility results for the authenticated wallet", "properties": { "stages": { "type": "array", "description": "Per-stage eligibility results", "items": { "$ref": "#/components/schemas/DropStageEligibilityResponse" } } }, "required": ["stages"] }, "DropStageEligibilityResponse": { "type": "object", "description": "Drop stage eligibility result for the authenticated wallet", "properties": { "stage_uuid": { "type": "string", "format": "uuid", "description": "Drop stage UUID" }, "is_eligible": { "type": "boolean", "description": "Whether the wallet is eligible for this stage" }, "price": { "type": "string", "description": "Mint price per token in wei (decimal string)" }, "max_total_mintable_by_wallet": { "type": "string", "description": "Ceiling on the wallet's mints for the whole drop, all token ids included, as a decimal string. Cumulative rather than per stage: SeaDrop checks it against the wallet's lifetime minted count on the contract, so caps on different stages do not add together, and a wallet that has already reached a later stage's cap cannot mint on it." }, "max_total_mintable_by_wallet_per_token": { "type": "string", "description": "The same ceiling for a single token id (ERC-1155), as a decimal string. Also a lifetime total for that token id rather than a per-stage allowance." } }, "required": ["is_eligible", "stage_uuid"] }, "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" }, "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", "description": "Window the stats cover", "example": "one_day" }, "volume": { "type": "number", "format": "double", "description": "Trading volume over the interval, denominated in the currency named by volume_symbol" }, "volume_symbol": { "type": "string", "description": "Currency that volume is denominated in. Empty when the conversion rate was unavailable and the unit could not be determined.", "example": "ETH" }, "sales": { "type": "integer", "format": "int32", "description": "Number of sales over the interval" } }, "required": ["interval", "sales", "volume", "volume_symbol"] }, "Total": { "type": "object", "properties": { "volume": { "type": "number", "format": "double", "description": "All-time trading volume, denominated in the currency named by volume_symbol. This is not necessarily the currency of floor_price." }, "volume_symbol": { "type": "string", "description": "Currency that volume is denominated in. Empty when the conversion rate was unavailable and the unit could not be determined.", "example": "ETH" }, "sales": { "type": "integer", "format": "int32", "description": "All-time number of sales" }, "num_owners": { "type": "integer", "format": "int64", "description": "Number of distinct addresses holding an item in the collection" }, "floor_price": { "type": "number", "format": "double", "description": "Price of the cheapest current listing, denominated in the currency named by floor_price_symbol. 0 when the collection has no listing." }, "floor_price_symbol": { "type": "string", "description": "Currency that floor_price is denominated in. Empty when there is no listing.", "example": "ETH" } }, "required": [ "floor_price", "floor_price_symbol", "num_owners", "sales", "volume", "volume_symbol" ] }, "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", "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": "number", "format": "double", "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": "number", "format": "double", "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": "number", "format": "double", "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": "number", "format": "double", "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" ] }, "TokenActivityStatsResponse": { "type": "object", "description": "Windowed trading activity for a token", "properties": { "chain": { "type": "string", "description": "Blockchain slug", "example": "base" }, "address": { "type": "string", "description": "Token contract address" }, "computed_at": { "type": "string", "format": "date-time", "description": "End time of the oldest returned aggregation window, or null when no window is returned" }, "windows": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TokenActivityWindowStatsResponse" }, "description": "Trading activity keyed by requested window. A requested key is omitted when the token has no swaps in that window; an omitted key means zero trades." } }, "required": ["address", "chain", "windows"] }, "TokenActivityWindowStatsResponse": { "type": "object", "description": "Trading activity within one time window", "properties": { "trades": { "type": "integer", "format": "int64", "description": "Swap transaction count" }, "volume_usd": { "type": "string", "description": "Total buy and sell volume in USD", "example": 710410.75, "pattern": "^[0-9]+(?:\\.[0-9]+)?$" }, "average_trade_usd": { "type": "string", "description": "Average USD volume per trade", "example": 232.92, "pattern": "^[0-9]+(?:\\.[0-9]+)?$" }, "unique_buyer_count": { "type": "integer", "format": "int64", "description": "Distinct wallets that bought this token during the window. Only populated for the 1h and 24h windows; always null for 5m and 4h, which have no materialized source. Null also means the value is unavailable or not yet authoritative for this token, which remains a valid runtime state. Zero is an authoritative zero, so do not treat null as 0.", "example": 412 }, "unique_seller_count": { "type": "integer", "format": "int64", "description": "Distinct wallets that sold this token during the window. Only populated for the 1h and 24h windows; always null for 5m and 4h, which have no materialized source. Null also means the value is unavailable or not yet authoritative for this token, which remains a valid runtime state. Zero is an authoritative zero, so do not treat null as 0.", "example": 377 } }, "required": ["average_trade_usd", "trades", "volume_usd"] }, "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": "number", "format": "double", "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" }, "display_name": { "type": "string" }, "ens_name": { "type": "string" }, "is_verified": { "type": "boolean" }, "is_agent": { "type": "boolean", "description": "Whether this account has declared itself an agent. Self-declared and not OpenSea verification, and the declaration on its own confers nothing: see GET /api/v2/accounts/{address_or_username}/agent-relationships for the ownership relationship, which is likewise a declaration rather than an authorization." }, "follower_count": { "type": "integer", "format": "int64" }, "following_count": { "type": "integer", "format": "int64" }, "nft_pfp": { "$ref": "#/components/schemas/NftPfpResponse" }, "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" } }, "required": [ "address", "bio", "follower_count", "following_count", "is_agent", "is_verified", "joined_date", "social_media_accounts" ] }, "SocialMediaAccount": { "type": "object", "properties": { "platform": { "type": "string" }, "username": { "type": "string" } }, "required": ["platform", "username"] }, "ProfileRelationshipResponse": { "type": "object", "properties": { "is_following": { "type": "boolean" }, "is_watching": { "type": "boolean" } }, "required": ["is_following", "is_watching"] }, "SocialProfilePageResponse": { "type": "object", "properties": { "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/SocialProfileSummaryResponse" } }, "next": { "type": "string" } }, "required": ["profiles"] }, "SocialProfileSummaryResponse": { "type": "object", "properties": { "address": { "type": "string" }, "username": { "type": "string" }, "display_name": { "type": "string" }, "profile_image_url": { "type": "string" }, "is_verified": { "type": "boolean" }, "follower_count": { "type": "integer", "format": "int64" }, "nft_pfp": { "$ref": "#/components/schemas/NftPfpResponse" }, "is_following": { "type": "boolean" }, "is_watching": { "type": "boolean" } }, "required": [ "address", "follower_count", "is_following", "is_verified", "is_watching" ] }, "AgentProfileRelationshipsResponse": { "type": "object", "description": "Public agent ownership relationships for a profile", "properties": { "agent_owner": { "$ref": "#/components/schemas/AgentProfileSummaryResponse", "description": "The account confirmed to own this one as its agent. Null when there is none, which is ordinary rather than exceptional: an agent nobody declared is a valid agent account. Only a relationship both accounts confirmed appears here." }, "agents": { "type": "array", "description": "The accounts this one is the confirmed owner of, newest relationship first. Empty when there are none.", "items": { "$ref": "#/components/schemas/AgentProfileSummaryResponse" } } }, "required": ["agents"] }, "AgentProfileSummaryResponse": { "type": "object", "description": "Compact public profile summary for an agent relationship", "properties": { "address": { "type": "string" }, "username": { "type": "string" }, "display_name": { "type": "string" }, "profile_image_url": { "type": "string" }, "is_verified": { "type": "boolean" } }, "required": ["address", "is_verified"] }, "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"] }, "AgentRelationshipListResponse": { "type": "object", "properties": { "relationships": { "type": "array", "items": { "$ref": "#/components/schemas/AgentRelationshipResponse" } } }, "required": ["relationships"] }, "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": "USDC" }, "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" ] }, "TokenAccountActivityPaginatedResponse": { "type": "object", "description": "Paginated list of account token activity events", "properties": { "activities": { "type": "array", "description": "List of token activity events", "items": { "$ref": "#/components/schemas/TokenAccountActivityResponse" } }, "next": { "type": "string", "description": "Cursor for the next page of results" } }, "required": ["activities"] }, "TokenAccountActivityResponse": { "type": "object", "description": "A fungible token activity event for an account", "properties": { "type": { "type": "string", "description": "Type of activity", "enum": ["send", "receive", "swap", "wrap", "unwrap"] }, "chain": { "type": "string", "description": "Blockchain the activity occurred on" }, "from": { "type": "string", "description": "Address that initiated the activity" }, "to": { "type": "string", "description": "Recipient address for transfers" }, "token": { "$ref": "#/components/schemas/TokenAmountResponse", "description": "Token amount for transfers" }, "from_token": { "$ref": "#/components/schemas/TokenAmountResponse", "description": "Token sold/swapped from" }, "to_token": { "$ref": "#/components/schemas/TokenAmountResponse", "description": "Token received/swapped to" }, "swap_protocol": { "type": "string", "description": "Swap protocol used" }, "transaction_hash": { "type": "string", "description": "Transaction hash" }, "user_op_hash": { "type": "string", "description": "User operation hash (for account abstraction)" }, "timestamp": { "type": "number", "format": "double", "description": "Timestamp of the activity" } }, "required": ["chain", "from", "timestamp", "transaction_hash", "type"] }, "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": "number", "format": "double", "description": "Timestamp of the data point", "example": 1777334400 }, "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"] }, "WalletPnlResponse": { "type": "object", "description": "Aggregated realized and unrealized trading P&L across all currencies held by a wallet", "properties": { "realized_pnl_usd": { "type": "string", "description": "Realized P&L in USD from closed positions", "example": "+1840.25" }, "unrealized_pnl_usd": { "type": "string", "description": "Unrealized P&L in USD from open positions", "example": -320.1 }, "total_pnl_usd": { "type": "string", "description": "Total P&L in USD (realized + unrealized)", "example": "+1520.15" }, "net_invested_usd": { "type": "string", "description": "Net amount invested in USD", "example": 12500 }, "current_value_usd": { "type": "string", "description": "Current USD value of the wallet's open positions (net_invested + unrealized P&L). Provides a visible anchor for the unrealized figure.", "example": 12179.9 }, "return_percentage": { "type": "string", "description": "Total return as a signed percentage in percent units (e.g. +12.16 means +12.16%, -8.40 means -8.40%). Not a 0-1 ratio.", "example": "+12.16" } }, "required": [ "current_value_usd", "net_invested_usd", "realized_pnl_usd", "return_percentage", "total_pnl_usd", "unrealized_pnl_usd" ] }, "PositionTokenTransferResponse": { "type": "object", "description": "A single token transfer that contributed to a wallet's position in a currency. Combine `direction` and `transfer_type` to distinguish zero-cost acquisitions (e.g. AIRDROP, CEX_TRANSFER) from buys (e.g. SWAP_BUY).", "properties": { "direction": { "type": "string", "description": "Transfer direction relative to the wallet (e.g. IN, OUT).", "example": "IN" }, "quantity_raw": { "type": "string", "description": "Raw token quantity transferred, in token base units, as a string to preserve precision.", "example": 1500000000 }, "price_usd": { "type": "string", "description": "Token price in USD at the time of the transfer, or null if unknown.", "example": 0.0425 }, "value_usd": { "type": "string", "description": "USD value of the transfer, or null if unknown.", "example": 63.75 }, "tx_signature": { "type": "string", "description": "Transaction hash/signature of the transfer.", "example": "0xabc123" }, "block_time": { "type": "number", "format": "double", "description": "Block time of the transfer, or null if unknown.", "example": 1777334400 }, "transfer_type": { "type": "string", "description": "Type of transfer, used to distinguish zero-cost acquisitions (e.g. AIRDROP, CEX_TRANSFER) from buys/sells (e.g. SWAP_BUY, SWAP_SELL). Null if unclassified.", "example": "SWAP_BUY" } }, "required": ["direction", "quantity_raw", "tx_signature"] }, "PositionTokenTransfersResponse": { "type": "object", "description": "A page of token transfers contributing to a wallet's position in a currency", "properties": { "token_transfers": { "type": "array", "description": "The token transfers for this page", "items": { "$ref": "#/components/schemas/PositionTokenTransferResponse" } }, "total_count": { "type": "integer", "format": "int32", "description": "Total number of token transfers for the position across all pages", "example": 17 }, "next": { "type": "string", "description": "Cursor for the next page of results, or null if there are no more pages" } }, "required": ["token_transfers", "total_count"] }, "ClosedPositionResponse": { "type": "object", "description": "A single realized (closed) trading position. Realized P&L and cost basis are computed via FIFO (first-in, first-out) lot matching.", "properties": { "currency": { "$ref": "#/components/schemas/TokenBaseResponse", "description": "The currency that was traded. Null if the currency is no longer surfaced (e.g. under trust & safety enforcement)." }, "realized_pnl_usd": { "type": "string", "description": "Realized profit or loss in USD for this position (FIFO). Signed.", "example": "+1840.25" }, "return_percentage": { "type": "string", "description": "Realized return as a signed percentage in percent units (e.g. +12.16 means +12.16%). Not a 0-1 ratio.", "example": "+12.16" }, "total_proceeds_usd": { "type": "string", "description": "Total USD proceeds from the sells that closed this position.", "example": 5200 }, "total_cost_basis_usd": { "type": "string", "description": "Total USD cost basis of the tokens sold, via FIFO lot matching.", "example": 3359.75 }, "avg_cost_per_token_usd": { "type": "string", "description": "Average cost per token in USD (FIFO).", "example": 0.0425 }, "closed_at": { "type": "number", "format": "double", "description": "When the position was closed (last sell). Null if unknown.", "example": 1777334400 }, "is_opensea_trade": { "type": "boolean", "description": "Whether this was a round-trip OpenSea trade (bought and sold on OpenSea)." }, "first_acquired_at": { "type": "number", "format": "double", "description": "When the tokens in this position were first acquired. Null if unknown.", "example": 1768435200 } }, "required": [ "avg_cost_per_token_usd", "is_opensea_trade", "realized_pnl_usd", "return_percentage", "total_cost_basis_usd", "total_proceeds_usd" ] }, "ClosedPositionsResponse": { "type": "object", "description": "A page of a wallet's closed (realized) trading positions", "properties": { "closed_positions": { "type": "array", "description": "The closed positions for this page", "items": { "$ref": "#/components/schemas/ClosedPositionResponse" } }, "total_count": { "type": "integer", "format": "int32", "description": "Total number of closed positions for the wallet across all pages", "example": 42 }, "next": { "type": "string", "description": "Cursor for the next page of results, or null if there are no more pages" } }, "required": ["closed_positions", "total_count"] }, "PerpetualFutureBaseResponse": { "type": "object", "description": "Common perpetual future identity fields shared across perpetual responses", "properties": { "id": { "type": "string", "description": "The perpetual future ID" }, "name": { "type": "string", "description": "The display name of the perpetual future" }, "symbol": { "type": "string", "description": "The perpetual future symbol" }, "image_url": { "type": "string", "description": "URL of the perpetual future image" }, "description": { "type": "string", "description": "Description of the perpetual future" }, "created_at": { "type": "number", "format": "double", "description": "Created timestamp" }, "chain": { "type": "string", "description": "Chain identifier" }, "contract_address": { "type": "string", "description": "Contract address" }, "max_leverage": { "type": "integer", "format": "int32", "description": "Maximum leverage" }, "decimals": { "type": "integer", "format": "int32", "description": "Decimal places" }, "asset_id": { "type": "string", "description": "Asset ID" }, "version": { "type": "integer", "format": "int64", "description": "Version" }, "categories": { "type": "array", "description": "Categories", "items": { "type": "string" } }, "market": { "type": "string", "description": "Market" } }, "required": [ "asset_id", "categories", "chain", "contract_address", "decimals", "id", "max_leverage", "name", "symbol", "version" ] }, "PerpetualFuturePaginatedResponse": { "type": "object", "description": "Paginated list of perpetual futures", "properties": { "perpetuals": { "type": "array", "description": "List of perpetual futures", "items": { "$ref": "#/components/schemas/PerpetualFutureResponse" } }, "next": { "type": "string", "description": "Cursor for the next page of results" } }, "required": ["perpetuals"] }, "PerpetualFutureResponse": { "type": "object", "description": "A perpetual future", "properties": { "id": { "type": "string", "description": "The perpetual future ID" }, "name": { "type": "string", "description": "The display name of the perpetual future" }, "symbol": { "type": "string", "description": "The perpetual future symbol" }, "image_url": { "type": "string", "description": "URL of the perpetual future image" }, "description": { "type": "string", "description": "Description of the perpetual future" }, "created_at": { "type": "number", "format": "double", "description": "Created timestamp" }, "chain": { "type": "string", "description": "Chain identifier" }, "contract_address": { "type": "string", "description": "Contract address" }, "max_leverage": { "type": "integer", "format": "int32", "description": "Maximum leverage" }, "decimals": { "type": "integer", "format": "int32", "description": "Decimal places" }, "asset_id": { "type": "string", "description": "Asset ID" }, "version": { "type": "integer", "format": "int64", "description": "Version" }, "categories": { "type": "array", "description": "Categories", "items": { "type": "string" } }, "market": { "type": "string", "description": "Market" }, "stats": { "$ref": "#/components/schemas/PerpetualFutureStatsResponse", "description": "Market statistics" } }, "required": [ "asset_id", "categories", "chain", "contract_address", "decimals", "id", "max_leverage", "name", "symbol", "version" ] }, "PerpetualFutureStatsResponse": { "type": "object", "description": "Market statistics for a perpetual future", "properties": { "price_usd": { "type": "number", "description": "Price in USD" }, "price_change_24h": { "type": "number", "format": "float", "description": "24-hour price change percentage" }, "volume_24h": { "type": "number", "description": "24-hour volume in USD" }, "mark_price": { "type": "number", "description": "Mark price" }, "oracle_price": { "type": "number", "description": "Oracle price" }, "funding_rate": { "type": "number", "description": "Funding rate" }, "open_interest": { "type": "number", "description": "Open interest" } } }, "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"] }, "SavedToolActionResponse": { "type": "object", "description": "Result of removing a saved tool", "properties": { "removed": { "type": "boolean", "description": "Whether a saved tool existed and was removed" } }, "required": ["removed"] }, "ClearNftPfpResponse": { "type": "object", "description": "Response for clearing the NFT profile picture", "properties": { "success": { "type": "boolean", "description": "Whether the NFT profile picture was cleared" } }, "required": ["success"] }, "WalletUnlinkResponse": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"] }, "AgentRelationshipRemovalResponse": { "type": "object", "properties": { "removed": { "type": "boolean" } }, "required": ["removed"] }, "AuthScope": { "type": "string", "description": "OAuth-style scope recognized by the OpenSea API for wallet-authenticated requests", "enum": [ "read:eligibility", "read:favorites", "read:social", "read:tools", "read:wallets", "write:favorites", "write:social", "write:tools", "write:orders", "write:drops", "write:collections", "write:profile", "write:wallets" ], "example": "read:favorites", "x-enum-descriptions": [ "Check drop eligibility for authenticated wallet", "View favorites and watchlist for authenticated account", "View follows, watches, followers, and following for the authenticated account", "View saved tools and toolkits for the authenticated account", "View wallet state for the authenticated account, currently agent ownership relationships including pending proposals", "Add and remove favorites and watchlist entries for authenticated account", "Follow, unfollow, watch, and unwatch profiles, and link or unlink an X account, for the authenticated account", "Save and remove tools and manage toolkits for the authenticated account", "Cancel orders on behalf of authenticated account", "Manage Creator Studio drops for authenticated account", "Modify collection metadata for authenticated account", "Modify profile settings for authenticated account", "Link, unlink, manage wallet visibility, and declare agent relationships for the authenticated account" ], "x-enum-display-names": [ "Check drop eligibility", "View favorites and watchlist", "View social relationships", "View saved tools and toolkits", "View linked wallets and agent relationships", "Manage favorites and watchlist", "Manage social relationships", "Manage saved tools and toolkits", "Cancel orders", "Creator Studio drop management", "Collection metadata editing", "Profile editing", "Manage linked wallets" ], "x-enum-groups": [ "read", "read", "read", "read", "read", "write", "write", "write", "write", "write", "write", "write", "write" ], "x-enum-endpoints": [ ["/api/v2/drops/{slug}/eligibility"], [ "/api/v2/account/{address}/favorites", "/api/v2/account/{address}/token_watchlist", "/api/v2/account/{address}/perpetual_watchlist" ], [ "/api/v2/accounts/{address_or_username}/relationship", "/api/v2/accounts/{address_or_username}/followers", "/api/v2/accounts/{address_or_username}/following" ], [ "/api/v2/saved-tools", "/api/v2/toolkits", "/api/v2/toolkits/{toolkit_slug}" ], ["/api/v2/accounts/agent-relationships"], ["/api/v2/watchlist"], [ "/api/v2/accounts/{address_or_username}/follow", "/api/v2/accounts/{address_or_username}/watch", "/api/v2/accounts/social/x/link", "/api/v2/accounts/social/x/link/{link_id}", "/api/v2/accounts/social/x" ], [ "/api/v2/saved-tools", "/api/v2/toolkits", "/api/v2/toolkits/{toolkit_id}/save" ], [ "/api/v2/orders/chain/{chain}/protocol/{protocol_address}/{order_hash}/cancel" ], [ "/api/v2/drops/{slug}", "/api/v2/drops/{slug}/allowlist", "/api/v2/drops/{slug}/allowlist/validate", "/api/v2/drops/{slug}/prereveal-item", "/api/v2/drops/{slug}/items", "/api/v2/drops/{slug}/items/media", "/api/v2/drops/{slug}/items/media/save", "/api/v2/drops/{slug}/items/{token_id}" ], [ "/api/v2/collections/{slug}", "/api/v2/collections/{slug}/metadata", "/api/v2/collections/{slug}/visibility", "/api/v2/collections/{slug}/images/{image_type}" ], [ "/api/v2/profile", "/api/v2/profile/username", "/api/v2/profile/images", "/api/v2/profile/nft-pfp", "/api/v2/profile/shelves", "/api/v2/profile/shelves/{shelf_id}" ], [ "/api/v2/accounts/agent", "/api/v2/accounts/agent-relationships", "/api/v2/accounts/agent-relationships/confirm", "/api/v2/accounts/wallets/siwx", "/api/v2/accounts/wallets/{wallet}", "/api/v2/accounts/wallets/{wallet}/private" ] ], "x-enum-mcp-tools": [ ["check_drop_eligibility"], ["get_favorites"], ["view_social_graph"], ["list_saved_tools", "list_toolkits", "get_toolkit"], ["get_agent_relationships"], ["manage_watchlist"], ["manage_social_graph", "link_x_account"], [ "save_tool", "unsave_tool", "create_toolkit", "save_toolkit", "unsave_toolkit" ], ["cancel_orders"], ["manage_drops"], ["manage_collections"], ["manage_profile"], ["manage_wallets", "manage_agent_account"] ] }, "TokenExchangeRequest": { "type": "object", "description": "Scoped-token exchange request", "properties": { "subjectToken": { "type": "string", "description": "The opaque scoped token (personal access token) to exchange. A session JWT is not accepted.", "maxLength": 8192, "minLength": 10 }, "subjectTokenType": { "type": "string", "default": "ACCESS_TOKEN", "description": "Type of the presented subject token", "enum": ["ACCESS_TOKEN"] } }, "required": ["subjectToken"] }, "TokenExchangeResponse": { "type": "object", "description": "Minted access token", "properties": { "accessToken": { "type": "string", "description": "Bearer token to send as `Authorization: Bearer `" }, "tokenType": { "type": "string", "description": "Token type", "example": "Bearer" }, "expiresIn": { "type": "integer", "format": "int64", "description": "Token lifetime in seconds, when the issuer reports one" }, "scope": { "type": "string", "description": "Space-delimited scopes on the minted token, when present" }, "tokenScopes": { "type": "array", "description": "Scopes bound to the presented scoped token at mint time. Requests are authorized against these, not the full account scope set.", "items": { "$ref": "#/components/schemas/AuthScope" }, "uniqueItems": true } }, "required": ["accessToken", "tokenType"] }, "AuthErrorResponse": { "type": "object", "description": "Error envelope returned by the authentication endpoints", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable reason" }, "status": { "type": "string", "description": "Status name" }, "code": { "type": "integer", "format": "int32", "description": "HTTP status code" } } } } } }, "responses": { "BadRequest": { "description": "For error reasons, review the response data." }, "Unauthorized": { "description": "Invalid or missing API key" }, "Forbidden": { "description": "Wallet token lacks permission for this request" }, "NotFound": { "description": "Resource not found" }, "Conflict": { "description": "Resource conflict" }, "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" }, "WalletAuth": { "type": "openIdConnect", "description": "OpenSea wallet authorization. Run `opensea login` or use the OAuth 2.1 authorization-code flow with PKCE, then send the access token as `Authorization: Bearer `.", "openIdConnectUrl": "https://auth.opensea.io/.well-known/openid-configuration" } } }, "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"] }, { "name": "Authentication", "tags": ["Auth Endpoints"] } ] }