# 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

```bash
# 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:

```python
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** | <p>Base: Coinbase CDP <br>Solana: Payai</p> |

### 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).