# OpenSea API — NFT marketplace scraper: collection floor price, volume, market-cap stats, supply and socials; collection search; per-NFT item detail with traits, rarity rank, best listing/offer and last sale; paginated collection items; top holders; recent sales activity; and trending / top collection rankings from OpenSea (opensea.io) — no API key required

> Full collection detail by slug: floor price, top offer, 24h + total volume, owner / listed / supply counts and 1-day floor change (live from OpenSea's GraphQL) merged with keyless metadata — description, image/banner, contracts (address + chain), category, safelist status, fees and social links (Twitter / Discord / Telegram / website).
> ReefAPI engine `opensea` · 7 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/opensea/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /opensea/v1/collection — 1 credit
Full collection detail by slug: floor price, top offer, 24h + total volume, owner / listed / supply counts and 1-day floor change (live from OpenSea's GraphQL) merged with keyless metadata — description, image/banner, contracts (address + chain), category, safelist status, fees and social links (Twitter / Discord / Telegram / website).

**Parameters:**
- `slug` (string, required) — OpenSea collection slug — the last path segment of an OpenSea collection URL (opensea.io/collection/<slug>), e.g. 'pudgypenguins', 'boredapeyachtclub', 'azuki'. Use the search action to resolve a name to its slug.

**Returns:** collection{slug, name, category, floor_price{amount,symbol,usd}, top_offer, total_supply, unique_item_count, listed_count, owner_count, total_volume, one_day_volume, one_day_floor_change, description, image_url, banner_image_url, contracts[]{address,chain}, safelist_status, twitter_username, discord_url, project_url, fees, created_date, opensea_url}

**Example request body:**
```json
{
  "slug": "pudgypenguins"
}
```

### POST /opensea/v1/search — 1 credit
Search OpenSea collections by free-text name. Returns matching collections with slug, name, image, category, floor price, owner count, supply and total volume — use the returned slug with the other actions.

**Parameters:**
- `query` (string, required) — Collection name or keyword to search for (e.g. 'pudgy', 'bored ape', 'azuki').
- `limit` (integer, optional, default 10) — Max collections to return (1-50, default 10).

**Returns:** collections[]{slug, name, category, image_url, floor_price, total_supply, owner_count, total_volume, opensea_url}

**Example request body:**
```json
{
  "query": "pudgy"
}
```

### POST /opensea/v1/items — 1 credit
Paginated items (NFTs) in a collection. Each item: name, token id, contract, image, rarity rank, best listing price + marketplace, best offer and last sale. Sort by price / rarity / last-sale-price / listing-date. Cursor pagination — pass the returned meta.next_cursor as `cursor` to page on.

**Parameters:**
- `slug` (string, required) — OpenSea collection slug — the last path segment of an OpenSea collection URL (opensea.io/collection/<slug>), e.g. 'pudgypenguins', 'boredapeyachtclub', 'azuki'. Use the search action to resolve a name to its slug.
- `limit` (integer, optional, default 30) — Items per page (1-100, default 30).
- `cursor` (string, optional) — Pagination cursor — pass meta.next_cursor from the previous page to fetch the next.
- `sort_by` (enum, optional, default "PRICE") — Sort items by this field. [one of: PRICE, RARITY, LAST_SALE_PRICE, CREATED_DATE, BEST_OFFER]
- `direction` (enum, optional, default "ASC") — Sort direction (ASC = cheapest/lowest first). [one of: ASC, DESC]

**Returns:** items[]{id, name, token_id, contract_address, image_url, rarity_rank, best_listing{amount,symbol,usd}, listing_marketplace, best_offer, last_sale} + meta{next_cursor, has_more}

**Example request body:**
```json
{
  "slug": "pudgypenguins",
  "limit": 5
}
```

### POST /opensea/v1/item — 1 credit
Single NFT / item detail by collection contract + token id: name, image, all traits (trait_type + value), rarity rank, best listing (price + marketplace), best offer and last sale. Get contract_address from the collection action's contracts[] (or an items[] row); token_id is the NFT number.

**Parameters:**
- `contract_address` (string, required) — NFT contract address (0x…). From the collection's contracts[].address or an items[] row.
- `token_id` (string, required) — The token id / NFT number within the contract.
- `chain` (enum, optional, default "ethereum") — Blockchain the item is on (default ethereum). [one of: ethereum, matic, base, solana, arbitrum, optimism, klaytn, avalanche, blast, zora, bsc, sei]

**Returns:** item{id, name, token_id, contract_address, image_url, animation_url, rarity_rank, collection_slug, traits[]{trait_type,value}, best_listing{amount,symbol,usd}, listing_marketplace, best_offer, last_sale, opensea_url}

### POST /opensea/v1/activity — 1 credit
Recent on-chain activity for a collection (default: sales). Each event: type, time, price (token amount + USD) and the item (name, token id, contract). Filter by event type — sales, listings, offers, transfers or mints.

**Parameters:**
- `slug` (string, required) — OpenSea collection slug — the last path segment of an OpenSea collection URL (opensea.io/collection/<slug>), e.g. 'pudgypenguins', 'boredapeyachtclub', 'azuki'. Use the search action to resolve a name to its slug.
- `limit` (integer, optional, default 20) — Max events (1-50, default 20).
- `event_type` (enum, optional, default "SALE") — Which activity to return (default SALE = recent sales). [one of: SALE, LISTING, OFFER, TRANSFER, MINT]

**Returns:** activity[]{id, type, event_time, price{amount,symbol,usd}, item_name, token_id, contract_address}

**Example request body:**
```json
{
  "slug": "pudgypenguins",
  "event_type": "SALE",
  "limit": 5
}
```

### POST /opensea/v1/holders — 1 credit
Top holders (owners) of a collection, ranked by quantity owned. Each holder: wallet address, display name (ENS / OpenSea username if any), quantity, % of supply and estimated total NFT portfolio value (USD). Cursor pagination.

**Parameters:**
- `slug` (string, required) — OpenSea collection slug — the last path segment of an OpenSea collection URL (opensea.io/collection/<slug>), e.g. 'pudgypenguins', 'boredapeyachtclub', 'azuki'. Use the search action to resolve a name to its slug.
- `limit` (integer, optional, default 20) — Holders per page (1-50, default 20).
- `cursor` (string, optional) — Pagination cursor (meta.next_cursor from the previous page).

**Returns:** holders[]{address, display_name, quantity, percent, estimated_nft_value_usd} + meta{next_cursor, has_more}

**Example request body:**
```json
{
  "slug": "pudgypenguins",
  "limit": 5
}
```

### POST /opensea/v1/trending — 1 credit
Trending or top collections ranked over a time window — the OpenSea rankings/leaderboard. Each: rank score, slug, name, floor price, volume, owners and 1-day floor change. Choose TRENDING (momentum) or TOP (by volume), and a window (1h / 1d / 7d / 30d).

**Parameters:**
- `ranking` (enum, optional, default "TRENDING") — TRENDING (momentum) or TOP (highest volume). [one of: TRENDING, TOP]
- `timeframe` (enum, optional, default "ONE_DAY") — Ranking window. [one of: ONE_HOUR, ONE_DAY, SEVEN_DAYS, THIRTY_DAYS]
- `limit` (integer, optional, default 20) — Max collections (1-100, default 20).

**Returns:** collections[]{score, slug, name, category, image_url, floor_price, total_volume, one_day_volume, owner_count, listed_count, total_supply, one_day_floor_change, opensea_url}

**Example request body:**
```json
{
  "ranking": "TRENDING",
  "timeframe": "ONE_DAY",
  "limit": 5
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=opensea
- Human docs page: https://reefapi.com/docs/opensea
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt