--- updatedAt: 2026-08-03T08:43:55.000Z --- Fetch the complete documentation index at: https://docs.birdeye.so/llms.txt. Use this file to discover all available pages before exploring further. # x402 — Pay-Per-Request API Birdeye supports the [x402 HTTP payment protocol](https://x402.org), allowing AI agents and programmatic clients to access real-time DeFi data without API keys. Each request is paid individually on-chain using USDC on Solana. *** ## How It Works x402 extends HTTP 402 (Payment Required) into a machine-negotiable flow: 1. Client sends a request without payment — server responds `402 Payment Required` with a `PAYMENT-REQUIRED` header describing payment terms (price, network, recipient address). 2. Client signs a Solana transaction fulfilling the payment terms and retries the request with a `PAYMENT-SIGNATURE` header. 3. Server verifies and settles the payment via the Coinbase CDP facilitator, then returns the data along with a `PAYMENT-RESPONSE` header confirming settlement. No API key. No subscription. No custody of funds — agents hold their own keys. *** ## Base URL ``` https://public-api.birdeye.so ``` All x402 endpoints are prefixed with `/x402`. *** ## Payment Details | Parameter | Value | | ----------- | -------------------------------------------------------------- | | Scheme | `exact` | | Network | `solana-mainnet` | | Currency | USDC | | Price | Per-request (see route configurations) | | Facilitator | Coinbase CDP (`https://api.cdp.coinbase.com/platform/v2/x402`) | | Max Timeout | 60 seconds | *** ## Quick Start ```javascript import { withPaymentInterceptor } from "@x402/fetch"; const fetch = withPaymentInterceptor(globalThis.fetch, { wallet: myWallet, // Solana wallet with USDC }); const response = await fetch( "https://public-api.birdeye.so/x402/defi/token_overview?address=So11111111111111111111111111111111111111112" ); const data = await response.json(); ``` *** ## Protocol Headers | Header | Direction | Description | | ------------------- | --------------- | -------------------------------------------------------- | | `PAYMENT-REQUIRED` | Server → Client | Base64-encoded JSON with payment terms (on 402 response) | | `PAYMENT-SIGNATURE` | Client → Server | Signed payment payload for verification | | `PAYMENT-RESPONSE` | Server → Client | Settlement confirmation after successful payment | *** ## Extensions Every x402 endpoint includes two extensions that enhance security and verifiability: ### Payment Identifier (`payment-identifier`) Enforces idempotency and prevents replay attacks. Each request must include a unique `id` in the payment extension. ``` id pattern: ^pay_[a-zA-Z0-9_-]{10,120}$ ``` ### Offer & Receipt (`offer-receipt`) Provides cryptographic commitment for payment terms and proof of service delivery: * **Offer** — signed before payment, commits the server to the price and service * **Receipt** — signed after successful delivery, provides an audit trail *** ## Rate Limits * **100 requests/second per IP** applied before payment verification. * Exceeding this returns `429 Too Many Requests`. *** ## Supported Endpoints ### DeFi (v1) — `/x402/defi` | Method | Path | Description | | ------ | ----------------------------------- | ---------------------------------- | | `GET` | `/x402/defi/price` | Token price | | `GET` | `/x402/defi/history_price` | Historical price | | `GET` | `/x402/defi/historical_price_unix` | Historical price at Unix timestamp | | `GET` | `/x402/defi/txs/token` | Token transactions | | `GET` | `/x402/defi/txs/pair` | Pair transactions | | `GET` | `/x402/defi/txs/token/seek_by_time` | Token transactions seek by time | | `GET` | `/x402/defi/txs/pair/seek_by_time` | Pair transactions seek by time | | `GET` | `/x402/defi/ohlcv` | OHLCV candlestick data | | `GET` | `/x402/defi/ohlcv/pair` | OHLCV data for a trading pair | | `GET` | `/x402/defi/ohlcv/base_quote` | OHLCV data by base/quote addresses | | `GET` | `/x402/defi/tokenlist` | Token list | | `GET` | `/x402/defi/token_trending` | Trending tokens | | `GET` | `/x402/defi/token_creation_info` | Token creation information | | `GET` | `/x402/defi/token_security` | Token security analysis | | `GET` | `/x402/defi/token_overview` | Token overview | | `GET` | `/x402/defi/price_volume/single` | Single token price and volume | | `GET` | `/x402/defi/multi_price` | Token prices (multiple) | | `POST` | `/x402/defi/multi_price` | Token prices (multiple) | | `POST` | `/x402/defi/price_volume/multi` | Token price and volume (multiple) | ### DeFi v2 — `/x402/defi/v2` | Method | Path | Description | | ------ | ---------------------------------- | --------------------------- | | `GET` | `/x402/defi/v2/tokens/new_listing` | New token listings | | `GET` | `/x402/defi/v2/tokens/top_traders` | Top traders for a token | | `GET` | `/x402/defi/v2/markets` | All market list for a token | ### DeFi v3 — `/x402/defi/v3` | Method | Path | Description | | ------ | --------------------------------------------- | --------------------------------- | | `GET` | `/x402/defi/v3/token/meta-data/single` | Token metadata (single) | | `GET` | `/x402/defi/v3/token/meta-data/multiple` | Token metadata (multiple) | | `GET` | `/x402/defi/v3/pair/overview/multiple` | Pair overview (multiple) | | `GET` | `/x402/defi/v3/pair/overview/single` | Pair overview (single) | | `GET` | `/x402/defi/v3/token/market-data/multiple` | Token market data (multiple) | | `GET` | `/x402/defi/v3/token/market-data` | Token market data | | `GET` | `/x402/defi/v3/token/trade-data/single` | Token trade data (single) | | `GET` | `/x402/defi/v3/token/trade-data/multiple` | Token trade data (multiple) | | `GET` | `/x402/defi/v3/token/holder` | Token holders | | `GET` | `/x402/defi/v3/search` | Search tokens and market data | | `GET` | `/x402/defi/v3/token/mint-burn-txs` | Token mint/burn transactions | | `GET` | `/x402/defi/v3/holder-stats/single` | Holder statistics (single) | | `GET` | `/x402/defi/v3/token/list` | Token list (v3) | | `GET` | `/x402/defi/v3/all-time/trades/single` | All-time trades (single) | | `POST` | `/x402/defi/v3/all-time/trades/multiple` | All-time trades (multiple) | | `GET` | `/x402/defi/v3/txs/recent` | Recent trades (v3) | | `GET` | `/x402/defi/v3/txs` | All trades (v3) | | `GET` | `/x402/defi/v3/token/txs` | Token trades (v3) | | `GET` | `/x402/defi/v3/txs/latest-block` | Latest block number | | `GET` | `/x402/defi/v3/token/exit-liquidity` | Token exit liquidity | | `GET` | `/x402/defi/v3/token/exit-liquidity/multiple` | Token exit liquidity (multiple) | | `GET` | `/x402/defi/v3/token/meme/list` | Meme token list | | `GET` | `/x402/defi/v3/token/meme/detail/single` | Meme token detail (single) | | `GET` | `/x402/defi/v3/token/txs-by-volume` | Token trades filtered by volume | | `GET` | `/x402/defi/v3/ohlcv` | OHLCV (v3) | | `GET` | `/x402/defi/v3/ohlcv/pair` | OHLCV pair (v3) | | `GET` | `/x402/defi/v3/price/stats/single` | Price stats (single) | | `POST` | `/x402/defi/v3/price/stats/multiple` | Price stats (multiple) | | `POST` | `/x402/defi/v3/liquidity/latest/token` | Latest token liquidity (multiple) | ### Trader — `/x402/trader` | Method | Path | Description | | ------ | ------------------------------- | -------------------------------- | | `GET` | `/x402/trader/gainers-losers` | Top gainers and losers | | `GET` | `/x402/trader/txs/seek_by_time` | Trader transactions seek by time | ### Token — `/x402/token/v1` > Solana only. | Method | Path | Description | | ------ | -------------------------------------------- | --------------------------- | | `POST` | `/x402/token/v1/transfer` | Token transfer list | | `POST` | `/x402/token/v1/transfer/total` | Token transfer total | | `GET` | `/x402/token/v1/holder-profile` | Token holder profile | | `GET` | `/x402/token/v1/holder-positions` | Token holder positions | | `GET` | `/x402/token/v1/first-buyers` | Token first buyers | | `GET` | `/x402/token/v1/holder/chart` | Token holder chart | | `GET` | `/x402/token/v1/wallet-tags-tracker` | Wallet tags tracker | | `GET` | `/x402/token/v1/wallet-tags-tracker/details` | Wallet tags tracker details | ### Wallet v2 — `/x402/wallet/v2` | Method | Path | Description | | ------ | ------------------------------- | ------------------------------- | | `GET` | `/x402/wallet/v2/pnl/multiple` | Wallet PnL (multiple) | | `POST` | `/x402/wallet/v2/token-balance` | Wallet token balance (multiple) | ### Holder — `/x402/holder/v1` > Solana only. | Method | Path | Description | | ------ | ------------------------------ | ------------------------- | | `GET` | `/x402/holder/v1/distribution` | Token holder distribution | ### Smart Money — `/x402/smart-money/v1` > Solana only. | Method | Path | Description | | ------ | --------------------------------- | ---------------------- | | `GET` | `/x402/smart-money/v1/token/list` | Smart money token list | *** ## Notes * **x402 supports 12 multiple or batch endpoints** across DeFi v1, DeFi v3, and Wallet v2. * **Solana-only routes** — Token, Holder, and Smart Money endpoints are restricted to the Solana chain. * **Idempotent retries** — If your request is retried with the same payment ID, the server returns a cached response without charging again (within the TTL window). * **Replay protection** — Payment IDs are stored in Redis. Reusing a payment ID with a different request is rejected. *** ## Error Responses | Status | Meaning | | ------------------------- | --------------------------------------------------------------------------- | | `402 Payment Required` | No valid payment provided. Inspect the `PAYMENT-REQUIRED` header for terms. | | `429 Too Many Requests` | IP rate limit exceeded (100 req/s). | | `503 Service Unavailable` | Payment validation service failed to initialize. | *** ## Resources * [x402 Protocol Specification](https://x402.org) * [Coinbase CDP](https://docs.cdp.coinbase.com) — facilitator used for payment verification and settlement * [bd-x402-tester](https://github.com/sondnm/bd-x402-tester) — CLI tool for testing Birdeye x402 endpoints