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 Base, Solana, or Monad, and get data back.

Nansen supports x402 V2 only. Deprecated V1 clients and the legacy X-PAYMENT request header are not supported. If your client reports invalid_x402_version, upgrade it to V2 and send the payment using the PAYMENT-SIGNATURE header. See the official V1-to-V2 migration guide.

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, Solana, or Monad
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 eth_account import Account
from x402 import x402ClientSync
from x402.http.clients import x402_requests
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client

# Sign payments with a wallet funded with USDC on Base
account = Account.from_key("YOUR_PRIVATE_KEY")
client = x402ClientSync()
register_exact_evm_client(client, EthAccountSigner(account))

# requests-style session that pays and retries on 402 automatically
session = x402_requests(client)
response = session.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

First 100 calls promotion (when enabled)

When advertised in /.well-known/x402, each wallet can receive 50% off its first 100 successfully settled x402 calls in this promotion. A $0.01 call costs $0.005 and a $0.05 call costs $0.025. Existing and new wallets start at zero when the promotion launches; earlier payments do not use the allowance. The allowance applies once per wallet across endpoints, with the same EVM wallet sharing its allowance across payment networks. Solana wallets have a separate allowance and their addresses are case-sensitive.

Send X-Payer-Address with the wallet that will sign the payment on the initial unpaid request:

curl -i -X POST 'https://api.nansen.ai/api/v1/smart-money/holdings' \
  -H 'Content-Type: application/json' \
  -H 'X-Payer-Address: YOUR_PAYING_WALLET_ADDRESS' \
  -d '{"chains": ["ethereum"]}'

Configure your x402 V2 client's initial request with the same header. For an existing fetch wrapper that handles x402 signing and retries, the request options are:

const response = await fetchWithPayment(
  "https://api.nansen.ai/api/v1/smart-money/holdings",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Payer-Address": payingWalletAddress,
    },
    body: JSON.stringify({ chains: ["ethereum"] }),
  },
);

The address header requests a quote; it does not prove ownership. On the paid retry, the signed payment determines the wallet and eligibility. Always sign the amount offered by the current 402 response, including fractional-cent prices. A quote does not reserve a discounted call: concurrent payments can use the remaining allowance before your retry, in which case request a fresh quote and confirm its price before paying again. Once the allowance is used, requests return to standard pricing automatically.

Clients that omit the header continue to receive standard-price quotes. Successfully settled standard-price x402 calls during the promotion also count toward the first 100 calls, so send the header from your first request to use the discount. A promotion may also return a standard-price quote when availability cannot be checked. Failed requests without a successful settlement do not consume the allowance; a payment with an uncertain outcome may temporarily hold an allowance slot while it is reconciled. API credit pricing and MPP payments are unchanged.

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/profiler/address/labels and /api/v1/profiler/address/premium-labels; these require an API key, on any plan.

• /api/v1/portfolio/defi-holdings

Payment Details

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

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, Solana, or Monad.

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, Solana, and Monad. 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).