repositories
loading repo index
repositories
loading repo index
repository
loading code, commits, and activity
Mirrored from https://github.com/ProjectOpenSea/opensea-skill
stars
latest
clone command
git clone gitlawb://did:key:z6MkqRzA...RfoM/ProjectOpenSea-...git clone gitlawb://did:key:z6MkqRzA.../ProjectOpenSea-...fef93001Release v2.14.011h ago| #1 | # OpenSea REST API Reference |
| #2 | |
| #3 | ## Base URL and Authentication |
| #4 | |
| #5 | ``` |
| #6 | Base URL: https://api.opensea.io |
| #7 | OpenAPI spec: https://api.opensea.io/api/v2/openapi.json |
| #8 | Auth header: x-api-key: $OPENSEA_API_KEY |
| #9 | ``` |
| #10 | |
| #11 | ## Pagination |
| #12 | |
| #13 | List endpoints support cursor-based pagination: |
| #14 | - `limit`: Page size (default varies, max 100) |
| #15 | - `next`: Cursor token from previous response |
| #16 | |
| #17 | ## Supported Chains |
| #18 | |
| #19 | | Chain | Identifier | |
| #20 | |-------|------------| |
| #21 | | Ethereum | `ethereum` | |
| #22 | | Polygon | `matic` | |
| #23 | | Arbitrum | `arbitrum` | |
| #24 | | Optimism | `optimism` | |
| #25 | | Base | `base` | |
| #26 | | Avalanche | `avalanche` | |
| #27 | | Klaytn | `klaytn` | |
| #28 | | Zora | `zora` | |
| #29 | | Blast | `blast` | |
| #30 | | Sepolia (testnet) | `sepolia` | |
| #31 | |
| #32 | ## Endpoint Reference |
| #33 | |
| #34 | ### Collections |
| #35 | |
| #36 | | Endpoint | Method | Description | |
| #37 | |----------|--------|-------------| |
| #38 | | `/api/v2/collections/{slug}` | GET | Single collection details | |
| #39 | | `/api/v2/collections/{slug}/stats` | GET | Collection statistics (floor, volume) | |
| #40 | | `/api/v2/collections` | GET | List multiple collections | |
| #41 | | `/api/v2/collections/trending` | GET | Trending collections by sales activity | |
| #42 | | `/api/v2/collections/top` | GET | Top collections by volume/sales/floor | |
| #43 | | `/api/v2/collections/batch` | POST | Fetch multiple collections by slug in one request | |
| #44 | | `/api/v2/collections/{slug}/offer_aggregates` | GET | Top offers grouped by price level | |
| #45 | | `/api/v2/collections/{slug}/holders` | GET | Holders ranked by quantity owned | |
| #46 | | `/api/v2/collections/{slug}/floor_prices` | GET | Floor-price history | |
| #47 | |
| #48 | ### NFTs |
| #49 | |
| #50 | | Endpoint | Method | Description | |
| #51 | |----------|--------|-------------| |
| #52 | | `/api/v2/chain/{chain}/contract/{contract}/nfts/{token_id}` | GET | Single NFT details | |
| #53 | | `/api/v2/collection/{slug}/nfts` | GET | NFTs by collection | |
| #54 | | `/api/v2/chain/{chain}/account/{address}/nfts` | GET | NFTs by wallet | |
| #55 | | `/api/v2/chain/{chain}/contract/{contract}/nfts` | GET | NFTs by contract | |
| #56 | | `/api/v2/nft/{contract}/{token_id}/refresh` | POST | Refresh NFT metadata | |
| #57 | | `/api/v2/nfts/batch` | POST | Fetch multiple NFTs in one request | |
| #58 | | `/api/v2/chain/{chain}/contract/{contract}/nfts/{token_id}/owners` | GET | Owners of an NFT (paginated for ERC-1155s) | |
| #59 | | `/api/v2/chain/{chain}/contract/{contract}/nfts/{token_id}/analytics` | GET | Historical sale points for an NFT | |
| #60 | |
| #61 | ### Listings |
| #62 | |
| #63 | | Endpoint | Method | Description | |
| #64 | |----------|--------|-------------| |
| #65 | | `/api/v2/listings/collection/{slug}/all` | GET | All listings for collection (filter by `?maker=`) | |
| #66 | | `/api/v2/listings/collection/{slug}/nfts/{token_id}/best` | GET | Best listing for NFT | |
| #67 | | `/api/v2/orders/{chain}/seaport/listings` | POST | Create new listing | |
| #68 | | `/api/v2/listings/fulfillment_data` | POST | Get buy transaction data | |
| #69 | | `/api/v2/listings/sweep` | POST | Bulk-buy items from a collection | |
| #70 | | `/api/v2/listings/actions` | POST | Ordered approval + sign actions to create listings | |
| #71 | |
| #72 | ### Offers |
| #73 | |
| #74 | | Endpoint | Method | Description | |
| #75 | |----------|--------|-------------| |
| #76 | | `/api/v2/offers/collection/{slug}/all` | GET | All offers for collection (filter by `?maker=`) | |
| #77 | | `/api/v2/offers/collection/{slug}/nfts/{token_id}` | GET | All offers for a specific NFT | |
| #78 | | `/api/v2/offers/collection/{slug}/nfts/{token_id}/best` | GET | Best offer for NFT | |
| #79 | | `/api/v2/orders/{chain}/seaport/offers` | POST | Create new offer | |
| #80 | | `/api/v2/offers/fulfillment_data` | POST | Get sell transaction data | |
| #81 | |
| #82 | ### Orders |
| #83 | |
| #84 | | Endpoint | Method | Description | |
| #85 | |----------|--------|-------------| |
| #86 | | `/api/v2/orders/chain/{chain}/protocol/{protocol}/{hash}` | GET | Get order by hash | |
| #87 | | `/api/v2/orders/chain/{chain}/protocol/{protocol}/{hash}/cancel` | POST | Cancel order | |
| #88 | |
| #89 | ### Events |
| #90 | |
| #91 | | Endpoint | Method | Description | |
| #92 | |----------|--------|-------------| |
| #93 | | `/api/v2/events/collection/{slug}` | GET | Events by collection | |
| #94 | | `/api/v2/events/chain/{chain}/contract/{contract}/nfts/{token_id}` | GET | Events by NFT | |
| #95 | | `/api/v2/events/chain/{chain}/account/{address}` | GET | Events by account | |
| #96 | |
| #97 | ### Drops |
| #98 | |
| #99 | | Endpoint | Method | Description | |
| #100 | |----------|--------|-------------| |
| #101 | | `/api/v2/drops` | GET | List drops (featured, upcoming, recently_minted) | |
| #102 | | `/api/v2/drops/{slug}` | GET | Detailed drop info with stages and supply | |
| #103 | | `/api/v2/drops/{slug}/mint` | POST | Build mint transaction data | |
| #104 | | `/api/v2/drops/deploy` | POST | Build deploy-contract transaction for a new drop | |
| #105 | | `/api/v2/drops/deploy/{chain}/{tx_hash}/receipt` | GET | Receipt for a previously submitted deploy transaction | |
| #106 | |
| #107 | ### Accounts |
| #108 | |
| #109 | | Endpoint | Method | Description | |
| #110 | |----------|--------|-------------| |
| #111 | | `/api/v2/accounts/{address}` | GET | Account profile | |
| #112 | | `/api/v2/accounts/resolve/{identifier}` | GET | Resolve ENS name, username, or address | |
| #113 | | `/api/v2/account/{address}/portfolio` | GET | Portfolio stats (net worth, P&L) | |
| #114 | | `/api/v2/account/{address}/portfolio/history` | GET | Portfolio net-worth history | |
| #115 | | `/api/v2/account/{address}/offers` | GET | Active offers made by an account | |
| #116 | | `/api/v2/account/{address}/offers_received` | GET | Offers received by an account | |
| #117 | | `/api/v2/account/{address}/listings` | GET | Active listings for an account | |
| #118 | | `/api/v2/account/{address}/favorites` | GET | Items favorited by an account | |
| #119 | | `/api/v2/account/{address}/collections` | GET | Collections owned by an account | |
| #120 | |
| #121 | ### Tokens |
| #122 | |
| #123 | | Endpoint | Method | Description | |
| #124 | |----------|--------|-------------| |
| #125 | | `/api/v2/tokens/batch` | POST | Fetch multiple tokens in one request | |
| #126 | | `/api/v2/chain/{chain}/token/{address}/price_history` | GET | Token price history | |
| #127 | | `/api/v2/chain/{chain}/token/{address}/ohlcv` | GET | OHLCV candles for a token | |
| #128 | | `/api/v2/chain/{chain}/token/{address}/activity` | GET | Recent swap activity for a token | |
| #129 | | `/api/v2/chain/{chain}/token/{address}/holders` | GET | Paginated holders + aggregate distribution health | |
| #130 | | `/api/v2/chain/{chain}/token/{address}/liquidity-pools` | GET | Liquidity pools for a token | |
| #131 | |
| #132 | ### Tools |
| #133 | |
| #134 | | Endpoint | Method | Description | |
| #135 | |----------|--------|-------------| |
| #136 | | `/api/v2/tools` | GET | List registered tools (sort by newest/oldest, filter by type) | |
| #137 | | `/api/v2/tools/search` | GET | Search tools by keyword, tags, creator, access type | |
| #138 | | `/api/v2/tools/{registry_chain}/{registry_addr}/{tool_id}` | GET | Get a specific registered tool | |
| #139 | |
| #140 | ### Assets |
| #141 | |
| #142 | | Endpoint | Method | Description | |
| #143 | |----------|--------|-------------| |
| #144 | | `/api/v2/assets/transfer` | POST | Build transactions to transfer NFTs or tokens between wallets | |
| #145 | |
| #146 | ### Swap & Transactions |
| #147 | |
| #148 | | Endpoint | Method | Description | |
| #149 | |----------|--------|-------------| |
| #150 | | `/api/v2/swap/quote` | GET | Get a single-asset swap quote | |
| #151 | | `/api/v2/swap/execute` | POST | Get executable transactions for a multi-asset swap | |
| #152 | | `/api/v2/transactions/receipt` | POST | Fetch transaction status (any tx type — sweep, swap, fulfillment) | |
| #153 | |
| #154 | ## Event Types |
| #155 | |
| #156 | For the events endpoint, filter with `event_type`: |
| #157 | - `sale` - NFT sold |
| #158 | - `transfer` - NFT transferred |
| #159 | - `listing` - New listing created |
| #160 | - `offer` - New offer made |
| #161 | - `cancel` - Order cancelled |
| #162 | - `redemption` - NFT redeemed |
| #163 | |
| #164 | ## Rate Limits |
| #165 | |
| #166 | All v2 endpoints require an API key. OpenSea uses a **token bucket** algorithm: your API key has a bucket of request tokens that refills over a fixed time window. Each request consumes one token. When the bucket is empty, the API returns `429 Too Many Requests`. |
| #167 | |
| #168 | All API keys under the same account share a single rate limit bucket. Creating multiple API keys will not increase your overall rate limit. |
| #169 | |
| #170 | ### Default Rate Limits (Tier 1) |
| #171 | |
| #172 | | Operation | Limit | |
| #173 | |-----------|-------| |
| #174 | | Read (GET) | 120 requests/minute | |
| #175 | | Write (POST) | 60 requests/minute | |
| #176 | | Fulfillment | 60 requests/minute | |
| #177 | |
| #178 | Higher tiers are available for select users. You can apply for a rate limit increase via the [OpenSea Developer Portal](https://opensea.io/settings/developer). |
| #179 | |
| #180 | ### Rate Limit Response Headers |
| #181 | |
| #182 | A `429` response includes these headers: |
| #183 | |
| #184 | | Header | Description | |
| #185 | |--------|-------------| |
| #186 | | `X-RateLimit-Limit` | Maximum requests allowed in the current time window | |
| #187 | | `X-RateLimit-Window` | Duration of the time window (e.g., `60s`) | |
| #188 | | `X-RateLimit-Remaining` | Requests remaining in the current window | |
| #189 | | `Retry-After` | Seconds to wait before retrying | |
| #190 | |
| #191 | ## Error Codes |
| #192 | |
| #193 | | Code | Meaning | |
| #194 | |------|---------| |
| #195 | | 400 | Bad request - check parameters | |
| #196 | | 401 | Unauthorized - missing/invalid API key | |
| #197 | | 404 | Resource not found | |
| #198 | | 429 | Rate limited | |
| #199 | | 500 | Server error | |
| #200 | |
| #201 | ## Tips |
| #202 | |
| #203 | 1. Use collection slugs (not addresses) for collection endpoints |
| #204 | 2. Use chain identifiers for NFT/account endpoints |
| #205 | 3. All timestamps are Unix epoch seconds |
| #206 | 4. Prices are in wei (divide by 10^18 for ETH) |
| #207 | 5. Use `jq` to parse JSON responses: `./script.sh | jq '.nft.name'` |
| #208 |