diff --git a/opensea-js/developerDocs/token-endpoints.md b/opensea-js/developerDocs/token-endpoints.md
new file mode 100644
index 0000000..14e02f4
--- /dev/null
+++ b/opensea-js/developerDocs/token-endpoints.md
@@ -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.) |