Skip to content

Add documentation for token discovery and swap API endpoints #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ckorhonen wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add documentation for token discovery and swap API endpoints #3

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a2dc3c8
Add documentation for token discovery and swap API endpoints
devin-ai-integration[bot] Feb 6, 2026
f6f0efe
Fix order frontmatter to avoid conflict with contributing.md
devin-ai-integration[bot] Feb 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
212 changes: 212 additions & 0 deletions opensea-js/developerDocs/token-endpoints.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,212 @@
---
title: Token Endpoints
category: 64cbb5277b5f3c0065d96616
slug: opensea-api-token-endpoints
parentDocSlug: opensea-sdk
order: 6
hidden: false
---

- [Token Discovery](#token-discovery)
- [Get Top Tokens](#get-top-tokens)
- [Get Trending Tokens](#get-trending-tokens)
- [Get Token Details](#get-token-details)
- [Token Swaps](#token-swaps)
- [Get Swap Quote](#get-swap-quote)

The OpenSea API provides endpoints for discovering tokens and executing swaps. All endpoints require API key authentication.

## Token Discovery

### Get Top Tokens

Retrieve tokens ranked by 24-hour trading volume.

**Endpoint:** `GET /api/v2/tokens/top`

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `chain` | string | No | Filter by blockchain (e.g., `ethereum`, `solana`) |
| `limit` | integer | No | Number of results to return |

**Example Request:**

```bash
curl -X GET "https://api.opensea.io/api/v2/tokens/top?chain=ethereum&limit=10" \
-H "X-API-KEY: YOUR_API_KEY"
```

**Example Response:**

```json
{
"tokens": [
{
"address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"chain": "ethereum",
"name": "USD Coin",
"symbol": "USDC",
"decimals": 6,
"image_url": "https://...",
"opensea_url": "https://opensea.io/assets/ethereum/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
}
]
}
```

### Get Trending Tokens

Retrieve tokens that are trending based on OpenSea's scoring algorithm.

**Endpoint:** `GET /api/v2/tokens/trending`

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `chain` | string | No | Filter by blockchain (e.g., `ethereum`, `solana`) |
| `limit` | integer | No | Number of results to return |

**Example Request:**

```bash
curl -X GET "https://api.opensea.io/api/v2/tokens/trending?chain=ethereum&limit=10" \
-H "X-API-KEY: YOUR_API_KEY"
```

**Example Response:**

```json
{
"tokens": [
{
"address": "0x...",
"chain": "ethereum",
"name": "Token Name",
"symbol": "TKN",
"decimals": 18,
"image_url": "https://...",
"opensea_url": "https://opensea.io/assets/ethereum/0x..."
}
]
}
```

### Get Token Details

Retrieve detailed information about a specific token by chain and contract address.

**Endpoint:** `GET /api/v2/chain/{chain}/token/{address}`

**Path Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `chain` | string | Yes | Blockchain name (e.g., `ethereum`, `solana`) |
| `address` | string | Yes | Token contract address |

**Example Request:**

```bash
curl -X GET "https://api.opensea.io/api/v2/chain/ethereum/token/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" \
-H "X-API-KEY: YOUR_API_KEY"
```

**Example Response:**

```json
{
"address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"chain": "ethereum",
"name": "USD Coin",
"symbol": "USDC",
"decimals": 6,
"image_url": "https://...",
"opensea_url": "https://opensea.io/assets/ethereum/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
}
```

## Token Swaps

### Get Swap Quote

Get a swap quote with transaction data for exchanging tokens. This endpoint returns both pricing information and the transaction payload needed to execute the swap.

**Endpoint:** `GET /api/v2/swap/quote`

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sell_token` | string | Yes | Contract address of the token to sell (use zero address for native tokens like ETH) |
| `buy_token` | string | Yes | Contract address of the token to buy |
| `sell_amount` | string | Yes | Amount of tokens to sell (in base units) |
| `taker_address` | string | Yes | Wallet address that will execute the swap |
| `chain` | string | Yes | Blockchain name (e.g., `ethereum`, `solana`) |
| `slippage` | number | No | Maximum acceptable slippage (0-0.5, default: 0.01). Values above 0.5 are rejected |

**Native Token Addresses:**

For native tokens (ETH on Ethereum, SOL on Solana), use the zero address:
- EVM chains: `0x0000000000000000000000000000000000000000`
- Solana: `11111111111111111111111111111111`

**Example Request:**

```bash
curl -X GET "https://api.opensea.io/api/v2/swap/quote?sell_token=0x0000000000000000000000000000000000000000&buy_token=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&sell_amount=1000000000000000000&taker_address=0x1234...&chain=ethereum&slippage=0.01" \
-H "X-API-KEY: YOUR_API_KEY"
```

**Example Response:**

```json
{
"quote": {
"sell_amount": "1000000000000000000",
"buy_amount": "1850000000",
"price_usd": 1850.00,
"price_impact": 0.001
},
"transactions": [
{
"chain_type": "evm",
"to": "0x...",
"data": "0x...",
"value": "1000000000000000000"
}
]
}
```

**Response Fields:**

| Field | Description |
|-------|-------------|
| `quote.sell_amount` | Amount of tokens being sold (in base units) |
| `quote.buy_amount` | Expected amount of tokens to receive (in base units) |
| `quote.price_usd` | Total value of the swap in USD |
| `quote.price_impact` | Estimated price impact of the trade |
| `transactions` | Array of transactions to execute (may include approval + swap) |
| `transactions[].chain_type` | Either `evm` or `svm` (Solana) |
| `transactions[].to` | Contract address to interact with (EVM only) |
| `transactions[].data` | Transaction calldata (EVM) or base64-encoded transaction (Solana) |
| `transactions[].value` | Native token value to send (EVM only) |

**Transaction Execution:**

The `transactions` array may contain multiple transactions that must be executed in order:
1. **Approval transaction** (if needed): Approves the swap contract to spend your tokens
2. **Swap transaction**: Executes the actual token swap

For EVM chains, use the transaction data with your web3 provider. For Solana, decode the base64 transaction and sign it with your wallet.

**Error Responses:**

| Status Code | Description |
|-------------|-------------|
| 400 | Invalid parameters (invalid quantity, slippage out of range, etc.) |
| 404 | Token not found |
| 422 | Swap not available (insufficient liquidity, token disabled, etc.) |