OpenSea API & Scraper
The OpenSea API returns NFT marketplace data — floor prices, items and activity — as clean JSON.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
The primary collection endpoint returns a collection's slug, name, category, floor price (amount, symbol, USD), top offer, total supply, unique-item and listed counts, and you can search collections, list items, pull an item, its activity and holders, and see what is trending. It is built for NFT analytics, portfolio tools and web3 apps that need OpenSea data without a scraper. One ReefAPI key, one shared credit pool, the standard { ok, data, meta, error } envelope.
Identifiers, price units, and the fields that are ratios rather than percentages
Two things break integrations here. Token ids exceed what a JSON number can safely hold, so they are strings, and several fields that look like percentages are decimal fractions. Prices are whole token units, not wei. All values below are a live read of pudgypenguins in August 2026.
| Field | Type and unit | Measured |
|---|---|---|
| slug | The last path segment of an OpenSea collection URL. A wrong one is rejected, not guessed | pudgypenguins; an invented slug returned NOT_FOUND with retryable false |
| contracts[].address and chain | 0x address plus a chain enum value from ethereum, matic, base, solana, arbitrum, optimism, klaytn, avalanche, blast, zora, bsc, sei | 0xbd3531da5cf5857e7cfaa92426877b022e612cf8 on ethereum |
| token_id | String, always. Never parse it as an integer | "7526" |
| id | A 32-character hex OpenSea internal id, unrelated to token_id | 45f2e6872b19330896ce4f1a187c4a5c |
| floor_price, best_listing, best_offer, last_sale, price | {amount, symbol, usd}, where amount is whole token units and not wei | floor 4.44899 ETH, usd 11102.63 |
| symbol | NOT always ETH. Read it on every row before you do arithmetic | Re-measured 2026-08-28 across 60 trending rows on two rankings: floor_price.symbol came back as ETH, USDG, HYPE, USDC and RON, and null on one row. OpenSea lists across chains, so a stablecoin- or side-chain-denominated floor sits next to an ether one. Within Ethereum collections the older rule still holds: ETH for listings and sales, WETH for offers and some sales |
| one_day_floor_change | A signed decimal fraction, so multiply by 100 for a percentage | -0.0135, meaning the floor was down about 1.35 percent |
| holders[].percent | Also a fraction of supply | 0.034 for a wallet holding 302 of 8,888 |
| fees[].fee | A percentage, with a required flag separating the marketplace fee from the creator fee | 1.0 required plus 5.0 optional |
| rarity_rank | Integer rank inside the collection | 6160 out of 8,888 |
The activity action takes event_type in upper case (SALE, LISTING, OFFER, TRANSFER, MINT) but returns type in title case, so a filter of SALE yields rows whose type reads Sale. Compare case-insensitively.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/opensea/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "pudgy"
}
}{
"ok": true,
"meta": {
"api": "opensea",
"endpoint": "search",
"mode": "live",
"latency_ms": 624.9,
"record_count": 10,
"bytes": 4298,
"cache_hit": false,
"charged_credits": 1,
"version": "1.0.0"
},
"data": {
"collections": [
{
"slug": "pudgypenguins",
"name": "Pudgy Penguins",
"category": "PFPS",
"image_url": "https://i2c.seadn.io/collection/pudgypenguins/image/f489fb69fd11886b468c0f7ff1376c/cdf489fb69fd11886b468c0f7ff1376c.png",
"opensea_url": "https://opensea.io/collection/pudgypenguins",
"floor_price": {
"amount": 3.5,
"symbol": "ETH",
"usd": null
},
"total_supply": 8888,
"owner_count": 5047,
"total_volume": {
"amount": 521534.2378002326,
"symbol": null,
"usd": null
}
},
{
"slug": "pudgyrods",
"name": "Pudgy Rods",
"category": "MEMBERSHIPS",
"image_url": "https://i2c.seadn.io/collection/pudgyrods/image/6691c691d0426769120db411b57e86/866691c691d0426769120db411b57e86.png",
"opensea_url": "https://opensea.io/collection/pudgyrods",
"floor_price": {
"amount": 0.1218113,
"symbol": "ETH",
"usd": null
},
"total_supply": 7399,
"owner_count": 2924,
"total_volume": {
"amount": 23659.620528620653,
"symbol": null,
"usd": null
}
},
{
"slug": "lilpudgys",
"name": "Lil Pudgys",
"category": "PFPS",
"image_url": "https://i2c.seadn.io/collection/lilpudgys/image/9289b91d3d0cefccfe6b9c7f83f471/649289b91d3d0cefccfe6b9c7f83f471.png",
"opensea_url": "https://opensea.io/collection/lilpudgys",
"floor_price": {
"amount": 0.33977209,
"symbol": "ETH",
"usd": null
},
"total_supply": 21929,
"owner_count": 10446,
"total_volume": {
"amount": 143323.41250031558,
"symbol": null,
"usd": null
}
},
{
"slug": "anichess-x-pudgy-penguins",
"name": "Anichess x Pudgy Penguins",
"category": "GAMING",
"image_url": "https://i2c.seadn.io/collection/anichess-penguboard/image_type_logo/838260f9561cc39f41dc862476fc73/96838260f9561cc39f41dc862476fc73.jpeg",
"opensea_url": "https://opensea.io/collection/anichess-x-pudgy-penguins",
"floor_price": {
"amount": 0.0004989,
"symbol": "ETH",
"usd": null
},
"total_supply": 7824,
"owner_count": 1728,
"total_volume": {
"amount": 0.4493502541192007,
"symbol": null,
"usd": null
}
},
{
"slug": "mechapenguins",
"name": "Mecha Penguins - Pudgy Pilots",
"category": "GAMING",
"image_url": "https://i2c.seadn.io/ethereum/43f0d6063a814e5f8e0eff6818b498c8/3dde82d1fb7b73bea93799b0a55954/f93dde82d1fb7b73bea93799b0a55954.png",
"opensea_url": "https://opensea.io/collection/mechapenguins",
"floor_price": {
"amount": 0.00041,
"symbol": "ETH",
"usd": null
},
"total_supply": 7408,
"owner_count": 1907,
"total_volume": {
"amount": 296.63479874408563,
"symbol": null,
"usd": null
}
},
{
"slug": "pudgy-halloween",
"name": "Pudgy Halloween",
"category": "PFPS",
"image_url": "https://i2c.seadn.io/ethereum/7309c77e589641e7be542a68da81206d/f108ebccfe74845f79ec4cd4f31afd/f4f108ebccfe74845f79ec4cd4f31afd.png",
"opensea_url": "https://opensea.io/collection/pudgy-halloween",
"floor_price": {
"amount": 0.0124098,
"symbol": "ETH",
"usd": null
},
"total_supply": 3085,
"owner_count": 1337,
"total_volume": {
"amount": 41.879201323362416,
"symbol": null,
"usd": null
}
},
{
"slug": "pudgy-pepes-abstract",
"name": "Pudgy Pepes",
"category": null,
"image_url": "https://i2c.seadn.io/abstract/068d56741b6c4b489b8a9a78afff2251/60eb2307bfadf82331b73b3be614f0/6760eb2307bfadf82331b73b3be614f0.png",
"opensea_url": "https://opensea.io/collection/pudgy-pepes-abstract",
"floor_price": null,
"total_supply": 0,
"owner_count": 0,
"total_volume": {
"amount": 0,
"symbol": null,
"usd": null
}
},
{
"slug": "pudgy-pepes",
"name": "Pudgy Pepes",
"category": "PFPS",
"image_url": "https://i2c.seadn.io/ethereum/96bd2f4f63af4905822d9c48d496692d/e06e90cc6c5212c64f38e463a4664d/72e06e90cc6c5212c64f38e463a4664d.png",
"opensea_url": "https://opensea.io/collection/pudgy-pepes",
"floor_price": {
"amount": 0.00073,
"symbol": "ETH",
"usd": null
},
"total_supply": 8797,
"owner_count": 2851,
"total_volume": {
"amount": 287.71020954855425,
"symbol": null,
"usd": null
}
},
{
"slug": "forever-pudgy-penguin",
"name": "Forever Pudgy Penguin",
"category": null,
"image_url": "https://i2c.seadn.io/polygon/43a5d1b6b86745c28d27d623544b334e/9689ae8648e23bb423b64a7c49db5e/6e9689ae8648e23bb423b64a7c49db5e.png",
"opensea_url": "https://opensea.io/collection/forever-pudgy-penguin",
"floor_price": null,
"total_supply": 4335,
"owner_count": 4335,
"total_volume": {
"amount": 0,
"symbol": null,
"usd": null
}
},
{
"slug": "pudgypixelpenguins",
"name": "Pudgy Pixel Penguins",
"category": "PFPS",
"image_url": "https://i2c.seadn.io/ethereum/93de60e2dd2e3b9aa1c82b1f3726e1a5/6c6a5ef62dc4bc6f21a87811985151/376c6a5ef62dc4bc6f21a87811985151.gif",
"opensea_url": "https://opensea.io/collection/pudgypixelpenguins",
"floor_price": {
"amount": 0.0023,
"symbol": "ETH",
"usd": null
},
"total_supply": 4436,
"owner_count": 1612,
"total_volume": {
"amount": 310.12169613259294,
"symbol": null,
"usd": null
}
}
]
}
}What the OpenSea API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| collection | Full collection detail by slug: floor price, top offer, 24h + total volume, owner / listed / supply counts and 1-day floor change merged with keyless metadata — description, image/banner, contracts (address + chain), category, safelist status, fees and social links (Twitter / Discord / Telegram / website). | Pricing teams call collection to get full collection detail by slug. | slug |
| search | 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. | Marketplace operators call search to search OpenSea collections by free-text name. | query, limit |
| items | 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. | Catalog enrichment teams call items to get paginated items (NFTs) in a collection. | slug, limit, cursor, sort_by, direction |
| item | 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. | Retail analysts call item to get single NFT / item detail by collection contract + token id. | contract_address, token_id, chain |
| activity | 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. | Pricing teams call activity to get recent on-chain activity for a collection (default. | slug, limit, event_type |
| holders | 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. | Marketplace operators call holders to get top holders (owners) of a collection, ranked by quantity owned. | slug, limit, cursor |
| trending | 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). | Catalog enrichment teams call trending to get trending or top collections ranked over a time window. | ranking, timeframe, limit |
Call search from your stack
curl -X POST https://api.reefapi.com/opensea/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"pudgy"}'import requests
r = requests.post(
"https://api.reefapi.com/opensea/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "pudgy"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/opensea/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "pudgy"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.opensea.search with {"query":"pudgy"}.Who uses this API and why
- NFT-analytics tools call collection to track a project's floor price, supply and listed count.
- Portfolio apps use holders and items to value a wallet's holdings across collections.
- Web3 products use activity and trending to power market feeds and discovery.
Questions developers ask before integrating
Is token_id a number or a string?
A string, in every action that returns it. Measured items rows came back as "5898", "8247" and "2028", and the item action needs token_id passed as a string too. This is not cosmetic: token ids on many contracts run far past the 2^53 limit JavaScript can represent exactly, so parsing them as numbers silently corrupts the tail. The separate id field is a 32-character hex OpenSea identifier and is not interchangeable with it.
Are prices in wei?
No. amount is denominated in whole token units, so a floor of 4.44899 means 4.44899 ETH, not a wei integer. Each price object also carries symbol and usd, and the symbol is worth reading rather than assuming: a measured collection returned floor_price in ETH and top_offer in WETH, and one of three recent sales settled in WETH while the other two settled in ETH.
Why is best_listing null on an item that clearly exists?
Because that token is not currently listed for sale. A measured item, token 7526 of pudgypenguins, returned best_listing null while best_offer still carried 4.37 WETH — the standing collection-wide offer applies to every token whether or not the owner is selling. last_sale was also populated at 4.619955 ETH. So null on best_listing means unlisted, not missing data.
Why does listing_marketplace say blur instead of opensea?
Because the best listing for that token is not always on OpenSea. Measured items rows for pudgypenguins all carried listing_marketplace blur, with best_listing prices matching the collection floor. Treat floor_price as the cheapest listing OpenSea knows about across marketplaces, and read listing_marketplace before you tell a user where to buy.
Why is usd null on some rows but filled on others?
The lighter actions skip the conversion. Measured: last_sale.usd came back null on every items row while amount and symbol were present; the search action returned floor_price.usd null; and trending rows returned floor_price.usd null, top_offer null and unique_item_count null. The collection action is the one that fills all of them, so use search or trending to find a slug and then call collection for the numbers you intend to display.
What happens if I pass the wrong chain for a contract?
You get NOT_FOUND rather than a silent fallback. The same ethereum contract and token, requested with chain matic, returned NOT_FOUND with the message naming matic explicitly, and a nonexistent token id on the correct chain returned NOT_FOUND naming ethereum. chain defaults to ethereum and is on_invalid=ignore, so an unrecognised chain string quietly becomes ethereum instead of erroring.
How do I page through items, holders or activity?
With cursors, not offsets. meta returns next_cursor and has_more, and you pass next_cursor back as cursor. A measured items page of 5 returned an opaque base64-style cursor and has_more true. Ceilings differ per action: items allow up to 100 per page, holders and activity up to 50, and trending up to 100 collections.
What is estimated_nft_value_usd on a holder?
An estimate of that wallet's whole NFT portfolio, not its stake in the collection you asked about. The top pudgypenguins holder measured 302 tokens, percent 0.034, and estimated_nft_value_usd of about 8.6 million, which is more than 302 tokens at the 11,100 dollar floor. display_name is null when the wallet has neither an ENS name nor an OpenSea username, so fall back to address.
What is the OpenSea API?
OpenSea API is a ReefAPI endpoint group for opensea It returns live JSON through POST requests under /opensea/v1.
Is the OpenSea API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. OpenSea calls use the same shared credit balance as every other ReefAPI engine.
Do I need an OpenSea login or account?
No login to OpenSea is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the OpenSea data?
The page example is captured from a live collection call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the OpenSea API use?
OpenSea actions currently cost 1 credit per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.
Can I call OpenSea from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call opensea actions with the same key, credit pool and JSON envelope used by normal REST requests.