# CoinMarketCap x402

> Pay-per-request crypto market data powered by the x402 protocol. Access CoinMarketCap endpoints instantly with on-chain USDC payment — no API key or subscription required.

Pricing, features, and availability may change without prior notice. For production workloads, we recommend using the standard [CoinMarketCap Pro API](https://coinmarketcap.com/api/documentation/v1/) with an API key subscription.

## What is x402?

x402 is an open payment protocol developed by Coinbase that enables instant, automatic stablecoin payments directly over HTTP. Instead of managing API keys and subscriptions, you pay per request using USDC on Base. Learn more at the [x402 documentation](https://docs.cdp.coinbase.com/x402/welcome).

## How it works

Make a request to any x402-enabled endpoint. The server responds with HTTP 402 and a `Payment-Required` header containing the payment details (amount, network, asset, recipient).

Your wallet signs a USDC `transferWithAuthorization` (EIP-3009) message for the requested amount. This is an off-chain signature — no on-chain transaction occurs yet.

Resend the original request with the signed `PAYMENT-SIGNATURE` header attached. The facilitator verifies the signature, the server processes your request, and you receive the data. The on-chain USDC transfer is only executed upon successful data delivery.

:::note
x402 endpoints do not require `X-CMC_PRO_API_KEY` or any other authentication header. Payment is the authentication.
:::

## MCP endpoint

The `/x402/mcp` endpoint exposes a [Model Context Protocol](https://modelcontextprotocol.io/) server that supports x402 payments at the HTTP transport layer. This enables AI agents and LLM clients (e.g., Claude, Cursor) to discover and call CMC data tools with automatic per-request payment.

**Connection URL:**

```text
https://mcp.coinmarketcap.com/x402/mcp
```

**Transport:** Streamable HTTP (POST to `/x402/mcp`)

To connect, use any MCP-compatible client with an x402-aware HTTP transport that intercepts 402 responses, signs the payment, and retries. The MCP server exposes the same data tools as the REST endpoints below, and supports automatic tool discovery via the standard MCP `tools/list` method.

For standard MCP documentation, see [CMC MCP](/ai-agent-hub/mcp).

## Base URL

All x402 requests use the following base URL:

```text
https://pro-api.coinmarketcap.com
```

## Supported REST endpoints

| Endpoint | Method | Path | Description |
| --- | --- | --- | --- |
| [DEX Search](https://coinmarketcap.com/api/documentation/v1/#operation/search) | GET | `/x402/v1/dex/search` | Search for DEX tokens by keyword (name, symbol, or contract address). |
| [Cryptocurrency Quotes Latest](https://coinmarketcap.com/api/documentation/v1/#operation/getV2CryptocurrencyQuotesLatest) | GET | `/x402/v3/cryptocurrency/quotes/latest` | Get the latest market quotes for one or more cryptocurrencies. |
| [Cryptocurrency Listing Latest](https://coinmarketcap.com/api/documentation/v1/#operation/getV1CryptocurrencyListingsLatest) | GET | `/x402/v3/cryptocurrency/listings/latest` | Get a paginated list of all active cryptocurrencies with latest market data, ranked by market cap. |
| [DEX Pairs Quotes Latest](https://coinmarketcap.com/api/documentation/v1/#operation/getLatestPairsQuotes) | GET | `/x402/v4/dex/pairs/quotes/latest` | Get the latest quotes and trading data for specific DEX trading pairs. |

All parameters supported by the standard CoinMarketCap Pro API endpoints are also supported in their x402 counterparts. Refer to the linked documentation for full parameter details, limits, and response schemas. You can download the full list of IDs in a [CSV file here](https://s3.coinmarketcap.com/generated/core/crypto/idmaps.csv).

## Request examples

**Example 1**: Search DEX tokens by keyword:

```text
GET https://pro-api.coinmarketcap.com/x402/v1/dex/search?q=pepe
```

**Example 2**: Get latest quotes for Bitcoin and Ethereum by CoinMarketCap ID:

```text
GET https://pro-api.coinmarketcap.com/x402/v3/cryptocurrency/quotes/latest?id=1,1027
```

**Example 3**: Get the top 10 cryptocurrencies by market cap:

```text
GET https://pro-api.coinmarketcap.com/x402/v3/cryptocurrency/listings/latest?start=1&limit=10
```

**Example 4**: Get latest DEX pair quotes:

```text
GET https://pro-api.coinmarketcap.com/x402/v4/dex/pairs/quotes/latest?pair_address=0x...
```

**Example 5**: Using curl with a pre-signed payment header:

```bash
curl --request GET \
  --url 'https://pro-api.coinmarketcap.com/x402/v1/dex/search?q=bnb' \
  -H 'PAYMENT-SIGNATURE: {{paymentSignature}}'
```

## Pricing and payment

**Current price: $0.01 USDC per API request** across all supported endpoints.

Pricing is subject to change without prior notice. Always parse the `Payment-Required` response header for the current amount before signing.

**Supported payment network:**

- **Base** (Chain ID: 8453)

**Payment asset:**

- **USDC** on Base (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`)

**Payment method:**

- EIP-3009 `transferWithAuthorization` — your wallet signs an off-chain authorization, and the facilitator executes the on-chain transfer only upon successful data delivery.

## 402 response format

When a request is made without a valid `PAYMENT-SIGNATURE`, the server returns HTTP 402 with a base64-encoded `Payment-Required` header:

```json
{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "/x402/v1/dex/search",
    "description": "..."
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "10000",
      "payTo": "0x271189c860DB25bC43173B0335784aD68a680908",
      "maxTimeoutSeconds": 30,
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }
  ]
}
```

| Field | Description |
| --- | --- |
| `scheme` | Payment scheme, currently `exact` (EIP-3009 transferWithAuthorization) |
| `network` | Target chain in CAIP-2 format (`eip155:8453` = Base Mainnet) |
| `asset` | USDC contract address on Base |
| `amount` | Payment amount in smallest unit (10000 = $0.01 USDC, 6 decimals) |
| `payTo` | Recipient address for the payment |
| `maxTimeoutSeconds` | Maximum validity window for the signed authorization |
| `extra.name` | EIP-712 domain name for the token (must be `"USD Coin"` for USDC on Base) |
| `extra.version` | EIP-712 domain version for the token |

## Quick start

### Using the x402 TypeScript SDK

Install dependencies:

```bash
npm install @x402/axios @x402/evm viem
```

Example — fetch DEX search results with automatic x402 payment:

```typescript
import { createX402AxiosClient } from "@x402/axios";
import { ExactEvmScheme, toClientEvmSigner } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";
import { createPublicClient, http } from "viem";
import { base } from "viem/chains";

const account = privateKeyToAccount("0xYOUR_PRIVATE_KEY");
const publicClient = createPublicClient({ chain: base, transport: http() });
const signer = toClientEvmSigner(account, publicClient);

const client = createX402AxiosClient({
  schemes: [new ExactEvmScheme(signer)],
});

const response = await client.get(
  "https://pro-api.coinmarketcap.com/x402/v1/dex/search",
  { params: { q: "bnb" } },
);

console.log(response.data);
```

### Using curl (manual flow)

```bash
# Step 1: Get the 402 response with payment requirements
curl -s -D - 'https://pro-api.coinmarketcap.com/x402/v1/dex/search?q=bnb'

# Step 2: Sign the payment using your x402 client (SDK or custom implementation)

# Step 3: Retry with the payment signature
curl --request GET \
  --url 'https://pro-api.coinmarketcap.com/x402/v1/dex/search?q=bnb' \
  -H 'PAYMENT-SIGNATURE: <your-signed-payment>'
```

## Important notes

- **No API key required** — x402 payment replaces traditional API key authentication.
- **Pay only on success** — the on-chain USDC transfer is executed only when the server successfully returns data. If the server encounters an error, no payment is deducted.
- **Authorization expiry** — signed authorizations expire after `maxTimeoutSeconds` (typically 30s). Unused authorizations are never submitted on-chain.
- **EIP-712 domain** — when constructing the `transferWithAuthorization` signature, use `name: "USD Coin"` and `version: "2"` for the USDC token domain on Base.
- **Rate limits** — x402 endpoints may have separate rate limits from the standard Pro API. Refer to the `Payment-Required` response for the latest terms.