Skip to main content

​
What is x402?

x402 is an open standard introduced by Coinbase. It uses the HTTP 402 Payment Required status code to allow machines (such as AI Agents) to automatically complete on-chain micropayments when initiating API requests. Payments are made using stablecoins (like USDC), with instant, transparent settlement and no need for trusted intermediaries.

​
Pricing

All Chainbase Web3 API endpoints accessed via x402 are charged at a flat rate:
Price
Per API Call$0.01 USDC
No subscriptions, no monthly fees — just pay per request with your wallet.

​
Supported Endpoints

All Chainbase Web3 API endpoints support x402 access. Below is the complete list:

​
Token API

MethodEndpointDescription
GET/v1/token/priceGet token price
GET/v1/token/price/historyGet token price history
GET/v1/token/holdersGet token holders
GET/v1/token/top-holdersGet top token holders
GET/v1/token/metadataGet token metadata
GET/v1/token/transfersGet token transfers by contract

​
Balance API

MethodEndpointDescription
GET/v1/account/tokensGet ERC-20 token balances
GET/v1/account/balanceGet native token balances
GET/v1/account/nftsGet NFTs owned by address

​
NFT API

MethodEndpointDescription
GET/v1/nft/metadataGet NFT metadata
GET/v1/nft/rarityGet NFT rarity
GET/v1/nft/ownerGet NFT owner by token
GET/v1/nft/owner/historyGet NFT owner history by token
GET/v1/nft/ownersGet NFT owners by collection
GET/v1/nft/transfersGet NFT transfers by collection
GET/v1/nft/collection/itemsGet NFT collection items
GET/v1/nft/collectionGet NFT collection metadata
GET/v1/nft/searchSearch NFT collections

​
Domain API

MethodEndpointDescription
GET/v1/ens/recordsResolve ENS domain
GET/v1/ens/reverseReverse resolve ENS domain
GET/v1/account/ensGet ENS domains by address

​
Basic API

MethodEndpointDescription
GET/v1/block/number/latestGet latest block number
GET/v1/block/detailGet block by number
GET/v1/tx/detailGet transaction details
GET/v1/account/txsGet transactions by account
POST/v1/contract/callContract call

​
Label API

MethodEndpointDescription
GET/v1/address/labelsGet address labels

​
Integration Steps (Python Example)

​
Install Dependencies

pip install eth_account x402

​
Prepare Your Private Key

Please ensure you have an Ethereum wallet with sufficient USDC (it is recommended to use a testnet or mainnet cold wallet). Never expose your real private key in public code! 
from eth_account import Account

# For production, please read from environment variables or a key management service
PRIVATE_KEY = "your_0x_private_key_here"  # Example: 0x123...abc
account = Account.from_key(PRIVATE_KEY)

​
Initialize x402 Session

from x402.clients.requests import x402_requests

# Create an HTTP session that supports x402
session = x402_requests(account)

​
Call Chainbase API

For all Chainbase Web3 API endpoints, simply add x-api-key: x402 to the request header. The rest of the usage is consistent with the standard API. 
from pprint import pprint

# Example: Query Ethereum Mainnet USDT holder addresses ($0.01 per call)
api_url = "https://api.chainbase.com/v1/token/holders?chain_id=1&contract_address=0xdac17f958d2ee523a2206206994597c13d831ec7"

headers = {
    "x-api-key": "x402",  # Enable x402 payment
    "Accept": "application/json"
}

response = session.get(api_url, headers=headers)

if response.status_code == 200:
    pprint(response.json())
else:
    print(f"Payment failed or request error: {response.status_code} - {response.text}")

​
Use Cases

  • AI Agent automatically monitors token address changes: Query once per hour, pay per request, no monthly fee required.
  • One-time data fetching: Analyze a specific Token project, call only once, and pay just $0.01.
  • Experimental development: No need to register an enterprise account, pay directly with a wallet to test interfaces.

​
Next Steps