OpenSea Developer Platform

https://docs.opensea.io
Admin
OpenSea's developer platform provides tools and guides for NFT builders and creators to innovate in...
Tokens:230,870
Snippets:2,030
Trust Score:10
Update:1 day ago
Show doc for...
Tokens:
Raw
### Install the OpenSea Agent Skill and get an instant API key

Source: https://docs.opensea.io/reference/agent-skill

Install the skill with npx and obtain an instant API key using curl and jq. The key has free-tier rate limits (600/h read, 30/h write) and expires after 7 days. Restart your AI tool after installation.

```bash
# Install the skill
npx skills add ProjectOpenSea/opensea-skill

# Get an instant API key (no signup needed)
# Using jq (recommended):
export OPENSEA_API_KEY=$(curl -s -X POST https://api.opensea.io/api/v2/auth/keys | jq -r '.api_key')
# Or without jq, copy the api_key value from the response:
# curl -s -X POST https://api.opensea.io/api/v2/auth/keys
```

--------------------------------

### Call a tool with @opensea/tool-sdk (TypeScript)

Source: https://docs.opensea.io/docs/set-up-an-onchain-agent

Install @opensea/tool-sdk and call tools directly. The example creates a wallet from environment variables and uses paidFetch to send a POST request with a signer and a maximum payment amount (maxAmount: "100000" caps at 0.10 USDC).

```TypeScript
import { paidFetch } from "@opensea/tool-sdk";
import { createWalletFromEnv } from "@opensea/wallet-adapters";

const wallet = createWalletFromEnv();
const res = await paidFetch("https://example-tool.com/api", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ query: "pudgy penguins floor price" }),
  signer: wallet,
  maxAmount: "100000", // cap at 0.10 USDC
});
const data = await res.json();
```

--------------------------------

### Install @opensea/cli globally

Source: https://docs.opensea.io/reference/opensea-cli

Installs the CLI globally via npm.

```bash
npm install -g @opensea/cli
```

--------------------------------

### Example deployment output

Source: https://docs.opensea.io/docs/part-2-set-up-shipyard

Example output from the deployment script, showing the contract address and gas costs.

```text
## Setting up 1 EVM.

==========================

Chain 8453

Estimated gas price: 88.766056168 gwei

Estimated total gas used for script: 7367397

Estimated amount required: 0.653974775913954696 ETH

.....

##
Waiting for receipts.
⠉ [00:00:13] [####################################################################################################] 1/1 receipts (0.0s)
##### base
✅  [Success]Hash: 0x453027c738fe082c224e47fe8a0cb021753cd9deaf63b83acc345f9cf4b52980
Contract Address: 0x345f5559A6FCF7A3f577910DB5f647b2f34FbB91
Block: 5061169
Paid: 0.322121247965804442 ETH (5668977 gas * 56.821759546 gwei)

==========================

ONCHAIN EXECUTION COMPLETE & SUCCESSFUL.
Total Paid: 0.322121247965804442 ETH (5668977 gas * avg 56.821759546 gwei)

...
```

--------------------------------

### Install @opensea/sdk and viem

Source: https://docs.opensea.io/docs/buy-and-sell-nfts

Install the OpenSea SDK and viem via npm. Requires Node.js >= 20.0.0 and an OpenSea API key.

```bash
npm install @opensea/sdk viem
```

--------------------------------

### Install @opensea/sdk

Source: https://docs.opensea.io/docs/stream-real-time-events

Install the OpenSea SDK package. No other dependencies are needed on Node 22 or newer.

```bash
npm install @opensea/sdk
```

--------------------------------

### Install @opensea/sdk

Source: https://docs.opensea.io/reference/stream-api

Install the OpenSea SDK package to use the Stream API client.

```APIDOC
## Install @opensea/sdk

### Description
Install the OpenSea SDK package to use the Stream API client.

### Command
```bash
npm install @opensea/sdk
```

```

--------------------------------

### Install Foundryup

Source: https://docs.opensea.io/docs/part-2-set-up-shipyard

Downloads and installs the Foundryup command, which is required to install forge, cast, anvil, and chisel.

```bash
curl -L https://foundry.paradigm.xyz | bash
```

--------------------------------

### Install OpenSea Agent Skill

Source: https://docs.opensea.io/docs/build-with-ai-agents

Installs the OpenSea Agent Skill from the ProjectOpenSea/opensea-skill repository using npx. Run this in a Bash terminal.

```bash
npx skills add ProjectOpenSea/opensea-skill
```

--------------------------------

### Create project directory

Source: https://docs.opensea.io/docs/part-2-set-up-shipyard

Creates a new directory named 'nft-tutorial' and changes into it.

```bash
mkdir nft-tutorial && cd nft-tutorial
```

--------------------------------

### GET /api/v2/account/{address}/offers

Source: https://docs.opensea.io/reference/get_profile_offers

Get a paginated list of active offers made by a wallet address. Supports pagination via cursor, filtering by collection slugs and chains, and sorting by start time or end time.

```APIDOC
## GET /api/v2/account/{address}/offers

### Description
Get a paginated list of active offers made by a wallet address.

### Method
GET

### Endpoint
https://api.opensea.io/api/v2/account/{address}/offers

### Parameters
#### Path Parameters
- **address** (string) - Required - The wallet address

#### Query Parameters
- **after** (string) - Optional - Cursor for pagination
- **limit** (int32) - Optional - Number of results to return. Defaults to 50.
- **collection_slugs** (array of strings) - Optional - Filter by collection slugs
- **chains** (array of objects) - Optional - Filter by chains
- **sort_by** (string) - Optional - Sort by field. Allowed values: `START_TIME`, `END_TIME`. Defaults to `START_TIME`.
- **sort_direction** (string) - Optional - Sort direction. Allowed values: `asc`, `desc`. Defaults to `desc`.

### Response
#### Success Response (200)
Active offers for account

#### Error Responses
- **400** - For error reasons, review the response data.
- **401** - Unauthorized
- **403** - Forbidden
- **404** - Not Found
- **409** - Conflict
- **500** - Internal server error. Please open a support ticket so OpenSea can investigate.
```

--------------------------------

### Full example: discover drop, check supply, and mint

Source: https://docs.opensea.io/docs/mint-from-a-drop

Complete example that sets up viem clients and OpenSeaSDK, checks drop supply, builds a mint transaction, and executes it. Requires a valid RPC URL, wallet address, API key, and collection slug.

```TypeScript
import { createPublicClient, createWalletClient, http } from "viem";
import { base } from "viem/chains";
import { OpenSeaSDK, Chain } from "@opensea/sdk/viem";

const publicClient = createPublicClient({ chain: base, transport: http("https://your-rpc-url") });
const walletClient = createWalletClient({ chain: base, transport: http("https://your-rpc-url"), account: "0x..." });

const sdk = new OpenSeaSDK(
  { publicClient, walletClient },
  { chain: Chain.Base, apiKey: "YOUR_API_KEY" },
);

const COLLECTION_SLUG = "my-collection-slug";
const WALLET = "0xYOUR_WALLET_ADDRESS";
const QUANTITY = 1;

// Check drop details
const drop = await sdk.api.getDrop(COLLECTION_SLUG);
const remaining = Number(drop.maxSupply) - Number(drop.totalSupply);
console.log(`${drop.collectionName}: ${remaining} remaining`);

if (remaining < QUANTITY) {
  console.log("Not enough supply remaining");
  process.exit(1);
}

// Build and execute mint transaction
const mintTx = await sdk.api.buildDropMintTransaction(COLLECTION_SLUG, {
  minter: WALLET,
  quantity: QUANTITY,
});

const hash = await walletClient.sendTransaction({
  to: mintTx.to,
  data: mintTx.data,
  value: BigInt(mintTx.value),
});

const receipt = await publicClient.waitForTransactionReceipt({ hash });
console.log("Minted! Tx:", receipt.transactionHash);
```

--------------------------------

### Initialize OpenSea SDK with viem

Source: https://docs.opensea.io/docs/mint-from-a-drop

Set up the OpenSea SDK with viem by creating public and wallet clients, then initializing the SDK with your API key. This example uses the Base chain.

```typescript
import { createPublicClient, createWalletClient, http } from "viem";
import { base } from "viem/chains";
import { OpenSeaSDK, Chain } from "@opensea/sdk/viem";

const publicClient = createPublicClient({ chain: base, transport: http("https://your-rpc-url") });
const walletClient = createWalletClient({ chain: base, transport: http("https://your-rpc-url"), account: "0x..." });

const sdk = new OpenSeaSDK(
  { publicClient, walletClient },
  { chain: Chain.Base, apiKey: "YOUR_API_KEY" },
);
```

--------------------------------

### Fetch llms.txt

Source: https://docs.opensea.io/reference/llms-agent-discovery

Use this endpoint to get a plain-text summary of the OpenSea API. It is a starting point for AI agents or LLMs to understand what the API offers.

```http
GET https://opensea.io/llms.txt
```

--------------------------------

### Example .env file with API keys

Source: https://docs.opensea.io/docs/set-up-an-onchain-agent

Example .env file showing where to add LLM and wallet provider API keys. Choose one provider for each category and replace the placeholder values with your actual keys.

```bash
# LLM provider (pick one)
OPENROUTER_API_KEY=sk-or-...

# Wallet provider (pick one)
BANKR_API_KEY=...
```

--------------------------------

### Get global events (SDK)

Source: https://docs.opensea.io/docs/query-analytics-and-events

Retrieves events across all collections using the OpenSea SDK. The example fetches sale events from the last hour with a limit of 50.

```TypeScript
const globalEvents = await sdk.api.getEvents({
  eventType: "sale",
  after: Math.floor(Date.now() / 1000) - 3600, // last hour
  limit: 50,
});
```

--------------------------------

### Get events by collection (SDK)

Source: https://docs.opensea.io/docs/query-analytics-and-events

Retrieves events for a collection using the OpenSea SDK. The example fetches sale events for 'boredapeyachtclub' with a limit of 10 and logs each event.

```TypeScript
const events = await sdk.api.getEventsByCollection("boredapeyachtclub", {
  eventType: "sale",
  limit: 10,
});

for (const event of events.assetEvents) {
  console.log(event);
}
```

--------------------------------

### Create project directory and navigate into it

Source: https://docs.opensea.io/docs/part-1-simple-website-setup

Run this command in your terminal to create a directory named 'nft-displayer' and change into it. This is the first step in setting up the project.

```bash
mkdir nft-displayer  && cd nft-displayer
```

--------------------------------

### Initialize OpenSeaSDK with viem

Source: https://docs.opensea.io/docs/buy-and-sell-nfts

Create public and wallet clients with viem, then instantiate OpenSeaSDK with the mainnet chain and your API key. Use this setup when using viem as the wallet/provider library.

```typescript
import { createPublicClient, createWalletClient, http } from "viem";
import { mainnet } from "viem/chains";
import { OpenSeaSDK, Chain } from "@opensea/sdk/viem";

const publicClient = createPublicClient({ chain: mainnet, transport: http("https://your-rpc-url") });
const walletClient = createWalletClient({ chain: mainnet, transport: http("https://your-rpc-url"), account: "0x..." });

const sdk = new OpenSeaSDK(
  { publicClient, walletClient },
  { chain: Chain.Mainnet, apiKey: "YOUR_API_KEY" },
);
```

--------------------------------

### Get events by account (SDK)

Source: https://docs.opensea.io/docs/query-analytics-and-events

Retrieves events for a specific account using the OpenSea SDK. The example fetches sale events for the given wallet address with a limit of 20.

```TypeScript
const accountEvents = await sdk.api.getEventsByAccount("0xWALLET_ADDRESS", {
  eventType: "sale",
  limit: 20,
});
```

--------------------------------

### GET https://opensea.io/llms.txt

Source: https://docs.opensea.io/reference/llms-agent-discovery

Retrieves a plain-text summary of the OpenSea API following the llms.txt standard. Use this as a starting point for AI agents or LLMs to understand what the API offers.

```APIDOC
## GET https://opensea.io/llms.txt

### Description
Retrieves a plain-text summary of the OpenSea API following the llms.txt standard. Use this as a starting point for AI agents or LLMs to understand what the API offers.

### Method
GET

### Endpoint
https://opensea.io/llms.txt

### Response
#### Success Response (200)
- **body** (text/plain) - Plain-text summary of the OpenSea API.

#### Response Example
```
[Plain text summary of the OpenSea API]
```
```

--------------------------------

### Get global events (curl)

Source: https://docs.opensea.io/docs/query-analytics-and-events

Retrieves events across all collections using the OpenSea REST API. The example fetches sale events with a limit of 50, requiring an API key.

```Bash
curl -X GET "https://api.opensea.io/api/v2/events?event_type=sale&limit=50" \
  -H "X-API-KEY: YOUR_API_KEY"
```

--------------------------------

### Build the project

Source: https://docs.opensea.io/docs/part-2-set-up-shipyard

Installs dependencies and compiles the contracts.

```bash
forge build
```

--------------------------------

### Get events by NFT (SDK)

Source: https://docs.opensea.io/docs/query-analytics-and-events

Retrieves events for a specific NFT using the OpenSea SDK. The example fetches sale events for a token on Ethereum with the given contract and token ID.

```TypeScript
const nftEvents = await sdk.api.getEventsByNFT(
  "ethereum",
  "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
  "1234",
  { eventType: "sale" },
);
```

--------------------------------

### Get events by collection (curl)

Source: https://docs.opensea.io/docs/query-analytics-and-events

Retrieves events for a collection using the OpenSea REST API. The example fetches sale events for 'boredapeyachtclub' with a limit of 10, requiring an API key.

```Bash
curl -X GET "https://api.opensea.io/api/v2/events/collection/boredapeyachtclub?event_type=sale&limit=10" \
  -H "X-API-KEY: YOUR_API_KEY"
```

--------------------------------

### Get events by account (curl)

Source: https://docs.opensea.io/docs/query-analytics-and-events

Retrieves events for a specific account using the OpenSea REST API. The example fetches sale events for the given wallet address with a limit of 20, requiring an API key.

```Bash
curl -X GET "https://api.opensea.io/api/v2/events/accounts/0xWALLET_ADDRESS?event_type=sale&limit=20" \
  -H "X-API-KEY: YOUR_API_KEY"
```

--------------------------------

### Scaffold, deploy, and register a tool with @opensea/tool-sdk

Source: https://docs.opensea.io/docs/agent-tool-registry

Commands to scaffold a new tool with the Vercel runtime, install dependencies, deploy, and register it onchain. Includes options for open access and NFT-gated access. Requires a wallet provider (Privy, Turnkey, Fireblocks, Bankr, or local private key) for registration.

```bash
# 1. Scaffold a new tool (generates manifest, handler, adapter, and .well-known route)
npx @opensea/tool-sdk init my-tool --runtime vercel
cd my-tool && npm install

# 2. Edit src/manifest.ts and src/handler.ts with your logic

# 3. Deploy
npx @opensea/tool-sdk deploy

# 4. Register onchain (configure a wallet provider, see the SDK README)
#    Supports: Privy, Turnkey, Fireblocks, Bankr, or a local private key

# 4a. Open access (no gate)
npx @opensea/tool-sdk register \
  --metadata https://my-tool.vercel.app/.well-known/ai-tool/my-tool.json \
  --network base

# 4b. NFT-gated access
npx @opensea/tool-sdk register \
  --metadata https://my-tool.vercel.app/.well-known/ai-tool/my-tool.json \
  --network base \
  --nft-gate 0xCOLLECTION_ADDRESS
```

--------------------------------

### Get events by NFT (curl)

Source: https://docs.opensea.io/docs/query-analytics-and-events

Retrieves events for a specific NFT using the OpenSea REST API. The example fetches sale events for a token on Ethereum with the given contract and token ID, requiring an API key.

```Bash
curl -X GET "https://api.opensea.io/api/v2/events/chain/ethereum/contract/0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D/nfts/1234?event_type=sale" \
  -H "X-API-KEY: YOUR_API_KEY"
```

--------------------------------

### GET /api/v2/drops/{slug}/metadata/ipfs/{workflow_execution_id}

Source: https://docs.opensea.io/reference/get_drop_metadata_ipfs_progress

Retrieves the progress of an IPFS metadata upload for a drop. Use this endpoint to poll the status of an upload started by POST /api/v2/drops/{slug}/metadata/ipfs. Poll every 15 seconds or slower while the status is running.

```APIDOC
## GET /api/v2/drops/{slug}/metadata/ipfs/{workflow_execution_id}

### Description
Retrieves the progress of an IPFS metadata upload for a drop. Use this endpoint to poll the status of an upload started by POST /api/v2/drops/{slug}/metadata/ipfs. Poll every 15 seconds or slower while the status is running.

### Method
GET

### Endpoint
/api/v2/drops/{slug}/metadata/ipfs/{workflow_execution_id}

### Parameters
#### Path Parameters
- **slug** (string) - Required - Collection slug
- **workflow_execution_id** (string) - Required - The workflow_execution_id returned when the upload was started

### Response
#### Success Response (200)
Upload progress

#### Error Responses
- **400** - For error reasons, review the response data.
- **401** - Invalid or missing API key
- **403** - Wallet token lacks permission for this request
- **404** - Resource not found
- **409** - Conflict
- **500** - Internal server error. Please open a support ticket so OpenSea can investigate.
```

--------------------------------

### Example OpenSea CLI commands

Source: https://docs.opensea.io/reference/opensea-cli

Shows common commands for collections, NFTs, listings, search, tokens, and table output.

```bash
# Get collection details
opensea collections get mfers

# Get floor price and volume stats
opensea collections stats mfers

# List NFTs in a collection
opensea nfts list-by-collection mfers --limit 5

# Get best listings
opensea listings best mfers --limit 5

# Search across OpenSea
opensea search "cool cats" --types collection

# Get trending tokens
opensea tokens trending --limit 5

# Human-readable table output
opensea --format table collections stats mfers
```

--------------------------------

### Run Foundryup

Source: https://docs.opensea.io/docs/part-2-set-up-shipyard

Installs forge, cast, anvil, and chisel by running the foundryup command.

```bash
foundryup
```

--------------------------------

### Create index.html file

Source: https://docs.opensea.io/docs/part-1-simple-website-setup

Run this command to create an empty index.html file in the current directory. This file will later contain the website's HTML code.

```bash
touch index.html
```

--------------------------------

### GET /api/v2/collections/trending

Source: https://docs.opensea.io/changelog/new-api-endpoints

Get trending collections by sales activity over a timeframe.

```APIDOC
## GET /api/v2/collections/trending

### Description
Get trending collections by sales activity over a timeframe.

### Method
GET

### Endpoint
/api/v2/collections/trending
```

--------------------------------

### GET /api/v2/collections/top

Source: https://docs.opensea.io/changelog/new-api-endpoints

Get top collections ranked by various stats.

```APIDOC
## GET /api/v2/collections/top

### Description
Get top collections ranked by various stats.

### Method
GET

### Endpoint
/api/v2/collections/top
```

--------------------------------

### GET /api/v2/drops

Source: https://docs.opensea.io/changelog/new-api-endpoints

Get drops by type: featured, upcoming, or recently minted.

```APIDOC
## GET /api/v2/drops

### Description
Get drops by type: featured, upcoming, or recently minted.

### Method
GET

### Endpoint
/api/v2/drops
```

--------------------------------

### Initialize OpenSeaSDK with ethers.js

Source: https://docs.opensea.io/docs/buy-and-sell-nfts

Create an ethers.js JsonRpcProvider and instantiate OpenSeaSDK with the mainnet chain and your API key. Use this setup when using ethers.js v6+ as the wallet/provider library.

```typescript
import { ethers } from "ethers";
import { OpenSeaSDK, Chain } from "@opensea/sdk";

const provider = new ethers.JsonRpcProvider("https://your-rpc-url");

const sdk = new OpenSeaSDK(provider, {
  chain: Chain.Mainnet,
  apiKey: "YOUR_API_KEY",
});
```

--------------------------------

### Tool manifest with x402 pricing

Source: https://docs.opensea.io/docs/x402

Example manifest showing the pricing field with an x402 protocol entry. Use amount "0" for free tools that still require the x402 identity proof.

```json
{
  "name": "premium-analytics",
  "endpoint": "https://tools.example.com/premium-analytics",
  "pricing": [
    {
      "protocol": "x402",
      "amount": "1000000",
      "asset": "eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "recipient": "eip155:8453:0xabcdef0123456789abcdef0123456789abcdef01"
    }
  ]
}
```

--------------------------------

### GET /api/v2/collections/{slug}/holders

Source: https://docs.opensea.io/changelog/new-api-endpoints

Get a paginated list of holders for a collection.

```APIDOC
## GET /api/v2/collections/{slug}/holders

### Description
Get a paginated list of holders for a collection.

### Method
GET

### Endpoint
/api/v2/collections/{slug}/holders

### Parameters
#### Path Parameters
- **slug** (string) - Required - The collection slug.
```
Tokens:
Raw