{ "schemaVersion": "1.0", "item": { "slug": "opensea-skill", "name": "OpenSea", "source": "tencent", "type": "skill", "category": "数据分析", "sourceUrl": "https://clawhub.ai/dfinzer/opensea-skill", "canonicalUrl": "https://clawhub.ai/dfinzer/opensea-skill", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/opensea-skill", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=opensea-skill", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "README.md", "SKILL.md", "scripts/opensea-account-nfts.sh", "scripts/opensea-order.sh", "scripts/opensea-listings-collection.sh", "scripts/opensea-get.sh" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-23T16:43:11.935Z", "expiresAt": "2026-04-30T16:43:11.935Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard", "contentDisposition": "attachment; filename=\"4claw-imageboard-1.0.1.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/opensea-skill" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/opensea-skill", "agentPageUrl": "https://openagent3.xyz/skills/opensea-skill/agent", "manifestUrl": "https://openagent3.xyz/skills/opensea-skill/agent.json", "briefUrl": "https://openagent3.xyz/skills/opensea-skill/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "OpenSea API", "body": "Query NFT data, trade on the Seaport marketplace, and swap ERC20 tokens across Ethereum, Base, Arbitrum, Optimism, Polygon, and more." }, { "title": "Quick start", "body": "Set OPENSEA_API_KEY in your environment\nPreferred: Use the opensea CLI (@opensea/cli) for all queries and operations\nAlternatively, use the shell scripts in scripts/ or the MCP server\n\nexport OPENSEA_API_KEY=\"your-api-key\"\n\n# Install the CLI globally (or use npx)\nnpm install -g @opensea/cli\n\n# Get collection info\nopensea collections get boredapeyachtclub\n\n# Get floor price and volume stats\nopensea collections stats boredapeyachtclub\n\n# Get NFT details\nopensea nfts get ethereum 0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d 1234\n\n# Get best listings for a collection\nopensea listings best boredapeyachtclub --limit 5\n\n# Search across OpenSea\nopensea search \"cool cats\"\n\n# Get trending tokens\nopensea tokens trending --limit 5\n\n# Get a swap quote\nopensea swaps quote \\\n --from-chain base --from-address 0x0000000000000000000000000000000000000000 \\\n --to-chain base --to-address 0xTokenAddress \\\n --quantity 0.02 --address 0xYourWallet" }, { "title": "Task guide", "body": "Recommended: Use the opensea CLI (@opensea/cli) as your primary tool. It covers all the operations below with a consistent interface, structured output, and built-in pagination. Install with npm install -g @opensea/cli or use npx @opensea/cli. The shell scripts in scripts/ remain available as alternatives." }, { "title": "Token swaps", "body": "OpenSea's API includes a cross-chain DEX aggregator for swapping ERC20 tokens with optimal routing across all supported chains.\n\nTaskCLI CommandAlternativeGet swap quote with calldataopensea swaps quote --from-chain --from-address --to-chain --to-address --quantity --address get_token_swap_quote (MCP) or opensea-swap.shGet trending tokensopensea tokens trending [--chains ] [--limit ]get_trending_tokens (MCP)Get top tokens by volumeopensea tokens top [--chains ] [--limit ]get_top_tokens (MCP)Get token detailsopensea tokens get
get_tokens (MCP)Search tokensopensea search --types tokensearch_tokens (MCP)Check token balancesget_token_balances (MCP)—" }, { "title": "Reading NFT data", "body": "TaskCLI CommandAlternativeGet collection detailsopensea collections get opensea-collection.sh Get collection statsopensea collections stats opensea-collection-stats.sh List NFTs in collectionopensea nfts list-by-collection [--limit ]opensea-collection-nfts.sh [limit] [next]Get single NFTopensea nfts get opensea-nft.sh List NFTs by walletopensea nfts list-by-account
[--limit ]opensea-account-nfts.sh
[limit]List NFTs by contractopensea nfts list-by-contract [--limit ]—Get collection traitsopensea collections traits —Get contract detailsopensea nfts contract
—Refresh NFT metadataopensea nfts refresh —" }, { "title": "Marketplace queries", "body": "TaskCLI CommandAlternativeGet best listings for collectionopensea listings best [--limit ]opensea-best-listing.sh Get best listing for specific NFTopensea listings best-for-nft opensea-best-listing.sh Get best offer for NFTopensea offers best-for-nft opensea-best-offer.sh List all collection listingsopensea listings all [--limit ]opensea-listings-collection.sh [limit]List all collection offersopensea offers all [--limit ]opensea-offers-collection.sh [limit]Get collection offersopensea offers collection [--limit ]opensea-offers-collection.sh [limit]Get trait offersopensea offers traits --type --value —Get order by hash—opensea-order.sh " }, { "title": "Marketplace actions (POST)", "body": "TaskScriptGet fulfillment data (buy NFT)opensea-fulfill-listing.sh Get fulfillment data (accept offer)opensea-fulfill-offer.sh Generic POST requestopensea-post.sh " }, { "title": "Search", "body": "TaskCLI CommandSearch collectionsopensea search --types collectionSearch NFTsopensea search --types nftSearch tokensopensea search --types tokenSearch accountsopensea search --types accountSearch multiple typesopensea search --types collection,nft,tokenSearch on specific chainopensea search --chains base,ethereum" }, { "title": "Events and monitoring", "body": "TaskCLI CommandAlternativeList recent eventsopensea events list [--event-type ] [--limit ]—Get collection eventsopensea events by-collection [--event-type ]opensea-events-collection.sh [event_type] [limit]Get events for specific NFTopensea events by-nft —Get events for accountopensea events by-account
—Stream real-time events—opensea-stream-collection.sh (requires websocat)\n\nEvent types: sale, transfer, mint, listing, offer, trait_offer, collection_offer" }, { "title": "Accounts", "body": "TaskCLI CommandGet account detailsopensea accounts get
" }, { "title": "Generic requests", "body": "TaskScriptAny GET endpointopensea-get.sh [query]Any POST endpointopensea-post.sh " }, { "title": "Buying an NFT", "body": "Find the NFT and check its listing:\n./scripts/opensea-best-listing.sh cool-cats-nft 1234\n\n\n\nGet the order hash from the response, then get fulfillment data:\n./scripts/opensea-fulfill-listing.sh ethereum 0x_order_hash 0x_your_wallet\n\n\n\nThe response contains transaction data to execute on-chain" }, { "title": "Selling an NFT (accepting an offer)", "body": "Check offers on your NFT:\n./scripts/opensea-best-offer.sh cool-cats-nft 1234\n\n\n\nGet fulfillment data for the offer:\n./scripts/opensea-fulfill-offer.sh ethereum 0x_offer_hash 0x_your_wallet 0x_nft_contract 1234\n\n\n\nExecute the returned transaction data" }, { "title": "Creating listings/offers", "body": "Creating new listings and offers requires wallet signatures. Use opensea-post.sh with the Seaport order structure - see references/marketplace-api.md for full details." }, { "title": "OpenSea CLI (@opensea/cli)", "body": "The OpenSea CLI is the recommended way for AI agents to interact with OpenSea. It provides a consistent command-line interface and a programmatic TypeScript/JavaScript SDK." }, { "title": "Installation", "body": "# Install globally\nnpm install -g @opensea/cli\n\n# Or use without installing\nnpx @opensea/cli collections get mfers" }, { "title": "Authentication", "body": "# Set via environment variable (recommended)\nexport OPENSEA_API_KEY=\"your-api-key\"\nopensea collections get mfers\n\n# Or pass inline\nopensea --api-key your-api-key collections get mfers" }, { "title": "CLI Commands", "body": "CommandDescriptioncollectionsGet, list, stats, and traits for NFT collectionsnftsGet, list, refresh metadata, and contract details for NFTslistingsGet all, best, or best-for-nft listingsoffersGet all, collection, best-for-nft, and trait offerseventsList marketplace events (sales, transfers, mints, etc.)searchSearch collections, NFTs, tokens, and accountstokensGet trending tokens, top tokens, and token detailsswapsGet swap quotes for token tradingaccountsGet account details\n\nGlobal options: --api-key, --chain (default: ethereum), --format (json/table/toon), --base-url, --timeout, --verbose" }, { "title": "Output Formats", "body": "JSON (default): Structured output for agents and scripts\nTable: Human-readable tabular output (--format table)\nTOON: Token-Oriented Object Notation, uses ~40% fewer tokens than JSON — ideal for LLM/AI agent context windows (--format toon)\n\n# JSON output (default)\nopensea collections stats mfers\n\n# Human-readable table\nopensea --format table collections stats mfers\n\n# Compact TOON format (best for AI agents)\nopensea --format toon tokens trending --limit 5" }, { "title": "Pagination", "body": "All list commands support cursor-based pagination with --limit and --next:\n\n# First page\nopensea collections list --limit 5\n\n# Pass the \"next\" cursor from the response to get the next page\nopensea collections list --limit 5 --next \"LXBrPTEwMDA...\"" }, { "title": "Programmatic SDK", "body": "The CLI also exports a TypeScript/JavaScript SDK for use in scripts and applications:\n\nimport { OpenSeaCLI, OpenSeaAPIError } from \"@opensea/cli\"\n\nconst client = new OpenSeaCLI({ apiKey: process.env.OPENSEA_API_KEY })\n\nconst collection = await client.collections.get(\"mfers\")\nconst { nfts } = await client.nfts.listByCollection(\"mfers\", { limit: 5 })\nconst { listings } = await client.listings.best(\"mfers\", { limit: 10 })\nconst { asset_events } = await client.events.byCollection(\"mfers\", { eventType: \"sale\" })\nconst { tokens } = await client.tokens.trending({ chains: [\"base\"], limit: 5 })\nconst results = await client.search.query(\"mfers\", { limit: 5 })\n\n// Swap quote\nconst { quote, transactions } = await client.swaps.quote({\n fromChain: \"base\",\n fromAddress: \"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913\",\n toChain: \"base\",\n toAddress: \"0x3ec2156d4c0a9cbdab4a016633b7bcf6a8d68ea2\",\n quantity: \"1000000\",\n address: \"0xYourWalletAddress\",\n})\n\n// Error handling\ntry {\n await client.collections.get(\"nonexistent\")\n} catch (error) {\n if (error instanceof OpenSeaAPIError) {\n console.error(error.statusCode) // e.g. 404\n console.error(error.responseBody) // raw API response\n console.error(error.path) // request path\n }\n}" }, { "title": "TOON Format for AI Agents", "body": "TOON (Token-Oriented Object Notation) is a compact serialization format that uses ~40% fewer tokens than JSON, making it ideal for piping CLI output into LLM context windows:\n\nopensea --format toon tokens trending --limit 3\n\nExample output:\n\ntokens[3]{name,symbol,chain,market_cap,price_usd}:\n Ethereum,ETH,ethereum,250000000000,2100.50\n Bitcoin,BTC,bitcoin,900000000000,48000.00\n Solana,SOL,solana,30000000000,95.25\nnext: abc123\n\nTOON is also available programmatically:\n\nimport { formatToon } from \"@opensea/cli\"\n\nconst data = await client.tokens.trending({ limit: 5 })\nconsole.log(formatToon(data))" }, { "title": "CLI Exit Codes", "body": "0 - Success\n1 - API error\n2 - Authentication error" }, { "title": "Shell Scripts Reference", "body": "The scripts/ directory contains shell scripts that wrap the OpenSea REST API directly using curl. These are an alternative to the CLI above." }, { "title": "NFT & Collection Scripts", "body": "ScriptPurposeopensea-get.shGeneric GET (path + optional query)opensea-post.shGeneric POST (path + JSON body)opensea-collection.shFetch collection by slugopensea-collection-stats.shFetch collection statisticsopensea-collection-nfts.shList NFTs in collectionopensea-nft.shFetch single NFT by chain/contract/tokenopensea-account-nfts.shList NFTs owned by wallet" }, { "title": "Marketplace Scripts", "body": "ScriptPurposeopensea-listings-collection.shAll listings for collectionopensea-listings-nft.shListings for specific NFTopensea-offers-collection.shAll offers for collectionopensea-offers-nft.shOffers for specific NFTopensea-best-listing.shLowest listing for NFTopensea-best-offer.shHighest offer for NFTopensea-order.shGet order by hashopensea-fulfill-listing.shGet buy transaction dataopensea-fulfill-offer.shGet sell transaction data" }, { "title": "Token Swap Scripts", "body": "ScriptPurposeopensea-swap.shSwap tokens via OpenSea MCP" }, { "title": "Monitoring Scripts", "body": "ScriptPurposeopensea-events-collection.shCollection event historyopensea-stream-collection.shReal-time WebSocket events" }, { "title": "Supported chains", "body": "ethereum, matic, arbitrum, optimism, base, avalanche, klaytn, zora, blast, sepolia" }, { "title": "References", "body": "OpenSea CLI GitHub - Full CLI and SDK documentation\nCLI Reference - Complete command reference\nSDK Reference - Programmatic SDK API\nCLI Examples - Real-world usage examples\nreferences/rest-api.md - REST endpoint families and pagination\nreferences/marketplace-api.md - Buy/sell workflows and Seaport details\nreferences/stream-api.md - WebSocket event streaming\nreferences/seaport.md - Seaport protocol and NFT purchase execution\nreferences/token-swaps.md - Token swap workflows via MCP" }, { "title": "OpenSea MCP Server", "body": "An official OpenSea MCP server provides direct LLM integration for token swaps and NFT operations. When enabled, Claude can execute swaps, query token data, and interact with NFT marketplaces directly.\n\nSetup:\n\nGo to the OpenSea Developer Portal and verify your email\nGenerate a new API key for REST API access\nGenerate a separate MCP token for the MCP server\n\nAdd to your MCP config:\n\n{\n \"mcpServers\": {\n \"opensea\": {\n \"url\": \"https://mcp.opensea.io/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer YOUR_MCP_TOKEN\"\n }\n }\n }\n}\n\nOr use the inline token format: https://mcp.opensea.io/YOUR_MCP_TOKEN/mcp" }, { "title": "Token Swap Tools", "body": "MCP ToolPurposeget_token_swap_quoteGet swap calldata for token tradesget_token_balancesCheck wallet token holdingssearch_tokensFind tokens by name/symbolget_trending_tokensHot tokens by momentumget_top_tokensTop tokens by 24h volumeget_tokensGet detailed token info" }, { "title": "NFT Tools", "body": "MCP ToolPurposesearch_collectionsSearch NFT collectionssearch_itemsSearch individual NFTsget_collectionsGet detailed collection infoget_itemsGet detailed NFT infoget_nft_balancesList NFTs owned by walletget_trending_collectionsTrending NFT collectionsget_top_collectionsTop collections by volumeget_activityTrading activity for collections/itemsget_upcoming_dropsUpcoming NFT mints" }, { "title": "Profile & Utility Tools", "body": "MCP ToolPurposeget_profileWallet profile with holdings/activityaccount_lookupResolve ENS/address/usernameget_chainsList supported chainssearchAI-powered natural language searchfetchGet full details by entity ID" }, { "title": "Token Swaps via MCP", "body": "OpenSea MCP supports ERC20 token swaps across supported DEXes - not just NFTs!" }, { "title": "Get Swap Quote", "body": "mcporter call opensea.get_token_swap_quote --args '{\n \"fromContractAddress\": \"0x0000000000000000000000000000000000000000\",\n \"fromChain\": \"base\",\n \"toContractAddress\": \"0xb695559b26bb2c9703ef1935c37aeae9526bab07\",\n \"toChain\": \"base\",\n \"fromQuantity\": \"0.02\",\n \"address\": \"0xYourWalletAddress\"\n}'\n\nParameters:\n\nfromContractAddress: Token to swap from (use 0x0000...0000 for native ETH)\ntoContractAddress: Token to swap to\nfromChain / toChain: Chain identifiers\nfromQuantity: Amount in human-readable units (e.g., \"0.02\" for 0.02 ETH)\naddress: Your wallet address\n\nResponse includes:\n\nswapQuote: Price info, fees, slippage impact\nswap.actions[0].transactionSubmissionData: Ready-to-use calldata" }, { "title": "Execute the Swap", "body": "import { createWalletClient, http } from 'viem';\nimport { privateKeyToAccount } from 'viem/accounts';\nimport { base } from 'viem/chains';\n\n// Extract from swap quote response\nconst txData = response.swap.actions[0].transactionSubmissionData;\n\nconst wallet = createWalletClient({ \n account: privateKeyToAccount(PRIVATE_KEY), \n chain: base, \n transport: http() \n});\n\nconst hash = await wallet.sendTransaction({\n to: txData.to,\n data: txData.data,\n value: BigInt(txData.value)\n});" }, { "title": "Check Token Balances", "body": "mcporter call opensea.get_token_balances --args '{\n \"address\": \"0xYourWallet\",\n \"chains\": [\"base\", \"ethereum\"]\n}'" }, { "title": "Generating a wallet", "body": "To execute swaps or buy NFTs, you need an Ethereum wallet (private key + address)." }, { "title": "Using Node.js", "body": "import crypto from 'crypto';\nimport { privateKeyToAccount } from 'viem/accounts';\n\nconst privateKey = '0x' + crypto.randomBytes(32).toString('hex');\nconst account = privateKeyToAccount(privateKey);\n\nconsole.log('Private Key:', privateKey);\nconsole.log('Address:', account.address);" }, { "title": "Using OpenSSL", "body": "# Generate private key\nPRIVATE_KEY=\"0x$(openssl rand -hex 32)\"\necho \"Private Key: $PRIVATE_KEY\"\n\n# Derive address (requires node + viem)\nnode --input-type=module -e \"\nimport { privateKeyToAccount } from 'viem/accounts';\nconsole.log('Address:', privateKeyToAccount('$PRIVATE_KEY').address);\n\"" }, { "title": "Using cast (Foundry)", "body": "cast wallet new\n\nImportant: Store private keys securely. Never commit them to git or share publicly." }, { "title": "Requirements", "body": "OPENSEA_API_KEY environment variable (for CLI, SDK, and REST API scripts)\nOPENSEA_MCP_TOKEN environment variable (for MCP server, separate from API key)\nNode.js >= 18.0.0 (for @opensea/cli)\ncurl for REST shell scripts\nwebsocat (optional) for Stream API\njq (recommended) for parsing JSON responses from shell scripts\n\nGet both credentials at opensea.io/settings/developer." } ], "body": "OpenSea API\n\nQuery NFT data, trade on the Seaport marketplace, and swap ERC20 tokens across Ethereum, Base, Arbitrum, Optimism, Polygon, and more.\n\nQuick start\nSet OPENSEA_API_KEY in your environment\nPreferred: Use the opensea CLI (@opensea/cli) for all queries and operations\nAlternatively, use the shell scripts in scripts/ or the MCP server\nexport OPENSEA_API_KEY=\"your-api-key\"\n\n# Install the CLI globally (or use npx)\nnpm install -g @opensea/cli\n\n# Get collection info\nopensea collections get boredapeyachtclub\n\n# Get floor price and volume stats\nopensea collections stats boredapeyachtclub\n\n# Get NFT details\nopensea nfts get ethereum 0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d 1234\n\n# Get best listings for a collection\nopensea listings best boredapeyachtclub --limit 5\n\n# Search across OpenSea\nopensea search \"cool cats\"\n\n# Get trending tokens\nopensea tokens trending --limit 5\n\n# Get a swap quote\nopensea swaps quote \\\n --from-chain base --from-address 0x0000000000000000000000000000000000000000 \\\n --to-chain base --to-address 0xTokenAddress \\\n --quantity 0.02 --address 0xYourWallet\n\nTask guide\n\nRecommended: Use the opensea CLI (@opensea/cli) as your primary tool. It covers all the operations below with a consistent interface, structured output, and built-in pagination. Install with npm install -g @opensea/cli or use npx @opensea/cli. The shell scripts in scripts/ remain available as alternatives.\n\nToken swaps\n\nOpenSea's API includes a cross-chain DEX aggregator for swapping ERC20 tokens with optimal routing across all supported chains.\n\nTask\tCLI Command\tAlternative\nGet swap quote with calldata\topensea swaps quote --from-chain --from-address --to-chain --to-address --quantity --address \tget_token_swap_quote (MCP) or opensea-swap.sh\nGet trending tokens\topensea tokens trending [--chains ] [--limit ]\tget_trending_tokens (MCP)\nGet top tokens by volume\topensea tokens top [--chains ] [--limit ]\tget_top_tokens (MCP)\nGet token details\topensea tokens get
\tget_tokens (MCP)\nSearch tokens\topensea search --types token\tsearch_tokens (MCP)\nCheck token balances\tget_token_balances (MCP)\t—\nReading NFT data\nTask\tCLI Command\tAlternative\nGet collection details\topensea collections get \topensea-collection.sh \nGet collection stats\topensea collections stats \topensea-collection-stats.sh \nList NFTs in collection\topensea nfts list-by-collection [--limit ]\topensea-collection-nfts.sh [limit] [next]\nGet single NFT\topensea nfts get \topensea-nft.sh \nList NFTs by wallet\topensea nfts list-by-account
[--limit ]\topensea-account-nfts.sh
[limit]\nList NFTs by contract\topensea nfts list-by-contract [--limit ]\t—\nGet collection traits\topensea collections traits \t—\nGet contract details\topensea nfts contract
\t—\nRefresh NFT metadata\topensea nfts refresh \t—\nMarketplace queries\nTask\tCLI Command\tAlternative\nGet best listings for collection\topensea listings best [--limit ]\topensea-best-listing.sh \nGet best listing for specific NFT\topensea listings best-for-nft \topensea-best-listing.sh \nGet best offer for NFT\topensea offers best-for-nft \topensea-best-offer.sh \nList all collection listings\topensea listings all [--limit ]\topensea-listings-collection.sh [limit]\nList all collection offers\topensea offers all [--limit ]\topensea-offers-collection.sh [limit]\nGet collection offers\topensea offers collection [--limit ]\topensea-offers-collection.sh [limit]\nGet trait offers\topensea offers traits --type --value \t—\nGet order by hash\t—\topensea-order.sh \nMarketplace actions (POST)\nTask\tScript\nGet fulfillment data (buy NFT)\topensea-fulfill-listing.sh \nGet fulfillment data (accept offer)\topensea-fulfill-offer.sh \nGeneric POST request\topensea-post.sh \nSearch\nTask\tCLI Command\nSearch collections\topensea search --types collection\nSearch NFTs\topensea search --types nft\nSearch tokens\topensea search --types token\nSearch accounts\topensea search --types account\nSearch multiple types\topensea search --types collection,nft,token\nSearch on specific chain\topensea search --chains base,ethereum\nEvents and monitoring\nTask\tCLI Command\tAlternative\nList recent events\topensea events list [--event-type ] [--limit ]\t—\nGet collection events\topensea events by-collection [--event-type ]\topensea-events-collection.sh [event_type] [limit]\nGet events for specific NFT\topensea events by-nft \t—\nGet events for account\topensea events by-account
\t—\nStream real-time events\t—\topensea-stream-collection.sh (requires websocat)\n\nEvent types: sale, transfer, mint, listing, offer, trait_offer, collection_offer\n\nAccounts\nTask\tCLI Command\nGet account details\topensea accounts get
\nGeneric requests\nTask\tScript\nAny GET endpoint\topensea-get.sh [query]\nAny POST endpoint\topensea-post.sh \nBuy/Sell workflows\nBuying an NFT\n\nFind the NFT and check its listing:\n\n./scripts/opensea-best-listing.sh cool-cats-nft 1234\n\n\nGet the order hash from the response, then get fulfillment data:\n\n./scripts/opensea-fulfill-listing.sh ethereum 0x_order_hash 0x_your_wallet\n\n\nThe response contains transaction data to execute on-chain\n\nSelling an NFT (accepting an offer)\n\nCheck offers on your NFT:\n\n./scripts/opensea-best-offer.sh cool-cats-nft 1234\n\n\nGet fulfillment data for the offer:\n\n./scripts/opensea-fulfill-offer.sh ethereum 0x_offer_hash 0x_your_wallet 0x_nft_contract 1234\n\n\nExecute the returned transaction data\n\nCreating listings/offers\n\nCreating new listings and offers requires wallet signatures. Use opensea-post.sh with the Seaport order structure - see references/marketplace-api.md for full details.\n\nOpenSea CLI (@opensea/cli)\n\nThe OpenSea CLI is the recommended way for AI agents to interact with OpenSea. It provides a consistent command-line interface and a programmatic TypeScript/JavaScript SDK.\n\nInstallation\n# Install globally\nnpm install -g @opensea/cli\n\n# Or use without installing\nnpx @opensea/cli collections get mfers\n\nAuthentication\n# Set via environment variable (recommended)\nexport OPENSEA_API_KEY=\"your-api-key\"\nopensea collections get mfers\n\n# Or pass inline\nopensea --api-key your-api-key collections get mfers\n\nCLI Commands\nCommand\tDescription\ncollections\tGet, list, stats, and traits for NFT collections\nnfts\tGet, list, refresh metadata, and contract details for NFTs\nlistings\tGet all, best, or best-for-nft listings\noffers\tGet all, collection, best-for-nft, and trait offers\nevents\tList marketplace events (sales, transfers, mints, etc.)\nsearch\tSearch collections, NFTs, tokens, and accounts\ntokens\tGet trending tokens, top tokens, and token details\nswaps\tGet swap quotes for token trading\naccounts\tGet account details\n\nGlobal options: --api-key, --chain (default: ethereum), --format (json/table/toon), --base-url, --timeout, --verbose\n\nOutput Formats\nJSON (default): Structured output for agents and scripts\nTable: Human-readable tabular output (--format table)\nTOON: Token-Oriented Object Notation, uses ~40% fewer tokens than JSON — ideal for LLM/AI agent context windows (--format toon)\n# JSON output (default)\nopensea collections stats mfers\n\n# Human-readable table\nopensea --format table collections stats mfers\n\n# Compact TOON format (best for AI agents)\nopensea --format toon tokens trending --limit 5\n\nPagination\n\nAll list commands support cursor-based pagination with --limit and --next:\n\n# First page\nopensea collections list --limit 5\n\n# Pass the \"next\" cursor from the response to get the next page\nopensea collections list --limit 5 --next \"LXBrPTEwMDA...\"\n\nProgrammatic SDK\n\nThe CLI also exports a TypeScript/JavaScript SDK for use in scripts and applications:\n\nimport { OpenSeaCLI, OpenSeaAPIError } from \"@opensea/cli\"\n\nconst client = new OpenSeaCLI({ apiKey: process.env.OPENSEA_API_KEY })\n\nconst collection = await client.collections.get(\"mfers\")\nconst { nfts } = await client.nfts.listByCollection(\"mfers\", { limit: 5 })\nconst { listings } = await client.listings.best(\"mfers\", { limit: 10 })\nconst { asset_events } = await client.events.byCollection(\"mfers\", { eventType: \"sale\" })\nconst { tokens } = await client.tokens.trending({ chains: [\"base\"], limit: 5 })\nconst results = await client.search.query(\"mfers\", { limit: 5 })\n\n// Swap quote\nconst { quote, transactions } = await client.swaps.quote({\n fromChain: \"base\",\n fromAddress: \"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913\",\n toChain: \"base\",\n toAddress: \"0x3ec2156d4c0a9cbdab4a016633b7bcf6a8d68ea2\",\n quantity: \"1000000\",\n address: \"0xYourWalletAddress\",\n})\n\n// Error handling\ntry {\n await client.collections.get(\"nonexistent\")\n} catch (error) {\n if (error instanceof OpenSeaAPIError) {\n console.error(error.statusCode) // e.g. 404\n console.error(error.responseBody) // raw API response\n console.error(error.path) // request path\n }\n}\n\nTOON Format for AI Agents\n\nTOON (Token-Oriented Object Notation) is a compact serialization format that uses ~40% fewer tokens than JSON, making it ideal for piping CLI output into LLM context windows:\n\nopensea --format toon tokens trending --limit 3\n\n\nExample output:\n\ntokens[3]{name,symbol,chain,market_cap,price_usd}:\n Ethereum,ETH,ethereum,250000000000,2100.50\n Bitcoin,BTC,bitcoin,900000000000,48000.00\n Solana,SOL,solana,30000000000,95.25\nnext: abc123\n\n\nTOON is also available programmatically:\n\nimport { formatToon } from \"@opensea/cli\"\n\nconst data = await client.tokens.trending({ limit: 5 })\nconsole.log(formatToon(data))\n\nCLI Exit Codes\n0 - Success\n1 - API error\n2 - Authentication error\nShell Scripts Reference\n\nThe scripts/ directory contains shell scripts that wrap the OpenSea REST API directly using curl. These are an alternative to the CLI above.\n\nNFT & Collection Scripts\nScript\tPurpose\nopensea-get.sh\tGeneric GET (path + optional query)\nopensea-post.sh\tGeneric POST (path + JSON body)\nopensea-collection.sh\tFetch collection by slug\nopensea-collection-stats.sh\tFetch collection statistics\nopensea-collection-nfts.sh\tList NFTs in collection\nopensea-nft.sh\tFetch single NFT by chain/contract/token\nopensea-account-nfts.sh\tList NFTs owned by wallet\nMarketplace Scripts\nScript\tPurpose\nopensea-listings-collection.sh\tAll listings for collection\nopensea-listings-nft.sh\tListings for specific NFT\nopensea-offers-collection.sh\tAll offers for collection\nopensea-offers-nft.sh\tOffers for specific NFT\nopensea-best-listing.sh\tLowest listing for NFT\nopensea-best-offer.sh\tHighest offer for NFT\nopensea-order.sh\tGet order by hash\nopensea-fulfill-listing.sh\tGet buy transaction data\nopensea-fulfill-offer.sh\tGet sell transaction data\nToken Swap Scripts\nScript\tPurpose\nopensea-swap.sh\tSwap tokens via OpenSea MCP\nMonitoring Scripts\nScript\tPurpose\nopensea-events-collection.sh\tCollection event history\nopensea-stream-collection.sh\tReal-time WebSocket events\nSupported chains\n\nethereum, matic, arbitrum, optimism, base, avalanche, klaytn, zora, blast, sepolia\n\nReferences\nOpenSea CLI GitHub - Full CLI and SDK documentation\nCLI Reference - Complete command reference\nSDK Reference - Programmatic SDK API\nCLI Examples - Real-world usage examples\nreferences/rest-api.md - REST endpoint families and pagination\nreferences/marketplace-api.md - Buy/sell workflows and Seaport details\nreferences/stream-api.md - WebSocket event streaming\nreferences/seaport.md - Seaport protocol and NFT purchase execution\nreferences/token-swaps.md - Token swap workflows via MCP\nOpenSea MCP Server\n\nAn official OpenSea MCP server provides direct LLM integration for token swaps and NFT operations. When enabled, Claude can execute swaps, query token data, and interact with NFT marketplaces directly.\n\nSetup:\n\nGo to the OpenSea Developer Portal and verify your email\nGenerate a new API key for REST API access\nGenerate a separate MCP token for the MCP server\n\nAdd to your MCP config:\n\n{\n \"mcpServers\": {\n \"opensea\": {\n \"url\": \"https://mcp.opensea.io/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer YOUR_MCP_TOKEN\"\n }\n }\n }\n}\n\n\nOr use the inline token format: https://mcp.opensea.io/YOUR_MCP_TOKEN/mcp\n\nToken Swap Tools\nMCP Tool\tPurpose\nget_token_swap_quote\tGet swap calldata for token trades\nget_token_balances\tCheck wallet token holdings\nsearch_tokens\tFind tokens by name/symbol\nget_trending_tokens\tHot tokens by momentum\nget_top_tokens\tTop tokens by 24h volume\nget_tokens\tGet detailed token info\nNFT Tools\nMCP Tool\tPurpose\nsearch_collections\tSearch NFT collections\nsearch_items\tSearch individual NFTs\nget_collections\tGet detailed collection info\nget_items\tGet detailed NFT info\nget_nft_balances\tList NFTs owned by wallet\nget_trending_collections\tTrending NFT collections\nget_top_collections\tTop collections by volume\nget_activity\tTrading activity for collections/items\nget_upcoming_drops\tUpcoming NFT mints\nProfile & Utility Tools\nMCP Tool\tPurpose\nget_profile\tWallet profile with holdings/activity\naccount_lookup\tResolve ENS/address/username\nget_chains\tList supported chains\nsearch\tAI-powered natural language search\nfetch\tGet full details by entity ID\nToken Swaps via MCP\n\nOpenSea MCP supports ERC20 token swaps across supported DEXes - not just NFTs!\n\nGet Swap Quote\nmcporter call opensea.get_token_swap_quote --args '{\n \"fromContractAddress\": \"0x0000000000000000000000000000000000000000\",\n \"fromChain\": \"base\",\n \"toContractAddress\": \"0xb695559b26bb2c9703ef1935c37aeae9526bab07\",\n \"toChain\": \"base\",\n \"fromQuantity\": \"0.02\",\n \"address\": \"0xYourWalletAddress\"\n}'\n\n\nParameters:\n\nfromContractAddress: Token to swap from (use 0x0000...0000 for native ETH)\ntoContractAddress: Token to swap to\nfromChain / toChain: Chain identifiers\nfromQuantity: Amount in human-readable units (e.g., \"0.02\" for 0.02 ETH)\naddress: Your wallet address\n\nResponse includes:\n\nswapQuote: Price info, fees, slippage impact\nswap.actions[0].transactionSubmissionData: Ready-to-use calldata\nExecute the Swap\nimport { createWalletClient, http } from 'viem';\nimport { privateKeyToAccount } from 'viem/accounts';\nimport { base } from 'viem/chains';\n\n// Extract from swap quote response\nconst txData = response.swap.actions[0].transactionSubmissionData;\n\nconst wallet = createWalletClient({ \n account: privateKeyToAccount(PRIVATE_KEY), \n chain: base, \n transport: http() \n});\n\nconst hash = await wallet.sendTransaction({\n to: txData.to,\n data: txData.data,\n value: BigInt(txData.value)\n});\n\nCheck Token Balances\nmcporter call opensea.get_token_balances --args '{\n \"address\": \"0xYourWallet\",\n \"chains\": [\"base\", \"ethereum\"]\n}'\n\nGenerating a wallet\n\nTo execute swaps or buy NFTs, you need an Ethereum wallet (private key + address).\n\nUsing Node.js\nimport crypto from 'crypto';\nimport { privateKeyToAccount } from 'viem/accounts';\n\nconst privateKey = '0x' + crypto.randomBytes(32).toString('hex');\nconst account = privateKeyToAccount(privateKey);\n\nconsole.log('Private Key:', privateKey);\nconsole.log('Address:', account.address);\n\nUsing OpenSSL\n# Generate private key\nPRIVATE_KEY=\"0x$(openssl rand -hex 32)\"\necho \"Private Key: $PRIVATE_KEY\"\n\n# Derive address (requires node + viem)\nnode --input-type=module -e \"\nimport { privateKeyToAccount } from 'viem/accounts';\nconsole.log('Address:', privateKeyToAccount('$PRIVATE_KEY').address);\n\"\n\nUsing cast (Foundry)\ncast wallet new\n\n\nImportant: Store private keys securely. Never commit them to git or share publicly.\n\nRequirements\nOPENSEA_API_KEY environment variable (for CLI, SDK, and REST API scripts)\nOPENSEA_MCP_TOKEN environment variable (for MCP server, separate from API key)\nNode.js >= 18.0.0 (for @opensea/cli)\ncurl for REST shell scripts\nwebsocat (optional) for Stream API\njq (recommended) for parsing JSON responses from shell scripts\n\nGet both credentials at opensea.io/settings/developer." }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/dfinzer/opensea-skill", "publisherUrl": "https://clawhub.ai/dfinzer/opensea-skill", "owner": "dfinzer", "version": "1.0.3", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/opensea-skill", "downloadUrl": "https://openagent3.xyz/downloads/opensea-skill", "agentUrl": "https://openagent3.xyz/skills/opensea-skill/agent", "manifestUrl": "https://openagent3.xyz/skills/opensea-skill/agent.json", "briefUrl": "https://openagent3.xyz/skills/opensea-skill/agent.md" } }