# OpenSea Developer Documentation Documentation

## Guides
- [Badges](https://docs.opensea.io/docs/badges.md): Establish trust with your users by adding our OpenSea badge on your site.
- [Logos](https://docs.opensea.io/docs/logos.md): These are official OpenSea resources that you can include on your marketing materials, webpage, and/or mobile application.
- [Build with AI Agents](https://docs.opensea.io/docs/build-with-ai-agents.md): Integrate OpenSea data and trading into AI agent workflows using MCP, Agent Skills, the CLI, and the SDK.
- [Buy and Sell NFTs](https://docs.opensea.io/docs/buy-and-sell-nfts.md): Buy and sell NFTs programmatically using the OpenSea SDK (@opensea/sdk).
- [Collection Offers and Advanced Trading](https://docs.opensea.io/docs/collection-offers-and-advanced-trading.md): Go beyond single-item trading with collection offers, trait offers, bulk operations, and advanced order management.
- [Optional: Manually deploying a SeaDrop-compatible contract](https://docs.opensea.io/docs/deploying-a-seadrop-compatible-contract.md)
- [Drops FAQ](https://docs.opensea.io/docs/drops-faq.md)
- [Create a Primary Drop](https://docs.opensea.io/docs/create-a-drop.md): Learn how to deploy a smart contract, configure drop mechanics, and personalize your landing page so that your community can mint your project directly on OpenSea.
- [Part 1: Deploy NFT Contract](https://docs.opensea.io/docs/part-1-deploy-a-smart-contract.md)
- [Part 2: Edit Collection Settings](https://docs.opensea.io/docs/part-2-edit-collection-settings.md)
- [Part 3: Upload Metadata](https://docs.opensea.io/docs/part-3-upload-metadata.md)
- [Part 4: Edit Drop Settings](https://docs.opensea.io/docs/part-4-edit-drop-settings.md)
- [Part 5: Customize Drop Page](https://docs.opensea.io/docs/part-5-customize-drop-page.md)
- [Part 6: Publish your drop](https://docs.opensea.io/docs/part-5-publish-your-drop.md)
- [Deploy an NFT Contract](https://docs.opensea.io/docs/deploy-an-nft-contract.md)
- [Part 1: Setup](https://docs.opensea.io/docs/part-1-setup.md)
- [Part 2: Deploy a contract using Shipyard](https://docs.opensea.io/docs/part-2-set-up-shipyard.md)
- [Part 3: Mint an NFT](https://docs.opensea.io/docs/part-3-add-metadata-to-your-contract.md)
- [Display an NFT](https://docs.opensea.io/docs/display-an-nft.md)
- [Part 1: Setup](https://docs.opensea.io/docs/part-1-simple-website-setup.md)
- [Part 2: Fetch an NFT from OpenSea](https://docs.opensea.io/docs/part-2-fetch-an-nft-from-opensea.md)
- [Mint from a Drop Programmatically](https://docs.opensea.io/docs/mint-from-a-drop.md): Build a custom mint experience using the OpenSea Drops API.
- [Query Analytics and Events](https://docs.opensea.io/docs/query-analytics-and-events.md): Build dashboards and analytics using OpenSea collection stats, trending data, and historical events.
- [Search and Discovery](https://docs.opensea.io/docs/search-and-discovery.md): Build search and browse experiences using the OpenSea API and SDK.
- [Stream Real-Time Events](https://docs.opensea.io/docs/stream-real-time-events.md): Listen to marketplace events in real time using @opensea/stream-js.
- [Swap Tokens](https://docs.opensea.io/docs/swap-tokens.md): Build a token swap using the OpenSea API and SDK.
- [Transfer and Manage NFTs](https://docs.opensea.io/docs/transfer-and-manage-nfts.md): Programmatically transfer, manage, and validate NFTs using the OpenSea SDK.
- [Creator Fee Enforcement](https://docs.opensea.io/docs/creator-fee-enforcement.md)
- [Offer Leverage](https://docs.opensea.io/docs/offer-leverage.md)
- [OpenSea Fees](https://docs.opensea.io/docs/opensea-fees.md)
- [SeaDrop](https://docs.opensea.io/docs/seadrop.md): An overview of the SeaDrop protocol and how it is used for NFT Primary Drops.
- [Seaport](https://docs.opensea.io/docs/seaport.md): An overview of the Seaport protocol and how it powers OpenSea.
- [Conduit Controller](https://docs.opensea.io/docs/seaport-conduit-controller.md)
- [Enums](https://docs.opensea.io/docs/seaport-enums.md)
- [Events and Errors](https://docs.opensea.io/docs/seaport-events-and-errors.md)
- [Seaport Hooks](https://docs.opensea.io/docs/seaport-hooks.md)
- [Interface](https://docs.opensea.io/docs/seaport-interface.md): Method definitions for the Seaport contract
- [Models](https://docs.opensea.io/docs/seaport-models.md): This page enumerates the models used within Seaport.
- [Contract-level metadata](https://docs.opensea.io/docs/contract-level-metadata.md): Customizing the metadata for your smart contract
- [Metadata Standards](https://docs.opensea.io/docs/metadata-standards.md): How to add rich metadata to your ERC721 or ERC1155 NFTs

## API Reference
- [Get collection stats](https://docs.opensea.io/reference/get_collection_stats.md): Get comprehensive statistics for a collection including volume, floor price, and trading metrics.
- [Analytics & Events](https://docs.opensea.io/reference/analytics-and-events.md)
- [Get events (by account)](https://docs.opensea.io/reference/list_events_by_account.md): Get a list of events for an account.
- [Get events (by collection)](https://docs.opensea.io/reference/list_events_by_collection.md): Get a list of events for a collection. Optionally filter by traits to only return events for items matching the specified trait criteria.
- [Get events (by NFT)](https://docs.opensea.io/reference/list_events_by_nft.md): Get a list of events for a specific NFT.
- [Get events](https://docs.opensea.io/reference/list_events.md): Get a list of events, with optional filtering by event type and time range.
- [Getting Your API Key](https://docs.opensea.io/reference/api-keys.md)
- [Overview](https://docs.opensea.io/reference/api-overview.md)
- [Get an OpenSea account profile](https://docs.opensea.io/reference/get_account.md): Get an OpenSea Account Profile including details such as bio, social media usernames, and profile image.
- [Resolve an account identifier](https://docs.opensea.io/reference/resolve_account.md): 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.
- [Create an instant API key](https://docs.opensea.io/reference/create_instant_api_key.md): Creates a free-tier API key instantly without authentication. The key can be used immediately for all API endpoints. Rate limited to 3 keys per hour per IP. Keys expire after 30 days.
- [Get supported chains](https://docs.opensea.io/reference/get_chains.md): Get all supported blockchain chains with metadata including name, native currency symbol, swap support, and block explorer information.
- [Get collection traits](https://docs.opensea.io/reference/get_collection_traits.md): Get all available traits for a collection with their value counts and data types.
- [Get a single collection](https://docs.opensea.io/reference/get_collection.md): Get a single collection including details such as fees, traits, and links.
- [Get collection by NFT](https://docs.opensea.io/reference/get_nft_collection.md): 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.
- [Get top collections](https://docs.opensea.io/reference/get_top_collections.md): 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.
- [Get trending collections](https://docs.opensea.io/reference/get_trending_collections.md): 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.
- [Get multiple collections](https://docs.opensea.io/reference/list_collections.md): Get a list of collections with filters and sorting options.
- [Get contract](https://docs.opensea.io/reference/get_contract.md): Get contract metadata including collection information, contract standards, and ownership details.
- [Get payment token](https://docs.opensea.io/reference/get_payment_token.md): Get a payment token by chain and contract address.
- [Data & Discovery](https://docs.opensea.io/reference/data-and-discovery.md)
- [Get NFT metadata](https://docs.opensea.io/reference/get_nft_metadata.md): Get detailed metadata for an NFT including name, description, image, traits, and external links.
- [Get NFT](https://docs.opensea.io/reference/get_nft.md): Get metadata, traits, ownership information, and rarity for a single NFT.
- [Get NFTs by account](https://docs.opensea.io/reference/get_nfts_by_account.md): Get all NFTs owned by a specific account on a blockchain, with optional collection filtering.
- [Get NFTs by collection](https://docs.opensea.io/reference/get_nfts_by_collection.md): 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"}]
- [Get NFTs by contract](https://docs.opensea.io/reference/get_nfts_by_contract.md): Get all NFTs for a specific contract address on a blockchain.
- [Refresh NFT metadata](https://docs.opensea.io/reference/refresh_nft_metadata.md): Queue a metadata refresh for a specific NFT to update its information from the blockchain.
- [Validate NFT metadata](https://docs.opensea.io/reference/validate_nft_metadata.md): 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.
- [Search across OpenSea](https://docs.opensea.io/reference/search.md): Search across collections, tokens, NFTs, and accounts. Results are ranked by relevance.
- [Get token balances by account](https://docs.opensea.io/reference/get_token_balances_by_account.md): 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.
- [Get a token group by slug](https://docs.opensea.io/reference/get_token_group.md): Get detailed information about a specific token group by its slug identifier.
- [Get token groups](https://docs.opensea.io/reference/get_token_groups.md): 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).
- [Get token details](https://docs.opensea.io/reference/get_token.md): Get detailed information about a specific token by chain and contract address.
- [Get top tokens](https://docs.opensea.io/reference/get_top_tokens.md): Get top tokens ranked by 24-hour trading volume. Returns established tokens with high market activity.
- [Get trending tokens](https://docs.opensea.io/reference/get_trending_tokens.md): Get trending tokens based on OpenSea's trending score algorithm. Returns tokens with high momentum including memecoins and newly popular assets.
- [Get listings](https://docs.opensea.io/reference/get_listings.md): Deprecated: This endpoint uses a legacy response format. Use the following collection-based endpoints instead, which return a cleaner response shape with structured price objects: GET /api/v2/listings/collection/{slug}/all for all listings in a collection, GET /api/v2/listings/collection/{slug}/best for best listings by price, or GET /api/v2/listings/collection/{slug}/nfts/{identifier}/best for the best listing on a specific NFT. To look up an individual order, use GET /api/v2/orders/chain/{chain}/protocol/{protocol_address}/{order_hash}. The collection-based endpoints return results sorted by best price. To query by creation time, use the events API (GET /api/v2/events). Note: the 'maker' filter on this endpoint has no equivalent on the collection-based endpoints. Also, the NFT-specific route (GET /api/v2/listings/collection/{slug}/nfts/{identifier}/best) only returns the best single listing, not a full paginated list.
- [Get item offers](https://docs.opensea.io/reference/get_offers.md): Deprecated: This endpoint uses a legacy response format. Use the following collection-based endpoints instead, which return a cleaner response shape with structured price objects: GET /api/v2/offers/collection/{slug}/nfts/{identifier} for item offers, GET /api/v2/offers/collection/{slug}/all for all offers in a collection, GET /api/v2/offers/collection/{slug} for collection offers, or GET /api/v2/offers/collection/{slug}/traits for trait offers. To look up an individual order, use GET /api/v2/orders/chain/{chain}/protocol/{protocol_address}/{order_hash}. The collection-based endpoints return results sorted by best price. To query by creation time, use the events API (GET /api/v2/events). Note: the 'maker' filter on this endpoint has no equivalent on the collection-based endpoints.
- [LLMs & Agent Discovery](https://docs.opensea.io/reference/llms-agent-discovery.md): Machine-readable endpoints for AI agents and LLMs to discover and interact with the OpenSea API.
- [Build mint transaction data for a drop](https://docs.opensea.io/reference/build_drop_mint_transaction.md): 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.
- [Get drop by collection slug](https://docs.opensea.io/reference/get_drop_by_slug.md): Get detailed drop information for a collection, including stages and supply.
- [Get drops](https://docs.opensea.io/reference/get_drops.md): 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.
- [Marketplace & Trading](https://docs.opensea.io/reference/marketplace-and-trading.md)
- [Fulfill a listing using a different token](https://docs.opensea.io/reference/generate_cross_chain_listing_fulfillment_data.md): 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.
- [Fulfill a listing](https://docs.opensea.io/reference/generate_listing_fulfillment_data_v2.md): Retrieve all the information, including signatures, needed to fulfill a listing directly onchain.
- [Get best listing by NFT](https://docs.opensea.io/reference/get_best_listing_nft.md): Get the best listing for an NFT.
- [Get best listings by collection](https://docs.opensea.io/reference/get_best_listings_collection.md): 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"}]
- [Get all listings by collection](https://docs.opensea.io/reference/list_listings_collection_all.md): Get all listings for a collection.
- [Create a listing](https://docs.opensea.io/reference/post_listing.md): List a single NFT (ERC721 or ERC1155) for sale on the OpenSea marketplace. The response includes both a legacy 'order' field (deprecated) and a new 'listing' field with the current v2 response format. New integrations should use the 'listing' field.
- [Build a criteria offer](https://docs.opensea.io/reference/build_offer_v2.md): 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.
- [Fulfill an offer](https://docs.opensea.io/reference/generate_offer_fulfillment_data_v2.md): 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.
- [Get best offer by NFT](https://docs.opensea.io/reference/get_best_offer_nft.md): Get the best offer for an NFT.
- [Get offers by trait](https://docs.opensea.io/reference/get_offers_collection_trait.md): Get trait offers for a collection with the specified trait(s). Supports single or multiple traits.
- [Get offers by collection](https://docs.opensea.io/reference/get_offers_collection.md): Get collection offers on a collection.
- [Get offers by NFT](https://docs.opensea.io/reference/get_offers_nft.md): Get offers for an NFT.
- [Get all offers by collection](https://docs.opensea.io/reference/list_offers_collection_all.md): Get all offers for a collection.
- [Create a criteria offer](https://docs.opensea.io/reference/post_criteria_offer_v2.md): 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.
- [Create an item offer](https://docs.opensea.io/reference/post_offer.md): Create an offer to purchase a single NFT (ERC721 or ERC1155). The response includes both a legacy 'order' field (deprecated) and a new 'offer' field with the current v2 response format. New integrations should use the 'offer' field.
- [Cancel an order](https://docs.opensea.io/reference/cancel_order.md): 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.
- [Get an order](https://docs.opensea.io/reference/get_order.md): Get a single order by its order hash.
- [Get swap quote](https://docs.opensea.io/reference/get_swap_quote.md): Get a quote for swapping tokens, including price details and executable transaction data.
- [Agent Skill](https://docs.opensea.io/reference/agent-skill.md): Enable AI coding assistants to interact with OpenSea using the Agent Skill, a modular knowledge and tooling package for AI agents.
- [MCP Overview](https://docs.opensea.io/reference/mcp.md): Connect your AI tools to OpenSea using the Model Context Protocol (MCP), an open standard that lets AI assistants interact with NFTs, tokens, and blockchain data across multiple chains.
- [@opensea/cli](https://docs.opensea.io/reference/opensea-cli.md): Query the OpenSea API from the command line or programmatically with @opensea/cli. Designed for both AI agents and developers.
- [@opensea/sdk](https://docs.opensea.io/reference/opensea-js.md): TypeScript SDK for creating listings, making offers, fulfilling orders, and querying NFT data via the Seaport protocol. Supports both ethers.js and viem.
- [Overview](https://docs.opensea.io/reference/sdks-overview.md): Open-source SDKs and tools for building on the OpenSea API. Each package is maintained in its own GitHub repository with full documentation.
- [@opensea/stream-js](https://docs.opensea.io/reference/stream-js.md): Receive real-time marketplace events over WebSocket using the OpenSea Stream API and @opensea/stream-js SDK.

## Pages
- [Model Reference](https://docs.opensea.io/model-reference.md)

## Changelog
- [OpenSea Fee Update](https://docs.opensea.io/changelog/opensea-fee-update.md)
- [Ronin OpenSea Marketplace Fee Update](https://docs.opensea.io/changelog/ronin-opensea-marketplace-fee-update.md)
- [Offer Precision Changes](https://docs.opensea.io/changelog/api-changes.md)
- [New Offchain Cancel Order API and List Collections `Order By` Option](https://docs.opensea.io/changelog/new-offchain-cancel-order-api-and-list-collections-order-by-option.md)
- [Now Accepting Seaport v1.6 Orders](https://docs.opensea.io/changelog/seaport-v1-6.md)