# @4885/opensea

> 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).

- Skill: `starchild-ai-agent/4885-opensea` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add starchild-ai-agent/4885-opensea`
- Raw SKILL.md: https://api.skillmd.com/api/skills/starchild-ai-agent/4885-opensea/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: starchild-ai-agent (https://skillmd.com/u/starchild-ai-agent)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/starchild-ai-agent/4885-opensea

---


## 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:
- https://docs.opensea.io
- https://docs.opensea.io/llms.txt (index of docs + endpoint map)

## API key strategy
OpenSea supports instant free-tier key creation (documented under `Create an instant API key`).

Use this decision rule:
1. If read-only request is small/occasional: create/use instant key.
2. 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:

1. **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

2. **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

3. **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
1. Resolve slug/collection.
2. Pull stats + floor history + traits.
3. Pull recent events.
4. Summarize liquidity, turnover, and near-term risk (washy volume, thin listings, trait concentration).

### B) “Should I sweep this collection?”
1. Fetch best listings and recent sales events.
2. Compare spread vs recent clears.
3. Evaluate depth (how many items near floor).
4. If user wants action: generate sweep transaction plan and clearly label it as pending execution until receipt confirmed.

### C) “Buy/list this NFT”
1. Pull best listing/offer + order details.
2. Generate fulfillment/listing actions.
3. Have wallet sign/broadcast via wallet tooling.
4. 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`.

```bash
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.py`
- `skills/opensea/scripts/get_collection_report.py`
- `skills/opensea/scripts/get_nft_snapshot.py`
- `skills/opensea/scripts/get_market_surface.py`
- `skills/opensea/scripts/poll_tx_receipt.py` (expects swap_quote JSON inline or via `@file.json`)

### End-to-end execution notes
1. `os_swap_execute` returns unsigned transaction payloads (`to`, `data`, `value`) and quote metadata; it does **not** broadcast.
2. Broadcast each transaction with wallet tooling (`wallet_transfer`) using chain-appropriate chain ID.
3. `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.
4. 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`.
5. `request_id` must be a valid UUID when supplied.
6. If `swap_quote`/identifier pairing is inconsistent, the API may return validation errors like provider-mapping failures.
7. 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.