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:

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

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

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

DeFi v2 — /x402/defi/v2

DeFi v3 — /x402/defi/v3

Trader — /x402/trader

Token — /x402/token/v1

Solana only.

Holder — /x402/holder/v1

Solana only.

Smart Money — /x402/smart-money/v1

Solana only.

Notes

• Multi-address endpoints excluded — Routes that accept multiple addresses (e.g., /token/meta-data/multiple) are not available on the x402 API. Use the standard API with an API key for bulk operations.
• 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

Resources

• x402 Protocol Specification
• Coinbase CDP — facilitator used for payment verification and settlement
• bd-x402-tester — CLI tool for testing Birdeye x402 endpoints