x402 Payments

Overview

x402 enables pay-per-call access to the Nansen API using cryptocurrency. No subscription or API key required. Send a request, pay with USDC on EVM (Base) or Solana, and get data back.

How It Works

x402 is an open HTTP payment protocol. When you make a request to a supported endpoint without an API key, the server returns a 402 Payment Required response with payment instructions. Your client pays the specified amount in USDC, then retries the request with a payment receipt.

Request Flow

1. Client sends request (no API key)
2. Server returns 402 with payment details
3. Client pays USDC on Base or Solana
4. Client retries with payment receipt in header
5. Server verifies payment and returns data

Example

# 1. Initial request returns 402 with payment instructions
curl -X POST 'https://api.nansen.ai/api/v1/smart-money/holdings' \
  -H 'Content-Type: application/json' \
  -d '{"chains": ["ethereum"]}'

# Response: 402 Payment Required
# Headers include payment details (amount, recipient, network)

With an x402-compatible client, payment and retry happen automatically:

from x402.client import x402_client

client = x402_client(wallet="YOUR_WALLET")

response = client.post(
    "https://api.nansen.ai/api/v1/smart-money/holdings",
    json={"chains": ["ethereum"]}
)
# Payment handled automatically — response contains data

Pricing

All Pro-tier endpoints are available via x402 (except labels endpoint). Pricing is based on endpoint tier.

Tier	Price Per Call	Endpoints
Basic	$0.01	Token Screener, Wallet Balances, Transactions, PnL, DEX Trades, Flows, and more
Premium	$0.05	Counterparties, Holders, PnL Leaderboard, Perp Leaderboard
Smart Money	$0.05	SM Net Flow, SM Inflows, SM Holdings, SM DEX Trades

Basic Endpoints — $0.01/call

Endpoint	Path
Current Balances	/api/v1/profiler/address/current-balance
Historical Balances	/api/v1/profiler/address/historical-balances
Perp Positions	/api/v1/profiler/perp-positions
Transactions	/api/v1/profiler/address/transactions
Perp Trades	/api/v1/profiler/perp-trades
Related Wallets	/api/v1/profiler/address/related-wallets
PnL Summary	/api/v1/profiler/address/pnl-summary
PnL	/api/v1/profiler/address/pnl
Token Screener	/api/v1/token-screener
Perp Screener	/api/v1/perp-screener
Transfers	/api/v1/tgm/transfers
DCAs	/api/v1/tgm/jup-dca
Flow Intel	/api/v1/tgm/flow-intelligence
Who Bought/Sold	/api/v1/tgm/who-bought-sold
DEX Trades	/api/v1/tgm/dex-trades
DeFi Holdings	/api/v1/portfolio/defi-holdings
Flows	/api/v1/tgm/flows

Premium Endpoints — $0.05/call

Endpoint	Path
Counterparties	/api/v1/profiler/address/counterparties
Holders	/api/v1/tgm/holders
PnL Leaderboard	/api/v1/tgm/pnl-leaderboard
Perp PnL Leaderboard	/api/v1/tgm/perp-pnl-leaderboard
Perp Leaderboard	/api/v1/perp-leaderboard

Smart Money Endpoints — $0.05/call

Endpoint	Path
Net Flow	/api/v1/smart-money/netflow
Holdings	/api/v1/smart-money/holdings
DEX Trades	/api/v1/smart-money/dex-trades
All other SM endpoints	/api/v1/smart-money/*

Excluded Endpoints

• /api/v1/labels/*; these require a Pro subscription due to the proprietary nature of Nansen's entity classification data.

• /api/v1/portfolio/defi-holdings

Payment Details

Parameter	Value
Network	Base & Solana
Currency	USDC
Settlement	Instant (onchain verification)
Facilitator	Base: Coinbase CDP Solana: Payai

Rate Limits

x402 requests have separate rate limits from API key authenticated requests.

Limit	Value
Per second (per wallet)	5 requests
Per minute (per wallet)	60 requests

If you exceed rate limits, you'll receive a 429 Too Many Requests response. Payments are not charged for rate-limited requests.

FAQ

Q: Do I need a Nansen account? No. x402 is fully permissionless. You only need a wallet with USDC on Base or Solana.

Q: What happens if payment fails? You'll receive a 402 Payment Required response again. No data is returned until payment succeeds.

Q: Can I use x402 and an API key together? If you include a valid API key, it takes precedence and no x402 payment is required.

Q: Which networks are supported for payment? Currently Base and Solana. More networks may be added in the future.

Q: Is there a minimum balance required? No minimum. You just need enough USDC to cover the call price plus gas fees (typically < $0.01).