x402 — Pay-Per-Request API

Birdeye supports the x402 HTTP payment protocol, 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:

Client sends a request without payment — server responds 402 Payment Required with a PAYMENT-REQUIRED header describing payment terms (price, network, recipient address).
Client signs a Solana transaction fulfilling the payment terms and retries the request with a PAYMENT-SIGNATURE header.
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

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
Coinbase CDP — facilitator used for payment verification and settlement
bd-x402-tester — CLI tool for testing Birdeye x402 endpoints

Getting Started

Guides

Resources

x402 — Pay-Per-Request API

How It Works

Base URL

Payment Details

Quick Start

Protocol Headers

Extensions

Payment Identifier (`payment-identifier`)

Offer & Receipt (`offer-receipt`)

Rate Limits

Supported Endpoints

DeFi (v1) — `/x402/defi`

DeFi v2 — `/x402/defi/v2`

DeFi v3 — `/x402/defi/v3`

Trader — `/x402/trader`

Token — `/x402/token/v1`

Wallet v2 — `/x402/wallet/v2`

Holder — `/x402/holder/v1`

Smart Money — `/x402/smart-money/v1`

Notes

Error Responses

Resources

​How It Works

​Base URL

​Payment Details

​Quick Start

​Protocol Headers

​Extensions

​Payment Identifier (payment-identifier)

​Offer & Receipt (offer-receipt)

​Rate Limits

​Supported Endpoints

​DeFi (v1) — /x402/defi

​DeFi v2 — /x402/defi/v2

​DeFi v3 — /x402/defi/v3

​Trader — /x402/trader

​Token — /x402/token/v1

​Wallet v2 — /x402/wallet/v2

​Holder — /x402/holder/v1

​Smart Money — /x402/smart-money/v1

​Notes

​Error Responses

​Resources

How It Works

Base URL

Payment Details

Quick Start

Protocol Headers

Extensions

Payment Identifier (`payment-identifier`)

Offer & Receipt (`offer-receipt`)

Rate Limits

Supported Endpoints

DeFi (v1) — `/x402/defi`

DeFi v2 — `/x402/defi/v2`

DeFi v3 — `/x402/defi/v3`

Trader — `/x402/trader`

Token — `/x402/token/v1`

Wallet v2 — `/x402/wallet/v2`

Holder — `/x402/holder/v1`

Smart Money — `/x402/smart-money/v1`

Notes

Error Responses

Resources