{"id":"a73472bf-4b98-4cbe-9eb1-1e1011cb72e7","entityType":"agent","slug":"clawhub-dfinzer-opensea-mcp","name":"OpenSea","canonicalUrl":"https://www.xpersona.co/agent/clawhub-dfinzer-opensea-mcp","canonicalPath":"/agent/clawhub-dfinzer-opensea-mcp","generatedAt":"2026-10-09T17:15:20.027Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"description":"Query OpenSea NFT marketplace data via official MCP server. Get floor prices, trending collections, token prices, wallet balances, swap quotes, and NFT holdings. Supports Ethereum, Base, Polygon, Solana, and other major chains. Requires OpenSea developer account for MCP token.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.5K downloads reported by the source. Last updated 4/15/2026.","installCommand":"clawhub skill install kn7176r43k8cwrwyv9h52051z9809n51:opensea-mcp","sourceUrl":"https://clawhub.ai/dfinzer/opensea-mcp","homepage":"https://clawhub.ai/dfinzer/opensea-mcp","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/dfinzer/opensea-mcp","kind":"source"}],"safetyScore":84,"overallRank":62,"popularityScore":64,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"OpenSea technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"stars":null,"forks":null,"downloads":1528,"packageName":null,"latestVersion":"1.0.2","tractionLabel":"1.5K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-02-28T21:32:04.197Z","emptyReason":null},"lastUpdatedAt":"2026-04-15T00:45:39.800Z","lastCrawledAt":"2026-02-28T21:32:04.197Z","lastIndexedAt":null,"nextCrawlAt":"2026-03-01T21:32:04.197Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.2","createdAt":"2026-02-08T01:16:59.679Z","changelog":"Version 1.0.2 - Documentation updates only; no file or code changes detected. - No impact to functionality or interfaces.","fileCount":26,"zipByteSize":22965},{"version":"1.0.1","createdAt":"2026-02-08T00:45:59.632Z","changelog":"- Expanded documentation in SKILL.md with detailed quick start instructions, script/task guides, and workflow examples for NFT trading and ERC20 token swaps. - Added comprehensive reference tables for all supported scripts and MCP server tools. - Clarified buy/sell NFT workflows and cross-chain token swap operations. - Documented supported chains and setup steps for OpenSea API and MCP server integration. - Included guidance for marketplace actions (listing/offers), events, and monitoring scripts. - Provided detailed references and workflow notes to improve usability for developers and users.","fileCount":26,"zipByteSize":22945},{"version":"1.0.0","createdAt":"2026-01-31T18:52:39.344Z","changelog":"- Initial release of opensea-mcp. - Enables querying OpenSea NFT marketplace data via the official MCP server. - Supports fetching floor prices, trending collections, token and wallet info, swap quotes, and NFT holdings. - Works with Ethereum, Base, Polygon, Solana, and other major chains. - Requires MCP token from an OpenSea developer account.","fileCount":null,"zipByteSize":null}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install kn7176r43k8cwrwyv9h52051z9809n51:opensea-mcp","setupComplexity":"low","setupSteps":["Install using `clawhub skill install kn7176r43k8cwrwyv9h52051z9809n51:opensea-mcp` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/dfinzer/opensea-mcp before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-dfinzer-opensea-mcp/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-dfinzer-opensea-mcp/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-dfinzer-opensea-mcp/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-dfinzer-opensea-mcp/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-dfinzer-opensea-mcp/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-dfinzer-opensea-mcp/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T17:15:20.026Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-dfinzer-opensea-mcp/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-dfinzer-opensea-mcp/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-dfinzer-opensea-mcp/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-dfinzer-opensea-mcp/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"readme":"Skill: OpenSea\n\nOwner: dfinzer\n\nSummary: Query OpenSea NFT marketplace data via official MCP server. Get floor prices, trending collections, token prices, wallet balances, swap quotes, and NFT holdings. Supports Ethereum, Base, Polygon, Solana, and other major chains. Requires OpenSea developer account for MCP token.\n\nTags: latest:1.0.2\n\nVersion history:\n\nv1.0.2 | 2026-02-08T01:16:59.679Z | user\n\nVersion 1.0.2\n\n- Documentation updates only; no file or code changes detected.\n- No impact to functionality or interfaces.\n\nv1.0.1 | 2026-02-08T00:45:59.632Z | user\n\n- Expanded documentation in SKILL.md with detailed quick start instructions, script/task guides, and workflow examples for NFT trading and ERC20 token swaps.\n- Added comprehensive reference tables for all supported scripts and MCP server tools.\n- Clarified buy/sell NFT workflows and cross-chain token swap operations.\n- Documented supported chains and setup steps for OpenSea API and MCP server integration.\n- Included guidance for marketplace actions (listing/offers), events, and monitoring scripts.\n- Provided detailed references and workflow notes to improve usability for developers and users.\n\nv1.0.0 | 2026-01-31T18:52:39.344Z | user\n\n- Initial release of opensea-mcp.\n- Enables querying OpenSea NFT marketplace data via the official MCP server.\n- Supports fetching floor prices, trending collections, token and wallet info, swap quotes, and NFT holdings.\n- Works with Ethereum, Base, Polygon, Solana, and other major chains.\n- Requires MCP token from an OpenSea developer account.\n\nArchive index:\n\nArchive v1.0.2: 26 files, 22965 bytes\n\nFiles: references/marketplace-api.md (9198b), references/rest-api.md (3935b), references/seaport.md (7026b), references/stream-api.md (661b), references/token-swaps.md (4604b), scripts/opensea-account-nfts.sh (483b), scripts/opensea-best-listing.sh (336b), scripts/opensea-best-offer.sh (330b), scripts/opensea-collection-nfts.sh (450b), scripts/opensea-collection-stats.sh (290b), scripts/opensea-collection.sh (210b), scripts/opensea-events-collection.sh (625b), scripts/opensea-fulfill-listing.sh (676b), scripts/opensea-fulfill-offer.sh (854b), scripts/opensea-get.sh (480b), scripts/opensea-listings-collection.sh (462b), scripts/opensea-listings-nft.sh (476b), scripts/opensea-nft.sh (285b), scripts/opensea-offers-collection.sh (458b), scripts/opensea-offers-nft.sh (470b), scripts/opensea-order.sh (374b), scripts/opensea-post.sh (527b), scripts/opensea-stream-collection.sh (958b), scripts/opensea-swap.sh (3027b), SKILL.md (10740b), _meta.json (130b)\n\nFile v1.0.2:SKILL.md\n\n# OpenSea API\n\nQuery NFT data, trade on the Seaport marketplace, and swap ERC20 tokens across Ethereum, Base, Arbitrum, Optimism, Polygon, and more.\n\n## Quick start\n\n1. Set `OPENSEA_API_KEY` in your environment\n2. Run helper scripts in `scripts/` for common operations\n3. Use the MCP server for token swaps and advanced queries\n\n```bash\nexport OPENSEA_API_KEY=\"your-api-key\"\n\n# Token swap: ETH to token\n./scripts/opensea-swap.sh 0xTokenAddress 0.1 0xYourWallet 0xYourKey base\n\n# Token swap: Token to token (specify from_token as last arg)\n./scripts/opensea-swap.sh 0xToToken 100 0xYourWallet 0xYourKey base 0xFromToken\n\n# Get collection info\n./scripts/opensea-collection.sh boredapeyachtclub\n\n# Get NFT details\n./scripts/opensea-nft.sh ethereum 0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d 1234\n\n# Get best listing price for an NFT\n./scripts/opensea-best-listing.sh boredapeyachtclub 1234\n```\n\n## Task guide\n\n### Token swaps\n\nOpenSea's API includes a cross-chain DEX aggregator for swapping ERC20 tokens with optimal routing across all supported chains.\n\n| Task | Tool/Script |\n|------|-------------|\n| Get swap quote with calldata | `get_token_swap_quote` (MCP) or `opensea-swap.sh` |\n| Check token balances | `get_token_balances` (MCP) |\n| Search tokens | `search_tokens` (MCP) |\n| Get trending tokens | `get_trending_tokens` (MCP) |\n| Get top tokens by volume | `get_top_tokens` (MCP) |\n\n### Reading NFT data\n\n| Task | Script |\n|------|--------|\n| Get collection details | `opensea-collection.sh <slug>` |\n| Get collection stats | `opensea-collection-stats.sh <slug>` |\n| List NFTs in collection | `opensea-collection-nfts.sh <slug> [limit] [next]` |\n| Get single NFT | `opensea-nft.sh <chain> <contract> <token_id>` |\n| List NFTs by wallet | `opensea-account-nfts.sh <chain> <address> [limit]` |\n\n### Marketplace queries\n\n| Task | Script |\n|------|--------|\n| Get best listing for NFT | `opensea-best-listing.sh <slug> <token_id>` |\n| Get best offer for NFT | `opensea-best-offer.sh <slug> <token_id>` |\n| List all collection listings | `opensea-listings-collection.sh <slug> [limit]` |\n| List all collection offers | `opensea-offers-collection.sh <slug> [limit]` |\n| Get listings for specific NFT | `opensea-listings-nft.sh <chain> <contract> <token_id>` |\n| Get offers for specific NFT | `opensea-offers-nft.sh <chain> <contract> <token_id>` |\n| Get order by hash | `opensea-order.sh <chain> <order_hash>` |\n\n### Marketplace actions (POST)\n\n| Task | Script |\n|------|--------|\n| Get fulfillment data (buy NFT) | `opensea-fulfill-listing.sh <chain> <order_hash> <buyer>` |\n| Get fulfillment data (accept offer) | `opensea-fulfill-offer.sh <chain> <order_hash> <seller> <contract> <token_id>` |\n| Generic POST request | `opensea-post.sh <path> <json_body>` |\n\n### Events and monitoring\n\n| Task | Script |\n|------|--------|\n| Get collection events | `opensea-events-collection.sh <slug> [event_type] [limit]` |\n| Stream real-time events | `opensea-stream-collection.sh <slug>` (requires websocat) |\n\n### Generic requests\n\n| Task | Script |\n|------|--------|\n| Any GET endpoint | `opensea-get.sh <path> [query]` |\n| Any POST endpoint | `opensea-post.sh <path> <json_body>` |\n\n## Buy/Sell workflows\n\n### Buying an NFT\n\n1. Find the NFT and check its listing:\n   ```bash\n   ./scripts/opensea-best-listing.sh cool-cats-nft 1234\n   ```\n\n2. Get the order hash from the response, then get fulfillment data:\n   ```bash\n   ./scripts/opensea-fulfill-listing.sh ethereum 0x_order_hash 0x_your_wallet\n   ```\n\n3. The response contains transaction data to execute on-chain\n\n### Selling an NFT (accepting an offer)\n\n1. Check offers on your NFT:\n   ```bash\n   ./scripts/opensea-best-offer.sh cool-cats-nft 1234\n   ```\n\n2. Get fulfillment data for the offer:\n   ```bash\n   ./scripts/opensea-fulfill-offer.sh ethereum 0x_offer_hash 0x_your_wallet 0x_nft_contract 1234\n   ```\n\n3. Execute the returned transaction data\n\n### Creating 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\n## Scripts reference\n\n### NFT & Collection Scripts\n| Script | Purpose |\n|--------|---------|\n| `opensea-get.sh` | Generic GET (path + optional query) |\n| `opensea-post.sh` | Generic POST (path + JSON body) |\n| `opensea-collection.sh` | Fetch collection by slug |\n| `opensea-collection-stats.sh` | Fetch collection statistics |\n| `opensea-collection-nfts.sh` | List NFTs in collection |\n| `opensea-nft.sh` | Fetch single NFT by chain/contract/token |\n| `opensea-account-nfts.sh` | List NFTs owned by wallet |\n\n### Marketplace Scripts\n| Script | Purpose |\n|--------|---------|\n| `opensea-listings-collection.sh` | All listings for collection |\n| `opensea-listings-nft.sh` | Listings for specific NFT |\n| `opensea-offers-collection.sh` | All offers for collection |\n| `opensea-offers-nft.sh` | Offers for specific NFT |\n| `opensea-best-listing.sh` | Lowest listing for NFT |\n| `opensea-best-offer.sh` | Highest offer for NFT |\n| `opensea-order.sh` | Get order by hash |\n| `opensea-fulfill-listing.sh` | Get buy transaction data |\n| `opensea-fulfill-offer.sh` | Get sell transaction data |\n\n### Token Swap Scripts\n| Script | Purpose |\n|--------|---------|\n| `opensea-swap.sh` | **Swap tokens via OpenSea MCP** |\n\n### Monitoring Scripts\n| Script | Purpose |\n|--------|---------|\n| `opensea-events-collection.sh` | Collection event history |\n| `opensea-stream-collection.sh` | Real-time WebSocket events |\n\n## Supported chains\n\n`ethereum`, `matic`, `arbitrum`, `optimism`, `base`, `avalanche`, `klaytn`, `zora`, `blast`, `sepolia`\n\n## References\n\n- `references/rest-api.md` - REST endpoint families and pagination\n- `references/marketplace-api.md` - Buy/sell workflows and Seaport details\n- `references/stream-api.md` - WebSocket event streaming\n- `references/seaport.md` - Seaport protocol and NFT purchase execution\n- `references/token-swaps.md` - **Token swap workflows via MCP**\n\n## OpenSea 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\n**Setup:**\n\n1. Go to the [OpenSea Developer Portal](https://opensea.io/settings/developer) and verify your email\n2. Generate a new API key for REST API access\n3. Generate a separate MCP token for the MCP server\n\nAdd to your MCP config:\n```json\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\n### Token Swap Tools\n| MCP Tool | Purpose |\n|----------|---------|\n| `get_token_swap_quote` | **Get swap calldata for token trades** |\n| `get_token_balances` | Check wallet token holdings |\n| `search_tokens` | Find tokens by name/symbol |\n| `get_trending_tokens` | Hot tokens by momentum |\n| `get_top_tokens` | Top tokens by 24h volume |\n| `get_tokens` | Get detailed token info |\n\n### NFT Tools\n| MCP Tool | Purpose |\n|----------|---------|\n| `search_collections` | Search NFT collections |\n| `search_items` | Search individual NFTs |\n| `get_collections` | Get detailed collection info |\n| `get_items` | Get detailed NFT info |\n| `get_nft_balances` | List NFTs owned by wallet |\n| `get_trending_collections` | Trending NFT collections |\n| `get_top_collections` | Top collections by volume |\n| `get_activity` | Trading activity for collections/items |\n| `get_upcoming_drops` | Upcoming NFT mints |\n\n### Profile & Utility Tools\n| MCP Tool | Purpose |\n|----------|---------|\n| `get_profile` | Wallet profile with holdings/activity |\n| `account_lookup` | Resolve ENS/address/username |\n| `get_chains` | List supported chains |\n| `search` | AI-powered natural language search |\n| `fetch` | Get full details by entity ID |\n\n---\n\n## Token Swaps via MCP\n\nOpenSea MCP supports ERC20 token swaps across supported DEXes - not just NFTs!\n\n### Get Swap Quote\n```bash\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\n**Parameters:**\n- `fromContractAddress`: Token to swap from (use `0x0000...0000` for native ETH)\n- `toContractAddress`: Token to swap to\n- `fromChain` / `toChain`: Chain identifiers\n- `fromQuantity`: Amount in human-readable units (e.g., \"0.02\" for 0.02 ETH)\n- `address`: Your wallet address\n\n**Response includes:**\n- `swapQuote`: Price info, fees, slippage impact\n- `swap.actions[0].transactionSubmissionData`: Ready-to-use calldata\n\n### Execute the Swap\n```javascript\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```\n\n### Check Token Balances\n```bash\nmcporter call opensea.get_token_balances --args '{\n  \"address\": \"0xYourWallet\",\n  \"chains\": [\"base\", \"ethereum\"]\n}'\n```\n\n## Generating a wallet\n\nTo execute swaps or buy NFTs, you need an Ethereum wallet (private key + address).\n\n### Using Node.js\n```javascript\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```\n\n### Using OpenSSL\n```bash\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```\n\n### Using cast (Foundry)\n```bash\ncast wallet new\n```\n\n**Important:** Store private keys securely. Never commit them to git or share publicly.\n\n## Requirements\n\n- `OPENSEA_API_KEY` environment variable (for REST API scripts)\n- `OPENSEA_MCP_TOKEN` environment variable (for MCP server, separate from API key)\n- `curl` for REST calls\n- `websocat` (optional) for Stream API\n- `jq` (recommended) for parsing JSON responses\n\nGet both credentials at [opensea.io/settings/developer](https://opensea.io/settings/developer).\n\nFile v1.0.2:_meta.json\n\n{\n  \"ownerId\": \"kn7176r43k8cwrwyv9h52051z9809n51\",\n  \"slug\": \"opensea-mcp\",\n  \"version\": \"1.0.2\",\n  \"publishedAt\": 1770513419679\n}\n\nFile v1.0.2:references/marketplace-api.md\n\n# OpenSea Marketplace API\n\nThis reference covers the marketplace endpoints for buying and selling NFTs on OpenSea.\n\n## Overview\n\nOpenSea uses the **Seaport protocol** for all marketplace orders. The API provides endpoints to:\n- Query existing listings and offers\n- Build new listings and offers (returns unsigned Seaport orders)\n- Fulfill orders (accept listings or offers)\n- Cancel orders\n\n**Important**: Creating and fulfilling orders requires wallet signatures. The API returns order data that must be signed client-side before submission.\n\n## Base URL and Authentication\n\n```\nBase URL: https://api.opensea.io/api/v2\nAuth: x-api-key: $OPENSEA_API_KEY\n```\n\n## Supported Chains\n\n| Chain | Identifier |\n|-------|------------|\n| Ethereum | `ethereum` |\n| Polygon | `matic` |\n| Arbitrum | `arbitrum` |\n| Optimism | `optimism` |\n| Base | `base` |\n| Avalanche | `avalanche` |\n| Klaytn | `klaytn` |\n| Zora | `zora` |\n| Blast | `blast` |\n| Sepolia (testnet) | `sepolia` |\n\n---\n\n## Read Operations (GET)\n\n### Get Best Listing for NFT\n\nReturns the lowest-priced active listing for an NFT.\n\n```bash\nGET /api/v2/listings/collection/{collection_slug}/nfts/{identifier}/best\n```\n\n**Parameters:**\n- `collection_slug`: Collection slug (e.g., `boredapeyachtclub`)\n- `identifier`: NFT identifier (token ID)\n\n**Example:**\n```bash\nscripts/opensea-get.sh \"/api/v2/listings/collection/boredapeyachtclub/nfts/1234/best\"\n```\n\n### Get Best Offer for NFT\n\nReturns the highest active offer for an NFT.\n\n```bash\nGET /api/v2/offers/collection/{collection_slug}/nfts/{identifier}/best\n```\n\n**Example:**\n```bash\nscripts/opensea-get.sh \"/api/v2/offers/collection/boredapeyachtclub/nfts/1234/best\"\n```\n\n### Get All Listings for Collection\n\nReturns all active listings for a collection.\n\n```bash\nGET /api/v2/listings/collection/{collection_slug}/all\n```\n\n**Query parameters:**\n- `limit`: Page size (default 50, max 100)\n- `next`: Cursor for pagination\n\n**Example:**\n```bash\nscripts/opensea-listings-collection.sh boredapeyachtclub 50\n```\n\n### Get All Offers for Collection\n\nReturns all active offers for a collection.\n\n```bash\nGET /api/v2/offers/collection/{collection_slug}/all\n```\n\n**Example:**\n```bash\nscripts/opensea-offers-collection.sh boredapeyachtclub 50\n```\n\n### Get Listings for Specific NFT\n\n```bash\nGET /api/v2/orders/{chain}/seaport/listings\n```\n\n**Query parameters:**\n- `asset_contract_address`: Contract address\n- `token_ids`: Comma-separated token IDs\n- `limit`, `next`: Pagination\n\n**Example:**\n```bash\nscripts/opensea-get.sh \"/api/v2/orders/ethereum/seaport/listings\" \"asset_contract_address=0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d&token_ids=1234\"\n```\n\n### Get Offers for Specific NFT\n\n```bash\nGET /api/v2/orders/{chain}/seaport/offers\n```\n\n**Query parameters:**\n- `asset_contract_address`: Contract address\n- `token_ids`: Comma-separated token IDs\n\n**Example:**\n```bash\nscripts/opensea-get.sh \"/api/v2/orders/ethereum/seaport/offers\" \"asset_contract_address=0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d&token_ids=1234\"\n```\n\n### Get Order by Hash\n\nRetrieve details of a specific order.\n\n```bash\nGET /api/v2/orders/chain/{chain}/protocol/{protocol_address}/hash/{order_hash}\n```\n\n**Example:**\n```bash\nscripts/opensea-get.sh \"/api/v2/orders/chain/ethereum/protocol/0x00000000000000adc04c56bf30ac9d3c0aaf14dc/hash/0x...\"\n```\n\n---\n\n## Write Operations (POST)\n\n### Build a Listing\n\nCreates an unsigned Seaport listing order. Returns order parameters to sign.\n\n```bash\nPOST /api/v2/orders/{chain}/seaport/listings\n```\n\n**Request body:**\n```json\n{\n  \"parameters\": {\n    \"offerer\": \"0xYourWalletAddress\",\n    \"offer\": [{\n      \"itemType\": 2,\n      \"token\": \"0xContractAddress\",\n      \"identifierOrCriteria\": \"1234\",\n      \"startAmount\": \"1\",\n      \"endAmount\": \"1\"\n    }],\n    \"consideration\": [{\n      \"itemType\": 0,\n      \"token\": \"0x0000000000000000000000000000000000000000\",\n      \"identifierOrCriteria\": \"0\",\n      \"startAmount\": \"1000000000000000000\",\n      \"endAmount\": \"1000000000000000000\",\n      \"recipient\": \"0xYourWalletAddress\"\n    }],\n    \"startTime\": \"1704067200\",\n    \"endTime\": \"1735689600\",\n    \"orderType\": 0,\n    \"zone\": \"0x0000000000000000000000000000000000000000\",\n    \"zoneHash\": \"0x0000000000000000000000000000000000000000000000000000000000000000\",\n    \"salt\": \"random_salt_value\",\n    \"conduitKey\": \"0x0000007b02230091a7ed01230072f7006a004d60a8d4e71d599b8104250f0000\",\n    \"totalOriginalConsiderationItems\": 1\n  },\n  \"signature\": \"0xSignedOrderSignature\"\n}\n```\n\n**Item Types:**\n- `0`: Native currency (ETH, MATIC, etc.)\n- `1`: ERC20 token\n- `2`: ERC721 NFT\n- `3`: ERC1155 NFT\n\n**Example (curl):**\n```bash\ncurl -X POST \"https://api.opensea.io/api/v2/orders/ethereum/seaport/listings\" \\\n  -H \"x-api-key: $OPENSEA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"parameters\": {...}, \"signature\": \"0x...\"}'\n```\n\n### Build an Offer\n\nCreates an unsigned Seaport offer order.\n\n```bash\nPOST /api/v2/orders/{chain}/seaport/offers\n```\n\n**Request body structure** (similar to listings, but offer contains payment and consideration contains NFT):\n```json\n{\n  \"parameters\": {\n    \"offerer\": \"0xBuyerWalletAddress\",\n    \"offer\": [{\n      \"itemType\": 1,\n      \"token\": \"0xWETHAddress\",\n      \"identifierOrCriteria\": \"0\",\n      \"startAmount\": \"1000000000000000000\",\n      \"endAmount\": \"1000000000000000000\"\n    }],\n    \"consideration\": [{\n      \"itemType\": 2,\n      \"token\": \"0xNFTContractAddress\",\n      \"identifierOrCriteria\": \"1234\",\n      \"startAmount\": \"1\",\n      \"endAmount\": \"1\",\n      \"recipient\": \"0xBuyerWalletAddress\"\n    }]\n  },\n  \"signature\": \"0x...\"\n}\n```\n\n### Fulfill a Listing (Buy NFT)\n\nAccept an existing listing to purchase an NFT.\n\n```bash\nPOST /api/v2/listings/fulfillment_data\n```\n\n**Request body:**\n```json\n{\n  \"listing\": {\n    \"hash\": \"0xOrderHash\",\n    \"chain\": \"ethereum\",\n    \"protocol_address\": \"0x00000000000000adc04c56bf30ac9d3c0aaf14dc\"\n  },\n  \"fulfiller\": {\n    \"address\": \"0xBuyerWalletAddress\"\n  }\n}\n```\n\n**Response:** Returns transaction data for the buyer to submit on-chain.\n\n### Fulfill an Offer (Sell NFT)\n\nAccept an existing offer to sell your NFT.\n\n```bash\nPOST /api/v2/offers/fulfillment_data\n```\n\n**Request body:**\n```json\n{\n  \"offer\": {\n    \"hash\": \"0xOfferOrderHash\",\n    \"chain\": \"ethereum\",\n    \"protocol_address\": \"0x00000000000000adc04c56bf30ac9d3c0aaf14dc\"\n  },\n  \"fulfiller\": {\n    \"address\": \"0xSellerWalletAddress\"\n  },\n  \"consideration\": {\n    \"asset_contract_address\": \"0xNFTContract\",\n    \"token_id\": \"1234\"\n  }\n}\n```\n\n### Cancel an Order\n\nCancel an active listing or offer.\n\n```bash\nPOST /api/v2/orders/chain/{chain}/protocol/{protocol_address}/hash/{order_hash}/cancel\n```\n\n**Note:** Cancellation requires an on-chain transaction. The API returns the transaction data to execute.\n\n---\n\n## Workflow: Buying an NFT\n\n1. **Find the NFT** - Use `opensea-nft.sh` to get NFT details\n2. **Check listings** - Use `opensea-get.sh` to get best listing\n3. **Get fulfillment data** - POST to `/api/v2/listings/fulfillment_data`\n4. **Execute transaction** - Sign and submit the returned transaction data\n\n```bash\n# Step 1: Get NFT info\n./scripts/opensea-nft.sh ethereum 0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d 1234\n\n# Step 2: Get best listing\n./scripts/opensea-get.sh \"/api/v2/listings/collection/boredapeyachtclub/nfts/1234/best\"\n\n# Step 3: Request fulfillment (requires POST - see marketplace scripts)\n./scripts/opensea-fulfill-listing.sh ethereum 0x_order_hash 0x_your_wallet\n```\n\n## Workflow: Selling an NFT (Creating a Listing)\n\n1. **Build the listing** - POST to `/api/v2/orders/{chain}/seaport/listings`\n2. **Sign the order** - Use wallet to sign the Seaport order\n3. **Submit signed order** - POST again with signature\n4. **Monitor** - Check listing via `/api/v2/listings/collection/{slug}/all`\n\n## Workflow: Making an Offer\n\n1. **Ensure WETH approval** - Buyer needs WETH allowance for Seaport\n2. **Build the offer** - POST to `/api/v2/orders/{chain}/seaport/offers`\n3. **Sign the order** - Wallet signature required\n4. **Submit** - POST with signature\n\n## Workflow: Accepting an Offer\n\n1. **View offers** - Use `opensea-offers-collection.sh`\n2. **Get fulfillment data** - POST to `/api/v2/offers/fulfillment_data`\n3. **Execute** - Submit the returned transaction\n\n---\n\n## Error Codes\n\n| Code | Meaning |\n|------|---------|\n| 400 | Bad request - invalid parameters |\n| 401 | Unauthorized - missing or invalid API key |\n| 404 | Not found - order/NFT doesn't exist |\n| 429 | Rate limited - too many requests |\n| 500 | Server error |\n\n## Rate Limits\n\n- Standard: 60 requests/minute\n- With API key: Higher limits (check your dashboard)\n\n---\n\n## Seaport Contract Addresses\n\n| Chain | Seaport 1.6 Address |\n|-------|---------------------|\n| All chains | `0x00000000000000ADc04C56Bf30aC9d3c0aAF14dC` |\n\n---\n\n## Tips\n\n1. **Always use WETH for offers** - Native ETH cannot be used for offers due to ERC20 approval requirements\n2. **Check approval status** - Before creating listings, ensure Seaport has approval for your NFTs\n3. **Test on Sepolia first** - Use testnet before mainnet transactions\n4. **Handle expiration** - Orders have startTime/endTime - check these before fulfilling\n5. **Monitor events** - Use Stream API for real-time order updates\n\nFile v1.0.2:references/rest-api.md\n\n# OpenSea REST API Reference\n\n## Base URL and Authentication\n\n```\nBase URL: https://api.opensea.io\nAuth header: x-api-key: $OPENSEA_API_KEY\n```\n\n## Pagination\n\nList endpoints support cursor-based pagination:\n- `limit`: Page size (default varies, max 100)\n- `next`: Cursor token from previous response\n\n## Supported Chains\n\n| Chain | Identifier |\n|-------|------------|\n| Ethereum | `ethereum` |\n| Polygon | `matic` |\n| Arbitrum | `arbitrum` |\n| Optimism | `optimism` |\n| Base | `base` |\n| Avalanche | `avalanche` |\n| Klaytn | `klaytn` |\n| Zora | `zora` |\n| Blast | `blast` |\n| Sepolia (testnet) | `sepolia` |\n\n## Endpoint Reference\n\n### Collections\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v2/collections/{slug}` | GET | Single collection details |\n| `/api/v2/collections/{slug}/stats` | GET | Collection statistics (floor, volume) |\n| `/api/v2/collections` | GET | List multiple collections |\n\n### NFTs\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v2/chain/{chain}/contract/{contract}/nfts/{token_id}` | GET | Single NFT details |\n| `/api/v2/collection/{slug}/nfts` | GET | NFTs by collection |\n| `/api/v2/chain/{chain}/account/{address}/nfts` | GET | NFTs by wallet |\n| `/api/v2/chain/{chain}/contract/{contract}/nfts` | GET | NFTs by contract |\n| `/api/v2/nft/{contract}/{token_id}/refresh` | POST | Refresh NFT metadata |\n\n### Listings\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v2/listings/collection/{slug}/all` | GET | All listings for collection |\n| `/api/v2/listings/collection/{slug}/nfts/{token_id}/best` | GET | Best listing for NFT |\n| `/api/v2/orders/{chain}/seaport/listings` | GET | Listings by contract/token |\n| `/api/v2/orders/{chain}/seaport/listings` | POST | Create new listing |\n| `/api/v2/listings/fulfillment_data` | POST | Get buy transaction data |\n\n### Offers\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v2/offers/collection/{slug}/all` | GET | All offers for collection |\n| `/api/v2/offers/collection/{slug}/nfts/{token_id}/best` | GET | Best offer for NFT |\n| `/api/v2/orders/{chain}/seaport/offers` | GET | Offers by contract/token |\n| `/api/v2/orders/{chain}/seaport/offers` | POST | Create new offer |\n| `/api/v2/offers/fulfillment_data` | POST | Get sell transaction data |\n\n### Orders\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v2/orders/chain/{chain}/protocol/{protocol}/{hash}` | GET | Get order by hash |\n| `/api/v2/orders/chain/{chain}/protocol/{protocol}/{hash}/cancel` | POST | Cancel order |\n\n### Events\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v2/events/collection/{slug}` | GET | Events by collection |\n| `/api/v2/events/chain/{chain}/contract/{contract}/nfts/{token_id}` | GET | Events by NFT |\n| `/api/v2/events/chain/{chain}/account/{address}` | GET | Events by account |\n\n### Accounts\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v2/accounts/{address}` | GET | Account profile |\n\n## Event Types\n\nFor the events endpoint, filter with `event_type`:\n- `sale` - NFT sold\n- `transfer` - NFT transferred\n- `listing` - New listing created\n- `offer` - New offer made\n- `cancel` - Order cancelled\n- `redemption` - NFT redeemed\n\n## Rate Limits\n\n- Without API key: 40 requests/minute\n- With API key: Higher limits (varies by tier)\n\n## Error Codes\n\n| Code | Meaning |\n|------|---------|\n| 400 | Bad request - check parameters |\n| 401 | Unauthorized - missing/invalid API key |\n| 404 | Resource not found |\n| 429 | Rate limited |\n| 500 | Server error |\n\n## Tips\n\n1. Use collection slugs (not addresses) for collection endpoints\n2. Use chain identifiers for NFT/account endpoints\n3. All timestamps are Unix epoch seconds\n4. Prices are in wei (divide by 10^18 for ETH)\n5. Use `jq` to parse JSON responses: `./script.sh | jq '.nft.name'`\n\nFile v1.0.2:references/seaport.md\n\n# Seaport (OpenSea marketplace protocol)\n\n## What it is\nSeaport is the marketplace protocol used for OpenSea orders. All listings and offers on OpenSea are Seaport orders under the hood.\n\n## Order structure\n- **Offer items**: What the offerer provides (e.g., an NFT for listings, WETH for offers)\n- **Consideration items**: What the offerer expects to receive (e.g., ETH payment + fees)\n\n## Seaport Contract Addresses\n\n| Chain | Seaport 1.6 Address |\n|-------|---------------------|\n| All EVM chains | `0x0000000000000068F116a894984e2DB1123eB395` |\n\nLegacy Seaport 1.4: `0x00000000000000ADc04C56Bf30aC9d3c0aAF14dC`\n\n---\n\n## Buying NFTs (Fulfilling Listings)\n\n**No SDK required!** The OpenSea API returns ready-to-use calldata.\n\n### Workflow\n\n1. **Find a listing** - Get order hash from listings endpoint\n2. **Get fulfillment data** - POST to fulfillment endpoint\n3. **Submit transaction** - Send calldata directly to blockchain\n\n### Step 1: Get Listings\n\n```bash\n# Via script\n./scripts/opensea-listings-collection.sh basenames\n\n# Via MCP\nmcporter call opensea.get_listings collection=\"basenames\" limit=10\n```\n\nNote the `order_hash` and `protocol_address` from the response.\n\n### Step 2: Get Fulfillment Calldata\n\n```bash\n# Via script\n./scripts/opensea-fulfill-listing.sh base 0xORDER_HASH 0xYOUR_WALLET\n\n# Via curl\ncurl -X POST \"https://api.opensea.io/api/v2/listings/fulfillment_data\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"x-api-key: $OPENSEA_API_KEY\" \\\n  -d '{\n    \"listing\": {\n      \"hash\": \"0xORDER_HASH\",\n      \"chain\": \"base\",\n      \"protocol_address\": \"0x0000000000000068F116a894984e2DB1123eB395\"\n    },\n    \"fulfiller\": {\n      \"address\": \"0xYOUR_WALLET\"\n    }\n  }'\n```\n\n**Response contains:**\n- `fulfillment_data.transaction.to` - Seaport contract\n- `fulfillment_data.transaction.value` - ETH to send (wei)\n- `fulfillment_data.transaction.input_data` - Encoded calldata\n\n### Step 3: Submit Transaction\n\n```javascript\nimport { createPublicClient, createWalletClient, http } from 'viem';\nimport { privateKeyToAccount } from 'viem/accounts';\nimport { base } from 'viem/chains';\n\nconst account = privateKeyToAccount(PRIVATE_KEY);\nconst wallet = createWalletClient({ account, chain: base, transport: http() });\nconst pub = createPublicClient({ chain: base, transport: http() });\n\n// From fulfillment response\nconst txData = response.fulfillment_data.transaction;\n\nconst hash = await wallet.sendTransaction({\n  to: txData.to,\n  data: txData.input_data.parameters ? encodeSeaportCall(txData.input_data) : txData.data,\n  value: BigInt(txData.value)\n});\n\nconst receipt = await pub.waitForTransactionReceipt({ hash });\nconsole.log(receipt.status === 'success' ? '✅ NFT purchased!' : '❌ Failed');\n```\n\n### Complete Working Example\n\n```javascript\n// buy-nft.mjs - Buy an NFT via OpenSea fulfillment API\nimport { createPublicClient, createWalletClient, http, encodeFunctionData } from 'viem';\nimport { privateKeyToAccount } from 'viem/accounts';\nimport { base } from 'viem/chains';\n\nconst SEAPORT_ABI = [{\n  name: 'fulfillBasicOrder_efficient_6GL6yc',\n  type: 'function',\n  stateMutability: 'payable',\n  inputs: [{\n    name: 'parameters',\n    type: 'tuple',\n    components: [\n      { name: 'considerationToken', type: 'address' },\n      { name: 'considerationIdentifier', type: 'uint256' },\n      { name: 'considerationAmount', type: 'uint256' },\n      { name: 'offerer', type: 'address' },\n      { name: 'zone', type: 'address' },\n      { name: 'offerToken', type: 'address' },\n      { name: 'offerIdentifier', type: 'uint256' },\n      { name: 'offerAmount', type: 'uint256' },\n      { name: 'basicOrderType', type: 'uint8' },\n      { name: 'startTime', type: 'uint256' },\n      { name: 'endTime', type: 'uint256' },\n      { name: 'zoneHash', type: 'bytes32' },\n      { name: 'salt', type: 'uint256' },\n      { name: 'offererConduitKey', type: 'bytes32' },\n      { name: 'fulfillerConduitKey', type: 'bytes32' },\n      { name: 'totalOriginalAdditionalRecipients', type: 'uint256' },\n      { name: 'additionalRecipients', type: 'tuple[]', components: [\n        { name: 'amount', type: 'uint256' },\n        { name: 'recipient', type: 'address' }\n      ]},\n      { name: 'signature', type: 'bytes' }\n    ]\n  }],\n  outputs: [{ name: 'fulfilled', type: 'bool' }]\n}];\n\nasync function buyNFT(orderHash, chain, buyerAddress, privateKey) {\n  // 1. Get fulfillment data\n  const res = await fetch('https://api.opensea.io/api/v2/listings/fulfillment_data', {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application/json',\n      'x-api-key': process.env.OPENSEA_API_KEY\n    },\n    body: JSON.stringify({\n      listing: { hash: orderHash, chain, protocol_address: '0x0000000000000068F116a894984e2DB1123eB395' },\n      fulfiller: { address: buyerAddress }\n    })\n  });\n  \n  const { fulfillment_data } = await res.json();\n  const tx = fulfillment_data.transaction;\n  const params = tx.input_data.parameters;\n  \n  // 2. Setup wallet\n  const account = privateKeyToAccount(privateKey);\n  const wallet = createWalletClient({ account, chain: base, transport: http() });\n  const pub = createPublicClient({ chain: base, transport: http() });\n  \n  // 3. Encode and send\n  const orderParams = {\n    ...params,\n    considerationIdentifier: BigInt(params.considerationIdentifier),\n    considerationAmount: BigInt(params.considerationAmount),\n    offerIdentifier: BigInt(params.offerIdentifier),\n    offerAmount: BigInt(params.offerAmount),\n    startTime: BigInt(params.startTime),\n    endTime: BigInt(params.endTime),\n    salt: BigInt(params.salt),\n    totalOriginalAdditionalRecipients: BigInt(params.totalOriginalAdditionalRecipients),\n    additionalRecipients: params.additionalRecipients.map(r => ({\n      amount: BigInt(r.amount),\n      recipient: r.recipient\n    }))\n  };\n  \n  const data = encodeFunctionData({\n    abi: SEAPORT_ABI,\n    functionName: 'fulfillBasicOrder_efficient_6GL6yc',\n    args: [orderParams]\n  });\n  \n  const hash = await wallet.sendTransaction({\n    to: tx.to,\n    data,\n    value: BigInt(tx.value)\n  });\n  \n  console.log(`TX: https://basescan.org/tx/${hash}`);\n  const receipt = await pub.waitForTransactionReceipt({ hash });\n  return receipt.status === 'success';\n}\n```\n\n---\n\n## Selling NFTs (Accepting Offers)\n\nSimilar workflow using `/api/v2/offers/fulfillment_data`:\n\n```bash\n./scripts/opensea-fulfill-offer.sh base 0xOFFER_HASH 0xYOUR_WALLET 0xNFT_CONTRACT 1234\n```\n\n---\n\n## Creating Listings\n\nCreating listings requires signing a Seaport order:\n\n1. Build order structure with offer (your NFT) and consideration (payment)\n2. Sign order with EIP-712\n3. POST signed order to OpenSea\n\nSee `references/marketplace-api.md` for full order structure.\n\n---\n\n## Key Points\n\n- **Fulfillment API returns ready-to-use calldata** - No SDK needed for buying\n- **Value field** tells you exactly how much ETH to send\n- **Works on all EVM chains** OpenSea supports\n- **Basic orders** use `fulfillBasicOrder_efficient_6GL6yc` function\n- **Advanced orders** use `fulfillAvailableAdvancedOrders` for partial fills\n\nFile v1.0.2:references/stream-api.md\n\n# OpenSea Stream API (WebSocket)\n\n## Base endpoint\nwss://stream.openseabeta.com/socket/websocket?token=YOUR_API_KEY\n\n## Join a collection channel\nSend a Phoenix join message:\n\n{\"topic\":\"collection:your-collection-slug\",\"event\":\"phx_join\",\"payload\":{},\"ref\":1}\n\nUse \"collection:*\" to subscribe globally.\n\n## Heartbeat\nSend every ~30 seconds:\n\n{\"topic\":\"phoenix\",\"event\":\"heartbeat\",\"payload\":{},\"ref\":0}\n\n## Event types\n- item_metadata_updated\n- item_listed\n- item_sold\n- item_transferred\n- item_received_bid\n- item_cancelled\n\n## Notes\n- Stream is WebSocket-based, not HTTP. curl is not suitable.\n- Use scripts/opensea-stream-collection.sh (websocat preferred).\n\nFile v1.0.2:references/token-swaps.md\n\n# Token Swaps via OpenSea MCP\n\nOpenSea MCP provides token swap functionality through integrated DEX aggregation. This allows swapping ERC20 tokens and native currencies across supported chains.\n\n## Overview\n\nThe `get_token_swap_quote` tool returns:\n1. **Quote details** - Expected output, fees, price impact\n2. **Transaction calldata** - Ready to submit on-chain\n\n## Supported Chains\n\n- Ethereum (`ethereum`)\n- Base (`base`)\n- Polygon (`matic`)\n- Arbitrum (`arbitrum`)\n- Optimism (`optimism`)\n\n## Getting a Swap Quote\n\n### Via mcporter CLI\n\n```bash\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\n### Parameters\n\n| Parameter | Required | Description |\n|-----------|----------|-------------|\n| `fromContractAddress` | Yes | Token to swap FROM. Use `0x0000...0000` for native ETH |\n| `toContractAddress` | Yes | Token to swap TO |\n| `fromChain` | Yes | Source chain identifier |\n| `toChain` | Yes | Destination chain identifier |\n| `fromQuantity` | Yes | Amount in human units (e.g., \"0.02\" for 0.02 ETH) |\n| `address` | Yes | Your wallet address |\n| `recipient` | No | Recipient address (defaults to sender) |\n| `slippageTolerance` | No | Slippage as decimal (e.g., 0.005 for 0.5%) |\n\n### Response Structure\n\n```json\n{\n  \"swapQuote\": {\n    \"swapRoutes\": [{\n      \"toAsset\": { \"symbol\": \"MOLT\", \"usdPrice\": \"0.00045\" },\n      \"fromAsset\": { \"symbol\": \"ETH\", \"usdPrice\": \"2370\" },\n      \"costs\": [\n        { \"costType\": \"GAS\", \"cost\": { \"usd\": 0.01 } },\n        { \"costType\": \"MARKETPLACE\", \"cost\": { \"usd\": 0.40 } }\n      ],\n      \"swapImpact\": { \"percent\": \"3.5\" }\n    }],\n    \"totalPrice\": { \"usd\": 47.40 }\n  },\n  \"swap\": {\n    \"actions\": [{\n      \"transactionSubmissionData\": {\n        \"to\": \"0xSwapRouterContract\",\n        \"data\": \"0x...\",\n        \"value\": \"20000000000000000\",\n        \"chain\": { \"networkId\": 8453, \"identifier\": \"base\" }\n      }\n    }]\n  }\n}\n```\n\n## Executing the Swap\n\n### Using viem (JavaScript)\n\n```javascript\nimport { createPublicClient, createWalletClient, http } from 'viem';\nimport { privateKeyToAccount } from 'viem/accounts';\nimport { base } from 'viem/chains';\n\n// Get quote first (via mcporter or direct API call)\nconst quote = await getSwapQuote(...);\nconst txData = quote.swap.actions[0].transactionSubmissionData;\n\n// Setup wallet\nconst account = privateKeyToAccount(PRIVATE_KEY);\nconst wallet = createWalletClient({ account, chain: base, transport: http() });\nconst pub = createPublicClient({ chain: base, transport: http() });\n\n// Execute swap\nconst hash = await wallet.sendTransaction({\n  to: txData.to,\n  data: txData.data,\n  value: BigInt(txData.value)\n});\n\nconsole.log(`TX: https://basescan.org/tx/${hash}`);\n\n// Wait for confirmation\nconst receipt = await pub.waitForTransactionReceipt({ hash });\nconsole.log(receipt.status === 'success' ? '✅ Swap complete!' : '❌ Failed');\n```\n\n### Using the swap script\n\n```bash\n./scripts/opensea-swap.sh <to_token_address> <amount_eth> <your_wallet> <private_key>\n\n# Example: Swap 0.02 ETH to MOLT\n./scripts/opensea-swap.sh 0xb695559b26bb2c9703ef1935c37aeae9526bab07 0.02 0xYourWallet 0xYourPrivateKey\n```\n\n## Finding Tokens\n\n### Search by name\n```bash\nmcporter call opensea.search_tokens --args '{\"query\": \"MOLT\", \"chain\": \"base\", \"limit\": 5}'\n```\n\n### Get trending tokens\n```bash\nmcporter call opensea.get_trending_tokens --args '{\"chains\": [\"base\"], \"limit\": 10}'\n```\n\n### Get top tokens by volume\n```bash\nmcporter call opensea.get_top_tokens --args '{\"chains\": [\"base\"], \"limit\": 10}'\n```\n\n## Checking Balances\n\n```bash\nmcporter call opensea.get_token_balances --args '{\n  \"address\": \"0xYourWallet\",\n  \"chains\": [\"base\", \"ethereum\"]\n}'\n```\n\n## Common Token Addresses (Base)\n\n| Token | Address |\n|-------|---------|\n| WETH | `0x4200000000000000000000000000000000000006` |\n| USDC | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |\n| MOLT | `0xb695559b26bb2c9703ef1935c37aeae9526bab07` |\n| CLAWD | `0x9f86db9fc6f7c9408e8fda3ff8ce4e78ac7a6b07` |\n| 4CLAW | `0x3b94a3fa7f33930cf9fdc5f36cb251533c947b07` |\n\n## Tips\n\n1. **Use native ETH address** (`0x0000...0000`) when swapping from ETH\n2. **Check slippage** - High impact swaps may fail; consider smaller amounts\n3. **Quote expiration** - Execute quickly after getting quote; prices change\n4. **Gas estimation** - The returned value includes all costs\n5. **Cross-chain swaps** - Same-chain swaps are faster and cheaper\n\nArchive v1.0.1: 26 files, 22945 bytes\n\nFiles: references/marketplace-api.md (9198b), references/rest-api.md (3935b), references/seaport.md (7026b), references/stream-api.md (661b), references/token-swaps.md (4604b), scripts/opensea-account-nfts.sh (483b), scripts/opensea-best-listing.sh (336b), scripts/opensea-best-offer.sh (330b), scripts/opensea-collection-nfts.sh (450b), scripts/opensea-collection-stats.sh (290b), scripts/opensea-collection.sh (210b), scripts/opensea-events-collection.sh (625b), scripts/opensea-fulfill-listing.sh (676b), scripts/opensea-fulfill-offer.sh (854b), scripts/opensea-get.sh (480b), scripts/opensea-listings-collection.sh (462b), scripts/opensea-listings-nft.sh (476b), scripts/opensea-nft.sh (285b), scripts/opensea-offers-collection.sh (458b), scripts/opensea-offers-nft.sh (470b), scripts/opensea-order.sh (374b), scripts/opensea-post.sh (527b), scripts/opensea-stream-collection.sh (958b), scripts/opensea-swap.sh (2908b), SKILL.md (10740b), _meta.json (130b)\n\nFile v1.0.1:SKILL.md\n\n# OpenSea API\n\nQuery NFT data, trade on the Seaport marketplace, and swap ERC20 tokens across Ethereum, Base, Arbitrum, Optimism, Polygon, and more.\n\n## Quick start\n\n1. Set `OPENSEA_API_KEY` in your environment\n2. Run helper scripts in `scripts/` for common operations\n3. Use the MCP server for token swaps and advanced queries\n\n```bash\nexport OPENSEA_API_KEY=\"your-api-key\"\n\n# Token swap: ETH to token\n./scripts/opensea-swap.sh 0xTokenAddress 0.1 0xYourWallet 0xYourKey base\n\n# Token swap: Token to token (specify from_token as last arg)\n./scripts/opensea-swap.sh 0xToToken 100 0xYourWallet 0xYourKey base 0xFromToken\n\n# Get collection info\n./scripts/opensea-collection.sh boredapeyachtclub\n\n# Get NFT details\n./scripts/opensea-nft.sh ethereum 0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d 1234\n\n# Get best listing price for an NFT\n./scripts/opensea-best-listing.sh boredapeyachtclub 1234\n```\n\n## Task guide\n\n### Token swaps\n\nOpenSea's API includes a cross-chain DEX aggregator for swapping ERC20 tokens with optimal routing across all supported chains.\n\n| Task | Tool/Script |\n|------|-------------|\n| Get swap quote with calldata | `get_token_swap_quote` (MCP) or `opensea-swap.sh` |\n| Check token balances | `get_token_balances` (MCP) |\n| Search tokens | `search_tokens` (MCP) |\n| Get trending tokens | `get_trending_tokens` (MCP) |\n| Get top tokens by volume | `get_top_tokens` (MCP) |\n\n### Reading NFT data\n\n| Task | Script |\n|------|--------|\n| Get collection details | `opensea-collection.sh <slug>` |\n| Get collection stats | `opensea-collection-stats.sh <slug>` |\n| List NFTs in collection | `opensea-collection-nfts.sh <slug> [limit] [next]` |\n| Get single NFT | `opensea-nft.sh <chain> <contract> <token_id>` |\n| List NFTs by wallet | `opensea-account-nfts.sh <chain> <address> [limit]` |\n\n### Marketplace queries\n\n| Task | Script |\n|------|--------|\n| Get best listing for NFT | `opensea-best-listing.sh <slug> <token_id>` |\n| Get best offer for NFT | `opensea-best-offer.sh <slug> <token_id>` |\n| List all collection listings | `opensea-listings-collection.sh <slug> [limit]` |\n| List all collection offers | `opensea-offers-collection.sh <slug> [limit]` |\n| Get listings for specific NFT | `opensea-listings-nft.sh <chain> <contract> <token_id>` |\n| Get offers for specific NFT | `opensea-offers-nft.sh <chain> <contract> <token_id>` |\n| Get order by hash | `opensea-order.sh <chain> <order_hash>` |\n\n### Marketplace actions (POST)\n\n| Task | Script |\n|------|--------|\n| Get fulfillment data (buy NFT) | `opensea-fulfill-listing.sh <chain> <order_hash> <buyer>` |\n| Get fulfillment data (accept offer) | `opensea-fulfill-offer.sh <chain> <order_hash> <seller> <contract> <token_id>` |\n| Generic POST request | `opensea-post.sh <path> <json_body>` |\n\n### Events and monitoring\n\n| Task | Script |\n|------|--------|\n| Get collection events | `opensea-events-collection.sh <slug> [event_type] [limit]` |\n| Stream real-time events | `opensea-stream-collection.sh <slug>` (requires websocat) |\n\n### Generic requests\n\n| Task | Script |\n|------|--------|\n| Any GET endpoint | `opensea-get.sh <path> [query]` |\n| Any POST endpoint | `opensea-post.sh <path> <json_body>` |\n\n## Buy/Sell workflows\n\n### Buying an NFT\n\n1. Find the NFT and check its listing:\n   ```bash\n   ./scripts/opensea-best-listing.sh cool-cats-nft 1234\n   ```\n\n2. Get the order hash from the response, then get fulfillment data:\n   ```bash\n   ./scripts/opensea-fulfill-listing.sh ethereum 0x_order_hash 0x_your_wallet\n   ```\n\n3. The response contains transaction data to execute on-chain\n\n### Selling an NFT (accepting an offer)\n\n1. Check offers on your NFT:\n   ```bash\n   ./scripts/opensea-best-offer.sh cool-cats-nft 1234\n   ```\n\n2. Get fulfillment data for the offer:\n   ```bash\n   ./scripts/opensea-fulfill-offer.sh ethereum 0x_offer_hash 0x_your_wallet 0x_nft_contract 1234\n   ```\n\n3. Execute the returned transaction data\n\n### Creating 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\n## Scripts reference\n\n### NFT & Collection Scripts\n| Script | Purpose |\n|--------|---------|\n| `opensea-get.sh` | Generic GET (path + optional query) |\n| `opensea-post.sh` | Generic POST (path + JSON body) |\n| `opensea-collection.sh` | Fetch collection by slug |\n| `opensea-collection-stats.sh` | Fetch collection statistics |\n| `opensea-collection-nfts.sh` | List NFTs in collection |\n| `opensea-nft.sh` | Fetch single NFT by chain/contract/token |\n| `opensea-account-nfts.sh` | List NFTs owned by wallet |\n\n### Marketplace Scripts\n| Script | Purpose |\n|--------|---------|\n| `opensea-listings-collection.sh` | All listings for collection |\n| `opensea-listings-nft.sh` | Listings for specific NFT |\n| `opensea-offers-collection.sh` | All offers for collection |\n| `opensea-offers-nft.sh` | Offers for specific NFT |\n| `opensea-best-listing.sh` | Lowest listing for NFT |\n| `opensea-best-offer.sh` | Highest offer for NFT |\n| `opensea-order.sh` | Get order by hash |\n| `opensea-fulfill-listing.sh` | Get buy transaction data |\n| `opensea-fulfill-offer.sh` | Get sell transaction data |\n\n### Token Swap Scripts\n| Script | Purpose |\n|--------|---------|\n| `opensea-swap.sh` | **Swap tokens via OpenSea MCP** |\n\n### Monitoring Scripts\n| Script | Purpose |\n|--------|---------|\n| `opensea-events-collection.sh` | Collection event history |\n| `opensea-stream-collection.sh` | Real-time WebSocket events |\n\n## Supported chains\n\n`ethereum`, `matic`, `arbitrum`, `optimism`, `base`, `avalanche`, `klaytn`, `zora`, `blast`, `sepolia`\n\n## References\n\n- `references/rest-api.md` - REST endpoint families and pagination\n- `references/marketplace-api.md` - Buy/sell workflows and Seaport details\n- `references/stream-api.md` - WebSocket event streaming\n- `references/seaport.md` - Seaport protocol and NFT purchase execution\n- `references/token-swaps.md` - **Token swap workflows via MCP**\n\n## OpenSea 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\n**Setup:**\n\n1. Go to the [OpenSea Developer Portal](https://opensea.io/settings/developer) and verify your email\n2. Generate a new API key for REST API access\n3. Generate a separate MCP token for the MCP server\n\nAdd to your MCP config:\n```json\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\n### Token Swap Tools\n| MCP Tool | Purpose |\n|----------|---------|\n| `get_token_swap_quote` | **Get swap calldata for token trades** |\n| `get_token_balances` | Check wallet token holdings |\n| `search_tokens` | Find tokens by name/symbol |\n| `get_trending_tokens` | Hot tokens by momentum |\n| `get_top_tokens` | Top tokens by 24h volume |\n| `get_tokens` | Get detailed token info |\n\n### NFT Tools\n| MCP Tool | Purpose |\n|----------|---------|\n| `search_collections` | Search NFT collections |\n| `search_items` | Search individual NFTs |\n| `get_collections` | Get detailed collection info |\n| `get_items` | Get detailed NFT info |\n| `get_nft_balances` | List NFTs owned by wallet |\n| `get_trending_collections` | Trending NFT collections |\n| `get_top_collections` | Top collections by volume |\n| `get_activity` | Trading activity for collections/items |\n| `get_upcoming_drops` | Upcoming NFT mints |\n\n### Profile & Utility Tools\n| MCP Tool | Purpose |\n|----------|---------|\n| `get_profile` | Wallet profile with holdings/activity |\n| `account_lookup` | Resolve ENS/address/username |\n| `get_chains` | List supported chains |\n| `search` | AI-powered natural language search |\n| `fetch` | Get full details by entity ID |\n\n---\n\n## Token Swaps via MCP\n\nOpenSea MCP supports ERC20 token swaps across supported DEXes - not just NFTs!\n\n### Get Swap Quote\n```bash\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\n**Parameters:**\n- `fromContractAddress`: Token to swap from (use `0x0000...0000` for native ETH)\n- `toContractAddress`: Token to swap to\n- `fromChain` / `toChain`: Chain identifiers\n- `fromQuantity`: Amount in human-readable units (e.g., \"0.02\" for 0.02 ETH)\n- `address`: Your wallet address\n\n**Response includes:**\n- `swapQuote`: Price info, fees, slippage impact\n- `swap.actions[0].transactionSubmissionData`: Ready-to-use calldata\n\n### Execute the Swap\n```javascript\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```\n\n### Check Token Balances\n```bash\nmcporter call opensea.get_token_balances --args '{\n  \"address\": \"0xYourWallet\",\n  \"chains\": [\"base\", \"ethereum\"]\n}'\n```\n\n## Generating a wallet\n\nTo execute swaps or buy NFTs, you need an Ethereum wallet (private key + address).\n\n### Using Node.js\n```javascript\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```\n\n### Using OpenSSL\n```bash\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```\n\n### Using cast (Foundry)\n```bash\ncast wallet new\n```\n\n**Important:** Store private keys securely. Never commit them to git or share publicly.\n\n## Requirements\n\n- `OPENSEA_API_KEY` environment variable (for REST API scripts)\n- `OPENSEA_MCP_TOKEN` environment variable (for MCP server, separate from API key)\n- `curl` for REST calls\n- `websocat` (optional) for Stream API\n- `jq` (recommended) for parsing JSON responses\n\nGet both credentials at [opensea.io/settings/developer](https://opensea.io/settings/developer).\n\nFile v1.0.1:_meta.json\n\n{\n  \"ownerId\": \"kn7176r43k8cwrwyv9h52051z9809n51\",\n  \"slug\": \"opensea-mcp\",\n  \"version\": \"1.0.1\",\n  \"publishedAt\": 1770511559632\n}\n\nFile v1.0.1:references/marketplace-api.md\n\n# OpenSea Marketplace API\n\nThis reference covers the marketplace endpoints for buying and selling NFTs on OpenSea.\n\n## Overview\n\nOpenSea uses the **Seaport protocol** for all marketplace orders. The API provides endpoints to:\n- Query existing listings and offers\n- Build new listings and offers (returns unsigned Seaport orders)\n- Fulfill orders (accept listings or offers)\n- Cancel orders\n\n**Important**: Creating and fulfilling orders requires wallet signatures. The API returns order data that must be signed client-side before submission.\n\n## Base URL and Authentication\n\n```\nBase URL: https://api.opensea.io/api/v2\nAuth: x-api-key: $OPENSEA_API_KEY\n```\n\n## Supported Chains\n\n| Chain | Identifier |\n|-------|------------|\n| Ethereum | `ethereum` |\n| Polygon | `matic` |\n| Arbitrum | `arbitrum` |\n| Optimism | `optimism` |\n| Base | `base` |\n| Avalanche | `avalanche` |\n| Klaytn | `klaytn` |\n| Zora | `zora` |\n| Blast | `blast` |\n| Sepolia (testnet) | `sepolia` |\n\n---\n\n## Read Operations (GET)\n\n### Get Best Listing for NFT\n\nReturns the lowest-priced active listing for an NFT.\n\n```bash\nGET /api/v2/listings/collection/{collection_slug}/nfts/{identifier}/best\n```\n\n**Parameters:**\n- `collection_slug`: Collection slug (e.g., `boredapeyachtclub`)\n- `identifier`: NFT identifier (token ID)\n\n**Example:**\n```bash\nscripts/opensea-get.sh \"/api/v2/listings/collection/boredapeyachtclub/nfts/1234/best\"\n```\n\n### Get Best Offer for NFT\n\nReturns the highest active offer for an NFT.\n\n```bash\nGET /api/v2/offers/collection/{collection_slug}/nfts/{identifier}/best\n```\n\n**Example:**\n```bash\nscripts/opensea-get.sh \"/api/v2/offers/collection/boredapeyachtclub/nfts/1234/best\"\n```\n\n### Get All Listings for Collection\n\nReturns all active listings for a collection.\n\n```bash\nGET /api/v2/listings/collection/{collection_slug}/all\n```\n\n**Query parameters:**\n- `limit`: Page size (default 50, max 100)\n- `next`: Cursor for pagination\n\n**Example:**\n```bash\nscripts/opensea-listings-collection.sh boredapeyachtclub 50\n```\n\n### Get All Offers for Collection\n\nReturns all active offers for a collection.\n\n```bash\nGET /api/v2/offers/collection/{collection_slug}/all\n```\n\n**Example:**\n```bash\nscripts/opensea-offers-collection.sh boredapeyachtclub 50\n```\n\n### Get Listings for Specific NFT\n\n```bash\nGET /api/v2/orders/{chain}/seaport/listings\n```\n\n**Query parameters:**\n- `asset_contract_address`: Contract address\n- `token_ids`: Comma-separated token IDs\n- `limit`, `next`: Pagination\n\n**Example:**\n```bash\nscripts/opensea-get.sh \"/api/v2/orders/ethereum/seaport/listings\" \"asset_contract_address=0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d&token_ids=1234\"\n```\n\n### Get Offers for Specific NFT\n\n```bash\nGET /api/v2/orders/{chain}/seaport/offers\n```\n\n**Query parameters:**\n- `asset_contract_address`: Contract address\n- `token_ids`: Comma-separated token IDs\n\n**Example:**\n```bash\nscripts/opensea-get.sh \"/api/v2/orders/ethereum/seaport/offers\" \"asset_contract_address=0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d&token_ids=1234\"\n```\n\n### Get Order by Hash\n\nRetrieve details of a specific order.\n\n```bash\nGET /api/v2/orders/chain/{chain}/protocol/{protocol_address}/hash/{order_hash}\n```\n\n**Example:**\n```bash\nscripts/opensea-get.sh \"/api/v2/orders/chain/ethereum/protocol/0x00000000000000adc04c56bf30ac9d3c0aaf14dc/hash/0x...\"\n```\n\n---\n\n## Write Operations (POST)\n\n### Build a Listing\n\nCreates an unsigned Seaport listing order. Returns order parameters to sign.\n\n```bash\nPOST /api/v2/orders/{chain}/seaport/listings\n```\n\n**Request body:**\n```json\n{\n  \"parameters\": {\n    \"offerer\": \"0xYourWalletAddress\",\n    \"offer\": [{\n      \"itemType\": 2,\n      \"token\": \"0xContractAddress\",\n      \"identifierOrCriteria\": \"1234\",\n      \"startAmount\": \"1\",\n      \"endAmount\": \"1\"\n    }],\n    \"consideration\": [{\n      \"itemType\": 0,\n      \"token\": \"0x0000000000000000000000000000000000000000\",\n      \"identifierOrCriteria\": \"0\",\n      \"startAmount\": \"1000000000000000000\",\n      \"endAmount\": \"1000000000000000000\",\n      \"recipient\": \"0xYourWalletAddress\"\n    }],\n    \"startTime\": \"1704067200\",\n    \"endTime\": \"1735689600\",\n    \"orderType\": 0,\n    \"zone\": \"0x0000000000000000000000000000000000000000\",\n    \"zoneHash\": \"0x0000000000000000000000000000000000000000000000000000000000000000\",\n    \"salt\": \"random_salt_value\",\n    \"conduitKey\": \"0x0000007b02230091a7ed01230072f7006a004d60a8d4e71d599b8104250f0000\",\n    \"totalOriginalConsiderationItems\": 1\n  },\n  \"signature\": \"0xSignedOrderSignature\"\n}\n```\n\n**Item Types:**\n- `0`: Native currency (ETH, MATIC, etc.)\n- `1`: ERC20 token\n- `2`: ERC721 NFT\n- `3`: ERC1155 NFT\n\n**Example (curl):**\n```bash\ncurl -X POST \"https://api.opensea.io/api/v2/orders/ethereum/seaport/listings\" \\\n  -H \"x-api-key: $OPENSEA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"parameters\": {...}, \"signature\": \"0x...\"}'\n```\n\n### Build an Offer\n\nCreates an unsigned Seaport offer order.\n\n```bash\nPOST /api/v2/orders/{chain}/seaport/offers\n```\n\n**Request body structure** (similar to listings, but offer contains payment and consideration contains NFT):\n```json\n{\n  \"parameters\": {\n    \"offerer\": \"0xBuyerWalletAddress\",\n    \"offer\": [{\n      \"itemType\": 1,\n      \"token\": \"0xWETHAddress\",\n      \"identifierOrCriteria\": \"0\",\n      \"startAmount\": \"1000000000000000000\",\n      \"endAmount\": \"1000000000000000000\"\n    }],\n    \"consideration\": [{\n      \"itemType\": 2,\n      \"token\": \"0xNFTContractAddress\",\n      \"identifierOrCriteria\": \"1234\",\n      \"startAmount\": \"1\",\n      \"endAmount\": \"1\",\n      \"recipient\": \"0xBuyerWalletAddress\"\n    }]\n  },\n  \"signature\": \"0x...\"\n}\n```\n\n### Fulfill a Listing (Buy NFT)\n\nAccept an existing listing to purchase an NFT.\n\n```bash\nPOST /api/v2/listings/fulfillment_data\n```\n\n**Request body:**\n```json\n{\n  \"listing\": {\n    \"hash\": \"0xOrderHash\",\n    \"chain\": \"ethereum\",\n    \"protocol_address\": \"0x00000000000000adc04c56bf30ac9d3c0aaf14dc\"\n  },\n  \"fulfiller\": {\n    \"address\": \"0xBuyerWalletAddress\"\n  }\n}\n```\n\n**Response:** Returns transaction data for the buyer to submit on-chain.\n\n### Fulfill an Offer (Sell NFT)\n\nAccept an existing offer to sell your NFT.\n\n```bash\nPOST /api/v2/offers/fulfillment_data\n```\n\n**Request body:**\n```json\n{\n  \"offer\": {\n    \"hash\": \"0xOfferOrderHash\",\n    \"chain\": \"ethereum\",\n    \"protocol_address\": \"0x00000000000000adc04c56bf30ac9d3c0aaf14dc\"\n  },\n  \"fulfiller\": {\n    \"address\": \"0xSellerWalletAddress\"\n  },\n  \"consideration\": {\n    \"asset_contract_address\": \"0xNFTContract\",\n    \"token_id\": \"1234\"\n  }\n}\n```\n\n### Cancel an Order\n\nCancel an active listing or offer.\n\n```bash\nPOST /api/v2/orders/chain/{chain}/protocol/{protocol_address}/hash/{order_hash}/cancel\n```\n\n**Note:** Cancellation requires an on-chain transaction. The API returns the transaction data to execute.\n\n---\n\n## Workflow: Buying an NFT\n\n1. **Find the NFT** - Use `opensea-nft.sh` to get NFT details\n2. **Check listings** - Use `opensea-get.sh` to get best listing\n3. **Get fulfillment data** - POST to `/api/v2/listings/fulfillment_data`\n4. **Execute transaction** - Sign and submit the returned transaction data\n\n```bash\n# Step 1: Get NFT info\n./scripts/opensea-nft.sh ethereum 0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d 1234\n\n# Step 2: Get best listing\n./scripts/opensea-get.sh \"/api/v2/listings/collection/boredapeyachtclub/nfts/1234/best\"\n\n# Step 3: Request fulfillment (requires POST - see marketplace scripts)\n./scripts/opensea-fulfill-listing.sh ethereum 0x_order_hash 0x_your_wallet\n```\n\n## Workflow: Selling an NFT (Creating a Listing)\n\n1. **Build the listing** - POST to `/api/v2/orders/{chain}/seaport/listings`\n2. **Sign the order** - Use wallet to sign the Seaport order\n3. **Submit signed order** - POST again with signature\n4. **Monitor** - Check listing via `/api/v2/listings/collection/{slug}/all`\n\n## Workflow: Making an Offer\n\n1. **Ensure WETH approval** - Buyer needs WETH allowance for Seaport\n2. **Build the offer** - POST to `/api/v2/orders/{chain}/seaport/offers`\n3. **Sign the order** - Wallet signature required\n4. **Submit** - POST with signature\n\n## Workflow: Accepting an Offer\n\n1. **View offers** - Use `opensea-offers-collection.sh`\n2. **Get fulfillment data** - POST to `/api/v2/offers/fulfillment_data`\n3. **Execute** - Submit the returned transaction\n\n---\n\n## Error Codes\n\n| Code | Meaning |\n|------|---------|\n| 400 | Bad request - invalid parameters |\n| 401 | Unauthorized - missing or invalid API key |\n| 404 | Not found - order/NFT doesn't exist |\n| 429 | Rate limited - too many requests |\n| 500 | Server error |\n\n## Rate Limits\n\n- Standard: 60 requests/minute\n- With API key: Higher limits (check your dashboard)\n\n---\n\n## Seaport Contract Addresses\n\n| Chain | Seaport 1.6 Address |\n|-------|---------------------|\n| All chains | `0x00000000000000ADc04C56Bf30aC9d3c0aAF14dC` |\n\n---\n\n## Tips\n\n1. **Always use WETH for offers** - Native ETH cannot be used for offers due to ERC20 approval requirements\n2. **Check approval status** - Before creating listings, ensure Seaport has approval for your NFTs\n3. **Test on Sepolia first** - Use testnet before mainnet transactions\n4. **Handle expiration** - Orders have startTime/endTime - check these before fulfilling\n5. **Monitor events** - Use Stream API for real-time order updates\n\nFile v1.0.1:references/rest-api.md\n\n# OpenSea REST API Reference\n\n## Base URL and Authentication\n\n```\nBase URL: https://api.opensea.io\nAuth header: x-api-key: $OPENSEA_API_KEY\n```\n\n## Pagination\n\nList endpoints support cursor-based pagination:\n- `limit`: Page size (default varies, max 100)\n- `next`: Cursor token from previous response\n\n## Supported Chains\n\n| Chain | Identifier |\n|-------|------------|\n| Ethereum | `ethereum` |\n| Polygon | `matic` |\n| Arbitrum | `arbitrum` |\n| Optimism | `optimism` |\n| Base | `base` |\n| Avalanche | `avalanche` |\n| Klaytn | `klaytn` |\n| Zora | `zora` |\n| Blast | `blast` |\n| Sepolia (testnet) | `sepolia` |\n\n## Endpoint Reference\n\n### Collections\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v2/collections/{slug}` | GET | Single collection details |\n| `/api/v2/collections/{slug}/stats` | GET | Collection statistics (floor, volume) |\n| `/api/v2/collections` | GET | List multiple collections |\n\n### NFTs\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v2/chain/{chain}/contract/{contract}/nfts/{token_id}` | GET | Single NFT details |\n| `/api/v2/collection/{slug}/nfts` | GET | NFTs by collection |\n| `/api/v2/chain/{chain}/account/{address}/nfts` | GET | NFTs by wallet |\n| `/api/v2/chain/{chain}/contract/{contract}/nfts` | GET | NFTs by contract |\n| `/api/v2/nft/{contract}/{token_id}/refresh` | POST | Refresh NFT metadata |\n\n### Listings\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v2/listings/collection/{slug}/all` | GET | All listings for collection |\n| `/api/v2/listings/collection/{slug}/nfts/{token_id}/best` | GET | Best listing for NFT |\n| `/api/v2/orders/{chain}/seaport/listings` | GET | Listings by contract/token |\n| `/api/v2/orders/{chain}/seaport/listings` | POST | Create new listing |\n| `/api/v2/listings/fulfillment_data` | POST | Get buy transaction data |\n\n### Offers\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v2/offers/collection/{slug}/all` | GET | All offers for collection |\n| `/api/v2/offers/collection/{slug}/nfts/{token_id}/best` | GET | Best offer for NFT |\n| `/api/v2/orders/{chain}/seaport/offers` | GET | Offers by contract/token |\n| `/api/v2/orders/{chain}/seaport/offers` | POST | Create new offer |\n| `/api/v2/offers/fulfillment_data` | POST | Get sell transaction data |\n\n### Orders\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v2/orders/chain/{chain}/protocol/{protocol}/{hash}` | GET | Get order by hash |\n| `/api/v2/orders/chain/{chain}/protocol/{protocol}/{hash}/cancel` | POST | Cancel order |\n\n### Events\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v2/events/collection/{slug}` | GET | Events by collection |\n| `/api/v2/events/chain/{chain}/contract/{contract}/nfts/{token_id}` | GET | Events by NFT |\n| `/api/v2/events/chain/{chain}/account/{address}` | GET | Events by account |\n\n### Accounts\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v2/accounts/{address}` | GET | Account profile |\n\n## Event Types\n\nFor the events endpoint, filter with `event_type`:\n- `sale` - NFT sold\n- `transfer` - NFT transferred\n- `listing` - New listing created\n- `offer` - New offer made\n- `cancel` - Order cancelled\n- `redemption` - NFT redeemed\n\n## Rate Limits\n\n- Without API key: 40 requests/minute\n- With API key: Higher limits (varies by tier)\n\n## Error Codes\n\n| Code | Meaning |\n|------|---------|\n| 400 | Bad request - check parameters |\n| 401 | Unauthorized - missing/invalid API key |\n| 404 | Resource not found |\n| 429 | Rate limited |\n| 500 | Server error |\n\n## Tips\n\n1. Use collection slugs (not addresses) for collection endpoints\n2. Use chain identifiers for NFT/account endpoints\n3. All timestamps are Unix epoch seconds\n4. Prices are in wei (divide by 10^18 for ETH)\n5. Use `jq` to parse JSON responses: `./script.sh | jq '.nft.name'`\n\nFile v1.0.1:references/seaport.md\n\n# Seaport (OpenSea marketplace protocol)\n\n## What it is\nSeaport is the marketplace protocol used for OpenSea orders. All listings and offers on OpenSea are Seaport orders under the hood.\n\n## Order structure\n- **Offer items**: What the offerer provides (e.g., an NFT for listings, WETH for offers)\n- **Consideration items**: What the offerer expects to receive (e.g., ETH payment + fees)\n\n## Seaport Contract Addresses\n\n| Chain | Seaport 1.6 Address |\n|-------|---------------------|\n| All EVM chains | `0x0000000000000068F116a894984e2DB1123eB395` |\n\nLegacy Seaport 1.4: `0x00000000000000ADc04C56Bf30aC9d3c0aAF14dC`\n\n---\n\n## Buying NFTs (Fulfilling Listings)\n\n**No SDK required!** The OpenSea API returns ready-to-use calldata.\n\n### Workflow\n\n1. **Find a listing** - Get order hash from listings endpoint\n2. **Get fulfillment data** - POST to fulfillment endpoint\n3. **Submit transaction** - Send calldata directly to blockchain\n\n### Step 1: Get Listings\n\n```bash\n# Via script\n./scripts/opensea-listings-collection.sh basenames\n\n# Via MCP\nmcporter call opensea.get_listings collection=\"basenames\" limit=10\n```\n\nNote the `order_hash` and `protocol_address` from the response.\n\n### Step 2: Get Fulfillment Calldata\n\n```bash\n# Via script\n./scripts/opensea-fulfill-listing.sh base 0xORDER_HASH 0xYOUR_WALLET\n\n# Via curl\ncurl -X POST \"https://api.opensea.io/api/v2/listings/fulfillment_data\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"x-api-key: $OPENSEA_API_KEY\" \\\n  -d '{\n    \"listing\": {\n      \"hash\": \"0xORDER_HASH\",\n      \"chain\": \"base\",\n      \"protocol_address\": \"0x0000000000000068F116a894984e2DB1123eB395\"\n    },\n    \"fulfiller\": {\n      \"address\": \"0xYOUR_WALLET\"\n    }\n  }'\n```\n\n**Response contains:**\n- `fulfillment_data.transaction.to` - Seaport contract\n- `fulfillment_data.transaction.value` - ETH to send (wei)\n- `fulfillment_data.transaction.input_data` - Encoded calldata\n\n### Step 3: Submit Transaction\n\n```javascript\nimport { createPublicClient, createWalletClient, http } from 'viem';\nimport { privateKeyToAccount } from 'viem/accounts';\nimport { base } from 'viem/chains';\n\nconst account = privateKeyToAccount(PRIVATE_KEY);\nconst wallet = createWalletClient({ account, chain: base, transport: http() });\nconst pub = createPublicClient({ chain: base, transport: http() });\n\n// From fulfillment response\nconst txData = response.fulfillment_data.transaction;\n\nconst hash = await wallet.sendTransaction({\n  to: txData.to,\n  data: txData.input_data.parameters ? encodeSeaportCall(txData.input_data) : txData.data,\n  value: BigInt(txData.value)\n});\n\nconst receipt = await pub.waitForTransactionReceipt({ hash });\nconsole.log(receipt.status === 'success' ? '✅ NFT purchased!' : '❌ Failed');\n```\n\n### Complete Working Example\n\n```javascript\n// buy-nft.mjs - Buy an NFT via OpenSea fulfillment API\nimport { createPublicClient, createWalletClient, http, encodeFunctionData } from 'viem';\nimport { privateKeyToAccount } from 'viem/accounts';\nimport { base } from 'viem/chains';\n\nconst SEAPORT_ABI = [{\n  name: 'fulfillBasicOrder_efficient_6GL6yc',\n  type: 'function',\n  stateMutability: 'payable',\n  inputs: [{\n    name: 'parameters',\n    type: 'tuple',\n    components: [\n      { name: 'considerationToken', type: 'address' },\n      { name: 'considerationIdentifier', type: 'uint256' },\n      { name: 'considerationAmount', type: 'uint256' },\n      { name: 'offerer', type: 'address' },\n      { name: 'zone', type: 'address' },\n      { name: 'offerToken', type: 'address' },\n      { name: 'offerIdentifier', type: 'uint256' },\n      { name: 'offerAmount', type: 'uint256' },\n      { name: 'basicOrderType', type: 'uint8' },\n      { name: 'startTime', type: 'uint256' },\n      { name: 'endTime', type: 'uint256' },\n      { name: 'zoneHash', type: 'bytes32' },\n      { name: 'salt', type: 'uint256' },\n      { name: 'offererConduitKey', type: 'bytes32' },\n      { name: 'fulfillerConduitKey', type: 'bytes32' },\n      { name: 'totalOriginalAdditionalRecipients', type: 'uint256' },\n      { name: 'additionalRecipients', type: 'tuple[]', components: [\n        { name: 'amount', type: 'uint256' },\n        { name: 'recipient', type: 'address' }\n      ]},\n      { name: 'signature', type: 'bytes' }\n    ]\n  }],\n  outputs: [{ name: 'fulfilled', type: 'bool' }]\n}];\n\nasync function buyNFT(orderHash, chain, buyerAddress, privateKey) {\n  // 1. Get fulfillment data\n  const res = await fetch('https://api.opensea.io/api/v2/listings/fulfillment_data', {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application/json',\n      'x-api-key': process.env.OPENSEA_API_KEY\n    },\n    body: JSON.stringify({\n      listing: { hash: orderHash, chain, protocol_address: '0x0000000000000068F116a894984e2DB1123eB395' },\n      fulfiller: { address: buyerAddress }\n    })\n  });\n  \n  const { fulfillment_data } = await res.json();\n  const tx = fulfillment_data.transaction;\n  const params = tx.input_data.parameters;\n  \n  // 2. Setup wallet\n  const account = privateKeyToAccount(privateKey);\n  const wallet = createWalletClient({ account, chain: base, transport: http() });\n  const pub = createPublicClient({ chain: base, transport: http() });\n  \n  // 3. Encode and send\n  const orderParams = {\n    ...params,\n    considerationIdentifier: BigInt(params.considerationIdentifier),\n    considerationAmount: BigInt(params.considerationAmount),\n    offerIdentifier: BigInt(params.offerIdentifier),\n    offerAmount: BigInt(params.offerAmount),\n    startTime: BigInt(params.startTime),\n    endTime: BigInt(params.endTime),\n    salt: BigInt(params.salt),\n    totalOriginalAdditionalRecipients: BigInt(params.totalOriginalAdditionalRecipients),\n    additionalRecipients: params.additionalRecipients.map(r => ({\n      amount: BigInt(r.amount),\n      recipient: r.recipient\n    }))\n  };\n  \n  const data = encodeFunctionData({\n    abi: SEAPORT_ABI,\n    functionName: 'fulfillBasicOrder_efficient_6GL6yc',\n    args: [orderParams]\n  });\n  \n  const hash = await wallet.sendTransaction({\n    to: tx.to,\n    data,\n    value: BigInt(tx.value)\n  });\n  \n  console.log(`TX: https://basescan.org/tx/${hash}`);\n  const receipt = await pub.waitForTransactionReceipt({ hash });\n  return receipt.status === 'success';\n}\n```\n\n---\n\n## Selling NFTs (Accepting Offers)\n\nSimilar workflow using `/api/v2/offers/fulfillment_data`:\n\n```bash\n./scripts/opensea-fulfill-offer.sh base 0xOFFER_HASH 0xYOUR_WALLET 0xNFT_CONTRACT 1234\n```\n\n---\n\n## Creating Listings\n\nCreating listings requires signing a Seaport order:\n\n1. Build order structure with offer (your NFT) and consideration (payment)\n2. Sign order with EIP-712\n3. POST signed order to OpenSea\n\nSee `references/marketplace-api.md` for full order structure.\n\n---\n\n## Key Points\n\n- **Fulfillment API returns ready-to-use calldata** - No SDK needed for buying\n- **Value field** tells you exactly how much ETH to send\n- **Works on all EVM chains** OpenSea supports\n- **Basic orders** use `fulfillBasicOrder_efficient_6GL6yc` function\n- **Advanced orders** use `fulfillAvailableAdvancedOrders` for partial fills\n\nFile v1.0.1:references/stream-api.md\n\n# OpenSea Stream API (WebSocket)\n\n## Base endpoint\nwss://stream.openseabeta.com/socket/websocket?token=YOUR_API_KEY\n\n## Join a collection channel\nSend a Phoenix join message:\n\n{\"topic\":\"collection:your-collection-slug\",\"event\":\"phx_join\",\"payload\":{},\"ref\":1}\n\nUse \"collection:*\" to subscribe globally.\n\n## Heartbeat\nSend every ~30 seconds:\n\n{\"topic\":\"phoenix\",\"event\":\"heartbeat\",\"payload\":{},\"ref\":0}\n\n## Event types\n- item_metadata_updated\n- item_listed\n- item_sold\n- item_transferred\n- item_received_bid\n- item_cancelled\n\n## Notes\n- Stream is WebSocket-based, not HTTP. curl is not suitable.\n- Use scripts/opensea-stream-collection.sh (websocat preferred).\n\nFile v1.0.1:references/token-swaps.md\n\n# Token Swaps via OpenSea MCP\n\nOpenSea MCP provides token swap functionality through integrated DEX aggregation. This allows swapping ERC20 tokens and native currencies across supported chains.\n\n## Overview\n\nThe `get_token_swap_quote` tool returns:\n1. **Quote details** - Expected output, fees, price impact\n2. **Transaction calldata** - Ready to submit on-chain\n\n## Supported Chains\n\n- Ethereum (`ethereum`)\n- Base (`base`)\n- Polygon (`matic`)\n- Arbitrum (`arbitrum`)\n- Optimism (`optimism`)\n\n## Getting a Swap Quote\n\n### Via mcporter CLI\n\n```bash\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\n### Parameters\n\n| Parameter | Required | Description |\n|-----------|----------|-------------|\n| `fromContractAddress` | Yes | Token to swap FROM. Use `0x0000...0000` for native ETH |\n| `toContractAddress` | Yes | Token to swap TO |\n| `fromChain` | Yes | Source chain identifier |\n| `toChain` | Yes | Destination chain identifier |\n| `fromQuantity` | Yes | Amount in human units (e.g., \"0.02\" for 0.02 ETH) |\n| `address` | Yes | Your wallet address |\n| `recipient` | No | Recipient address (defaults to sender) |\n| `slippageTolerance` | No | Slippage as decimal (e.g., 0.005 for 0.5%) |\n\n### Response Structure\n\n```json\n{\n  \"swapQuote\": {\n    \"swapRoutes\": [{\n      \"toAsset\": { \"symbol\": \"MOLT\", \"usdPrice\": \"0.00045\" },\n      \"fromAsset\": { \"symbol\": \"ETH\", \"usdPrice\": \"2370\" },\n      \"costs\": [\n        { \"costType\": \"GAS\", \"cost\": { \"usd\": 0.01 } },\n        { \"costType\": \"MARKETPLACE\", \"cost\": { \"usd\": 0.40 } }\n      ],\n      \"swapImpact\": { \"percent\": \"3.5\" }\n    }],\n    \"totalPrice\": { \"usd\": 47.40 }\n  },\n  \"swap\": {\n    \"actions\": [{\n      \"transactionSubmissionData\": {\n        \"to\": \"0xSwapRouterContract\",\n        \"data\": \"0x...\",\n        \"value\": \"20000000000000000\",\n        \"chain\": { \"networkId\": 8453, \"identifier\": \"base\" }\n      }\n    }]\n  }\n}\n```\n\n## Executing the Swap\n\n### Using viem (JavaScript)\n\n```javascript\nimport { createPublicClient, createWalletClient, http } from 'viem';\nimport { privateKeyToAccount } from 'viem/accounts';\nimport { base } from 'viem/chains';\n\n// Get quote first (via mcporter or direct API call)\nconst quote = await getSwapQuote(...);\nconst txData = quote.swap.actions[0].transactionSubmissionData;\n\n// Setup wallet\nconst account = privateKeyToAccount(PRIVATE_KEY);\nconst wallet = createWalletClient({ account, chain: base, transport: http() });\nconst pub = createPublicClient({ chain: base, transport: http() });\n\n// Execute swap\nconst hash = await wallet.sendTransaction({\n  to: txData.to,\n  data: txData.data,\n  value: BigInt(txData.value)\n});\n\nconsole.log(`TX: https://basescan.org/tx/${hash}`);\n\n// Wait for confirmation\nconst receipt = await pub.waitForTransactionReceipt({ hash });\nconsole.log(receipt.status === 'success' ? '✅ Swap complete!' : '❌ Failed');\n```\n\n### Using the swap script\n\n```bash\n./scripts/opensea-swap.sh <to_token_address> <amount_eth> <your_wallet> <private_key>\n\n# Example: Swap 0.02 ETH to MOLT\n./scripts/opensea-swap.sh 0xb695559b26bb2c9703ef1935c37aeae9526bab07 0.02 0xYourWallet 0xYourPrivateKey\n```\n\n## Finding Tokens\n\n### Search by name\n```bash\nmcporter call opensea.search_tokens --args '{\"query\": \"MOLT\", \"chain\": \"base\", \"limit\": 5}'\n```\n\n### Get trending tokens\n```bash\nmcporter call opensea.get_trending_tokens --args '{\"chains\": [\"base\"], \"limit\": 10}'\n```\n\n### Get top tokens by volume\n```bash\nmcporter call opensea.get_top_tokens --args '{\"chains\": [\"base\"], \"limit\": 10}'\n```\n\n## Checking Balances\n\n```bash\nmcporter call opensea.get_token_balances --args '{\n  \"address\": \"0xYourWallet\",\n  \"chains\": [\"base\", \"ethereum\"]\n}'\n```\n\n## Common Token Addresses (Base)\n\n| Token | Address |\n|-------|---------|\n| WETH | `0x4200000000000000000000000000000000000006` |\n| USDC | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |\n| MOLT | `0xb695559b26bb2c9703ef1935c37aeae9526bab07` |\n| CLAWD | `0x9f86db9fc6f7c9408e8fda3ff8ce4e78ac7a6b07` |\n| 4CLAW | `0x3b94a3fa7f33930cf9fdc5f36cb251533c947b07` |\n\n## Tips\n\n1. **Use native ETH address** (`0x0000...0000`) when swapping from ETH\n2. **Check slippage** - High impact swaps may fail; consider smaller amounts\n3. **Quote expiration** - Execute quickly after getting quote; prices change\n4. **Gas estimation** - The returned value includes all costs\n5. **Cross-chain swaps** - Same-chain swaps are faster and cheaper","readmeExcerpt":"Skill: OpenSea Owner: dfinzer Summary: Query OpenSea NFT marketplace data via official MCP server. Get floor prices, trending collections, token prices, wallet balances, swap quotes, and NFT holdings. Supports Ethereum, Base, Polygon, Solana, and other major chains. Requires OpenSea developer account for MCP token. Tags: latest:1.0.2 Version history: v1.0.2 | 2026-02-08T01:16:59.679Z | user Version 1.0.2 - Documentat","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"export OPENSEA_API_KEY=\"your-api-key\"\n\n# Token swap: ETH to token\n./scripts/opensea-swap.sh 0xTokenAddress 0.1 0xYourWallet 0xYourKey base\n\n# Token swap: Token to token (specify from_token as last arg)\n./scripts/opensea-swap.sh 0xToToken 100 0xYourWallet 0xYourKey base 0xFromToken\n\n# Get collection info\n./scripts/opensea-collection.sh boredapeyachtclub\n\n# Get NFT details\n./scripts/opensea-nft.sh ethereum 0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d 1234\n\n# Get best listing price for an NFT\n./scripts/opensea-best-listing.sh boredapeyachtclub 1234"},{"language":"bash","snippet":"./scripts/opensea-best-listing.sh cool-cats-nft 1234"},{"language":"bash","snippet":"./scripts/opensea-fulfill-listing.sh ethereum 0x_order_hash 0x_your_wallet"},{"language":"bash","snippet":"./scripts/opensea-best-offer.sh cool-cats-nft 1234"},{"language":"bash","snippet":"./scripts/opensea-fulfill-offer.sh ethereum 0x_offer_hash 0x_your_wallet 0x_nft_contract 1234"},{"language":"json","snippet":"{\n  \"mcpServers\": {\n    \"opensea\": {\n      \"url\": \"https://mcp.opensea.io/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_MCP_TOKEN\"\n      }\n    }\n  }\n}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"# OpenSea API\n\nQuery NFT data, trade on the Seaport marketplace, and swap ERC20 tokens across Ethereum, Base, Arbitrum, Optimism, Polygon, and more.\n\n## Quick start\n\n1. Set `OPENSEA_API_KEY` in your environment\n2. Run helper scripts in `scripts/` for common operations\n3. Use the MCP server for token swaps and advanced queries\n\n```bash\nexport OPENSEA_API_KEY=\"your-api-key\"\n\n# Token swap: ETH to token\n./scripts/opensea-swap.sh 0xTokenAddress 0.1 0xYourWallet 0xYourKey base\n\n# Token swap: Token to token (specify from_token as last arg)\n./scripts/opensea-swap.sh 0xToToken 100 0xYourWallet 0xYourKey base 0xFromToken\n\n# Get collection info\n./scripts/opensea-collection.sh boredapeyachtclub\n\n# Get NFT details\n./scripts/opensea-nft.sh ethereum 0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d 1234\n\n# Get best listing price for an NFT\n./scripts/opensea-best-listing.sh boredapeyachtclub 1234\n```\n\n## Task guide\n\n### Token swaps\n\nOpenSea's API includes a cross-chain DEX aggregator for swapping ERC20 tokens with optimal routing across all supported chains.\n\n| Task | Tool/Script |\n|------|-------------|\n| Get swap quote with calldata | `get_token_swap_quote` (MCP) or `opensea-swap.sh` |\n| Check token balances | `get_token_balances` (MCP) |\n| Search tokens | `search_tokens` (MCP) |\n| Get trending tokens | `get_trending_tokens` (MCP) |\n| Get top tokens by volume | `get_top_tokens` (MCP) |\n\n### Reading NFT data\n\n| Task | Script |\n|------|--------|\n| Get collection details | `opensea-collection.sh <slug>` |\n| Get collection stats | `opensea-collection-stats.sh <slug>` |\n| List NFTs in collection | `opensea-collection-nfts.sh <slug> [limit] [next]` |\n| Get single NFT | `opensea-nft.sh <chain> <contract> <token_id>` |\n| List NFTs by wallet | `opensea-account-nfts.sh <chain> <address> [limit]` |\n\n### Marketplace queries\n\n| Task | Script |\n|------|--------|\n| Get best listing for NFT | `opensea-best-listing.sh <slug> <token_id>` |\n| Get best offer for NFT | `opensea-best-offer.sh <slug> <token_id>` |\n| List all collection listings | `opensea-listings-collection.sh <slug> [limit]` |\n| List all collection offers | `opensea-offers-collection.sh <slug> [limit]` |\n| Get listings for specific NFT | `opensea-listings-nft.sh <chain> <contract> <token_id>` |\n| Get offers for specific NFT | `opensea-offers-nft.sh <chain> <contract> <token_id>` |\n| Get order by hash | `opensea-order.sh <chain> <order_hash>` |\n\n### Marketplace actions (POST)\n\n| Task | Script |\n|------|--------|\n| Get fulfillment data (buy NFT) | `opensea-fulfill-listing.sh <chain> <order_hash> <buyer>` |\n| Get fulfillment data (accept offer) | `opensea-fulfill-offer.sh <chain> <order_hash> <seller> <contract> <token_id>` |\n| Generic POST request | `opensea-post.sh <path> <json_body>` |\n\n### Events and monitoring\n\n| Task | Script |\n|------|--------|\n| Get collection events | `opensea-events-collection.sh <slug> [event_type] [limit]` |\n| Stream real-time events | `opensea-stream-collection.sh <slug>` (requires websocat) |\n"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7176r43k8cwrwyv9h52051z9809n51\",\n  \"slug\": \"opensea-mcp\",\n  \"version\": \"1.0.2\",\n  \"publishedAt\": 1770513419679\n}"},{"path":"references/marketplace-api.md","content":"# OpenSea Marketplace API\n\nThis reference covers the marketplace endpoints for buying and selling NFTs on OpenSea.\n\n## Overview\n\nOpenSea uses the **Seaport protocol** for all marketplace orders. The API provides endpoints to:\n- Query existing listings and offers\n- Build new listings and offers (returns unsigned Seaport orders)\n- Fulfill orders (accept listings or offers)\n- Cancel orders\n\n**Important**: Creating and fulfilling orders requires wallet signatures. The API returns order data that must be signed client-side before submission.\n\n## Base URL and Authentication\n\n```\nBase URL: https://api.opensea.io/api/v2\nAuth: x-api-key: $OPENSEA_API_KEY\n```\n\n## Supported Chains\n\n| Chain | Identifier |\n|-------|------------|\n| Ethereum | `ethereum` |\n| Polygon | `matic` |\n| Arbitrum | `arbitrum` |\n| Optimism | `optimism` |\n| Base | `base` |\n| Avalanche | `avalanche` |\n| Klaytn | `klaytn` |\n| Zora | `zora` |\n| Blast | `blast` |\n| Sepolia (testnet) | `sepolia` |\n\n---\n\n## Read Operations (GET)\n\n### Get Best Listing for NFT\n\nReturns the lowest-priced active listing for an NFT.\n\n```bash\nGET /api/v2/listings/collection/{collection_slug}/nfts/{identifier}/best\n```\n\n**Parameters:**\n- `collection_slug`: Collection slug (e.g., `boredapeyachtclub`)\n- `identifier`: NFT identifier (token ID)\n\n**Example:**\n```bash\nscripts/opensea-get.sh \"/api/v2/listings/collection/boredapeyachtclub/nfts/1234/best\"\n```\n\n### Get Best Offer for NFT\n\nReturns the highest active offer for an NFT.\n\n```bash\nGET /api/v2/offers/collection/{collection_slug}/nfts/{identifier}/best\n```\n\n**Example:**\n```bash\nscripts/opensea-get.sh \"/api/v2/offers/collection/boredapeyachtclub/nfts/1234/best\"\n```\n\n### Get All Listings for Collection\n\nReturns all active listings for a collection.\n\n```bash\nGET /api/v2/listings/collection/{collection_slug}/all\n```\n\n**Query parameters:**\n- `limit`: Page size (default 50, max 100)\n- `next`: Cursor for pagination\n\n**Example:**\n```bash\nscripts/opensea-listings-collection.sh boredapeyachtclub 50\n```\n\n### Get All Offers for Collection\n\nReturns all active offers for a collection.\n\n```bash\nGET /api/v2/offers/collection/{collection_slug}/all\n```\n\n**Example:**\n```bash\nscripts/opensea-offers-collection.sh boredapeyachtclub 50\n```\n\n### Get Listings for Specific NFT\n\n```bash\nGET /api/v2/orders/{chain}/seaport/listings\n```\n\n**Query parameters:**\n- `asset_contract_address`: Contract address\n- `token_ids`: Comma-separated token IDs\n- `limit`, `next`: Pagination\n\n**Example:**\n```bash\nscripts/opensea-get.sh \"/api/v2/orders/ethereum/seaport/listings\" \"asset_contract_address=0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d&token_ids=1234\"\n```\n\n### Get Offers for Specific NFT\n\n```bash\nGET /api/v2/orders/{chain}/seaport/offers\n```\n\n**Query parameters:**\n- `asset_contract_address`: Contract address\n- `token_ids`: Comma-separated token IDs\n\n**Example:**\n```bash\nscripts/opensea-get.sh \"/api/v2/orders/ethereum/seaport/offers\" \"asset_contract_address=0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d&token_ids"},{"path":"references/rest-api.md","content":"# OpenSea REST API Reference\n\n## Base URL and Authentication\n\n```\nBase URL: https://api.opensea.io\nAuth header: x-api-key: $OPENSEA_API_KEY\n```\n\n## Pagination\n\nList endpoints support cursor-based pagination:\n- `limit`: Page size (default varies, max 100)\n- `next`: Cursor token from previous response\n\n## Supported Chains\n\n| Chain | Identifier |\n|-------|------------|\n| Ethereum | `ethereum` |\n| Polygon | `matic` |\n| Arbitrum | `arbitrum` |\n| Optimism | `optimism` |\n| Base | `base` |\n| Avalanche | `avalanche` |\n| Klaytn | `klaytn` |\n| Zora | `zora` |\n| Blast | `blast` |\n| Sepolia (testnet) | `sepolia` |\n\n## Endpoint Reference\n\n### Collections\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v2/collections/{slug}` | GET | Single collection details |\n| `/api/v2/collections/{slug}/stats` | GET | Collection statistics (floor, volume) |\n| `/api/v2/collections` | GET | List multiple collections |\n\n### NFTs\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v2/chain/{chain}/contract/{contract}/nfts/{token_id}` | GET | Single NFT details |\n| `/api/v2/collection/{slug}/nfts` | GET | NFTs by collection |\n| `/api/v2/chain/{chain}/account/{address}/nfts` | GET | NFTs by wallet |\n| `/api/v2/chain/{chain}/contract/{contract}/nfts` | GET | NFTs by contract |\n| `/api/v2/nft/{contract}/{token_id}/refresh` | POST | Refresh NFT metadata |\n\n### Listings\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v2/listings/collection/{slug}/all` | GET | All listings for collection |\n| `/api/v2/listings/collection/{slug}/nfts/{token_id}/best` | GET | Best listing for NFT |\n| `/api/v2/orders/{chain}/seaport/listings` | GET | Listings by contract/token |\n| `/api/v2/orders/{chain}/seaport/listings` | POST | Create new listing |\n| `/api/v2/listings/fulfillment_data` | POST | Get buy transaction data |\n\n### Offers\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v2/offers/collection/{slug}/all` | GET | All offers for collection |\n| `/api/v2/offers/collection/{slug}/nfts/{token_id}/best` | GET | Best offer for NFT |\n| `/api/v2/orders/{chain}/seaport/offers` | GET | Offers by contract/token |\n| `/api/v2/orders/{chain}/seaport/offers` | POST | Create new offer |\n| `/api/v2/offers/fulfillment_data` | POST | Get sell transaction data |\n\n### Orders\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v2/orders/chain/{chain}/protocol/{protocol}/{hash}` | GET | Get order by hash |\n| `/api/v2/orders/chain/{chain}/protocol/{protocol}/{hash}/cancel` | POST | Cancel order |\n\n### Events\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v2/events/collection/{slug}` | GET | Events by collection |\n| `/api/v2/events/chain/{chain}/contract/{contract}/nfts/{token_id}` | GET | Events by NFT |\n| `/api/v2/events/chain/{chain}/account/{address}` | GET | Events by account |\n\n### Accounts\n\n| Endpoint | Method | Description |\n|"},{"path":"references/seaport.md","content":"# Seaport (OpenSea marketplace protocol)\n\n## What it is\nSeaport is the marketplace protocol used for OpenSea orders. All listings and offers on OpenSea are Seaport orders under the hood.\n\n## Order structure\n- **Offer items**: What the offerer provides (e.g., an NFT for listings, WETH for offers)\n- **Consideration items**: What the offerer expects to receive (e.g., ETH payment + fees)\n\n## Seaport Contract Addresses\n\n| Chain | Seaport 1.6 Address |\n|-------|---------------------|\n| All EVM chains | `0x0000000000000068F116a894984e2DB1123eB395` |\n\nLegacy Seaport 1.4: `0x00000000000000ADc04C56Bf30aC9d3c0aAF14dC`\n\n---\n\n## Buying NFTs (Fulfilling Listings)\n\n**No SDK required!** The OpenSea API returns ready-to-use calldata.\n\n### Workflow\n\n1. **Find a listing** - Get order hash from listings endpoint\n2. **Get fulfillment data** - POST to fulfillment endpoint\n3. **Submit transaction** - Send calldata directly to blockchain\n\n### Step 1: Get Listings\n\n```bash\n# Via script\n./scripts/opensea-listings-collection.sh basenames\n\n# Via MCP\nmcporter call opensea.get_listings collection=\"basenames\" limit=10\n```\n\nNote the `order_hash` and `protocol_address` from the response.\n\n### Step 2: Get Fulfillment Calldata\n\n```bash\n# Via script\n./scripts/opensea-fulfill-listing.sh base 0xORDER_HASH 0xYOUR_WALLET\n\n# Via curl\ncurl -X POST \"https://api.opensea.io/api/v2/listings/fulfillment_data\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"x-api-key: $OPENSEA_API_KEY\" \\\n  -d '{\n    \"listing\": {\n      \"hash\": \"0xORDER_HASH\",\n      \"chain\": \"base\",\n      \"protocol_address\": \"0x0000000000000068F116a894984e2DB1123eB395\"\n    },\n    \"fulfiller\": {\n      \"address\": \"0xYOUR_WALLET\"\n    }\n  }'\n```\n\n**Response contains:**\n- `fulfillment_data.transaction.to` - Seaport contract\n- `fulfillment_data.transaction.value` - ETH to send (wei)\n- `fulfillment_data.transaction.input_data` - Encoded calldata\n\n### Step 3: Submit Transaction\n\n```javascript\nimport { createPublicClient, createWalletClient, http } from 'viem';\nimport { privateKeyToAccount } from 'viem/accounts';\nimport { base } from 'viem/chains';\n\nconst account = privateKeyToAccount(PRIVATE_KEY);\nconst wallet = createWalletClient({ account, chain: base, transport: http() });\nconst pub = createPublicClient({ chain: base, transport: http() });\n\n// From fulfillment response\nconst txData = response.fulfillment_data.transaction;\n\nconst hash = await wallet.sendTransaction({\n  to: txData.to,\n  data: txData.input_data.parameters ? encodeSeaportCall(txData.input_data) : txData.data,\n  value: BigInt(txData.value)\n});\n\nconst receipt = await pub.waitForTransactionReceipt({ hash });\nconsole.log(receipt.status === 'success' ? '✅ NFT purchased!' : '❌ Failed');\n```\n\n### Complete Working Example\n\n```javascript\n// buy-nft.mjs - Buy an NFT via OpenSea fulfillment API\nimport { createPublicClient, createWalletClient, http, encodeFunctionData } from 'viem';\nimport { privateKeyToAccount } from 'viem/accounts';\nimport { base } from 'viem/chains';\n\nconst SEAPO"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1286,"uniquenessScore":40,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:15:20.027Z","emptyReason":null},"items":[{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-10T18:48:31.762Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}