| name | @4885/opensea |
| version | 1.1.0 |
| description | OpenSea API integration for NFT and token discovery, marketplace intelligence, and order/transaction workflows.
Use when working with OpenSea data or trading flows (e.g. collection stats, trending collections/tokens, NFT metadata, listings/offers, swap quotes, transaction receipt polling). |
| author | kristina |
| tags | ["opensea","nft","marketplace","listings","offers","swaps"] |
| metadata | {"starchild":{"emoji":"🧿","skillKey":"opensea","requires":{"anyBins":["python3","python"]}}} |
| user-invocable | true |
What this skill is for
Use this skill when the user asks for anything OpenSea-specific: NFT collection research, account portfolio views, listing/offer discovery, market events, token intel, or OpenSea trading workflow support.
Primary docs source:
API key strategy
OpenSea supports instant free-tier key creation (documented under Create an instant API key).
Use this decision rule:
- If read-only request is small/occasional: create/use instant key.
- If user wants sustained/production usage or higher throughput: request user-provided key via secure env input.
Never ask user to paste keys in chat.
Request pattern (Python scripts)
For any script you write for this skill:
- Use
from core.http_client import proxied_get, proxied_post
- Add usage tracking header:
headers={"SC-CALLER-ID": "chat:<thread_id>"} (or job/preview typed prefix when relevant)
- Read key from env if available (e.g.,
OPENSEA_API_KEY) and pass as X-API-KEY
- If key missing and task needs authenticated throughput, use
request_env_input
Endpoint families to prioritize
Use OpenSea V2 reference endpoints grouped by intent:
- Discovery / analytics
- collections: stats, traits, top/trending, holders, floor history
- NFTs: metadata, owners, analytics, by collection/account/contract
- events: global/by collection/by NFT/by account
- search: cross-entity search
- Marketplace intelligence
- listings: best listing by NFT/collection, all listings by collection
- offers: best offer by NFT, collection offers, trait offers
- orders: get order, cancel order
- Execution planning (no fabricated confirmations)
- listing/offer fulfillment data endpoints
- sweep and cross-chain fulfillment endpoints
- swaps: quote + execute transaction payloads
- transaction receipt endpoint for verification polling
Safety and verification
- Never claim a buy/list/swap/fulfillment is complete without receipt/status confirmation.
- Treat OpenSea as quote/action builder unless on-chain submission + receipt confirms execution.
- If endpoint output omits a hash or status, explicitly say it was not returned.
Common workflow templates
A) Collection research request
- Resolve slug/collection.
- Pull stats + floor history + traits.
- Pull recent events.
- Summarize liquidity, turnover, and near-term risk (washy volume, thin listings, trait concentration).
B) “Should I sweep this collection?”
- Fetch best listings and recent sales events.
- Compare spread vs recent clears.
- Evaluate depth (how many items near floor).
- If user wants action: generate sweep transaction plan and clearly label it as pending execution until receipt confirmed.
C) “Buy/list this NFT”
- Pull best listing/offer + order details.
- Generate fulfillment/listing actions.
- Have wallet sign/broadcast via wallet tooling.
- Poll transaction receipt endpoint and report verified state.
Known doc anchors
- API overview:
/reference/api-overview
- API key flow:
/reference/api-keys
- LLM/agent discovery:
/reference/llms-agent-discovery
- SDKs:
/reference/opensea-js, /reference/opensea-cli, /reference/stream-js
If endpoint behavior conflicts with assumptions, trust live docs and response payloads over memory.
Script usage
Script-mode skill — import from skills/opensea/exports.py.
python3 - <<'EOF'
import sys, json
sys.path.insert(0, "/data/workspace/skills/opensea")
from exports import os_collection_stats, os_search
print(json.dumps(os_collection_stats("doodles-official"), indent=2))
print(json.dumps(os_search("doodles", limit=3), indent=2))
EOF
Exports available
- API key:
os_create_instant_api_key
- Collections:
os_collections, os_collection, os_collection_stats, os_collection_holders, os_collection_floor_prices, os_collections_trending, os_collections_top
- Search:
os_search
- NFTs:
os_nft, os_nfts_by_contract
- Events:
os_events, os_events_by_collection, os_events_by_nft
- Listings/Offers:
os_listings_best, os_listings_all, os_offers_all, os_offers_for_nft, os_best_offer_for_nft
- Swap/verification:
os_swap_quote, os_swap_execute, os_transaction_receipt (swap_quote required by OpenSea API; include at least one of transaction_identifiers / relay_request_id / request_id)
Ready scripts
skills/opensea/scripts/smoke_test.pyskills/opensea/scripts/get_collection_report.pyskills/opensea/scripts/get_nft_snapshot.pyskills/opensea/scripts/get_market_surface.pyskills/opensea/scripts/poll_tx_receipt.py (expects swap_quote JSON inline or via @file.json)
End-to-end execution notes
os_swap_execute returns unsigned transaction payloads (to, data, value) and quote metadata; it does not broadcast.- Broadcast each transaction with wallet tooling (
wallet_transfer) using chain-appropriate chain ID.
wallet_transfer may return user_operation_hash without a normal tx hash. You can use that value as transaction_identifiers[].transaction_hash for OpenSea receipt polling.- For receipt verification call
os_transaction_receipt with:
- a
swap_quote object containing from_assets (and optionally to_assets), and
- at least one identifier:
transaction_identifiers (preferred), relay_request_id, or request_id.
request_id must be a valid UUID when supplied.- If
swap_quote/identifier pairing is inconsistent, the API may return validation errors like provider-mapping failures.
- Verified working pattern (Arbitrum USDC->WETH test):
swap_provider from quote: ZERO_EX- pass two
transaction_identifiers with chain arbitrum, provider ZERO_EX, hashes from wallet user_operation_hash
- receipt returns
status: PENDING with populated asset_receipts/total_spent while settlement completes.
Output style
Return:
- user’s requested answer first,
- key metrics in compact bullets or table,
- explicit confidence/limits when data is partial,
- next actionable step (e.g. monitor, place order, wait for receipt).
No hype language, no fabricated execution results.
