Integrate with Your Agent

x402warden works with any AI agent, any language, any framework. Two integration paths: a CLI your agent calls directly, or an HTTP Proxy that handles payments transparently.

Prerequisites

Before integrating, you need a funded Solana wallet on devnet.

SOL for transaction fees — Get free devnet SOL at faucet.solana.com
USDC for payments — Get free devnet USDC at faucet.circle.com (select Solana Devnet). This creates a USDC token account linked to your wallet.

What is a USDC Token Account?

On Solana, tokens like USDC live in separate "token accounts" associated with your wallet. When you request USDC from the Circle faucet, it automatically creates this account for you. Your wallet address holds SOL; the token account holds USDC. x402warden needs to know both to manage payments on your behalf.

Step 1 — Create Your Agent Account

An agent account is an on-chain smart account that enforces your spending rules. Create one by providing your USDC token account address.

Terminal

# Check your balances and USDC token account address
npx x402warden balance

# Create agent account (agent-id 0 is your first agent)
npx x402warden init --agent-id 0 --usdc-account <YOUR_USDC_TOKEN_ACCOUNT>

The balance command shows your USDC token account address. Copy it and use it in the init command.

Step 2 — Set Spending Policies

Policies define how much your agent can spend. All amounts are in USDC micro-units (1 USDC = 1,000,000 micro-units).

Terminal

npx x402warden policy \
  --max-per-call 5000000 \
  --max-per-period 50000000 \
  --period-seconds 86400 \
  --dispute-window 300

What do the numbers mean?

--max-per-call 5000000 = max 5 USDC per individual payment
--max-per-period 50000000 = max 50 USDC total per period
--period-seconds 86400 = period resets every 24 hours (86,400 seconds)
--dispute-window 300 = 5-minute window (300 seconds) to dispute a payment before it settles

You can also configure policies from the Dashboard with a visual interface.

Integration Path A

CLI — Direct Command

Your agent calls x402warden pay as a subprocess. It handles the entire x402 flow: request, 402 detection, on-chain payment, retry. Returns JSON to stdout.

Any agent — shell out to CLI

# Simple GET request to a paywalled service
npx x402warden pay https://api.example.com/research

# POST with body and headers
npx x402warden pay https://api.example.com/analyze \
  --method POST \
  --body '{"query": "Solana TVL trends"}' \
  --headers '{"Content-Type": "application/json"}'

# Set a max amount you're willing to pay (in micro-USDC)
npx x402warden pay https://api.example.com/data --max-amount 10000000

The CLI returns JSON you can parse in any language:

Response (stdout)

{
  "status": "paid",
  "statusCode": 200,
  "txSignature": "4fW...ABCD",
  "amountPaid": 5000000,
  "body": { "data": "..." }
}

Use from any language:

Python

import subprocess, json

result = subprocess.run(
    ["npx", "x402warden", "pay", "https://api.example.com/research"],
    capture_output=True, text=True
)
data = json.loads(result.stdout)
print(data["body"])  # The actual API response

Node.js

import { execSync } from "child_process";

const result = JSON.parse(
  execSync("npx x402warden pay https://api.example.com/research").toString()
);
console.log(result.body);

Exit codes

0 — Success (payment made or no payment needed)
1 — Payment blocked by your spending policy
2 — Error (network, config, insufficient funds)

Integration Path B

HTTP Proxy — Zero Code Changes

Start a local proxy server. Point your agent's HTTP client to it. The proxy intercepts 402 responses, pays on-chain, retries with the payment header. Your agent doesn't know it's paying — it just gets the data.

Terminal 1 — Start the proxy

npx x402warden-proxy --port 4020

Terminal 2 — Use it with curl

# The proxy handles the 402 payment automatically
curl -x http://localhost:4020 http://api.example.com/research

# Works with any HTTP client
HTTP_PROXY=http://localhost:4020 curl http://api.example.com/data

Use from your agent code:

Python (httpx)

import httpx

# All requests through the proxy are x402-protected
client = httpx.Client(proxy="http://localhost:4020")
response = client.get("http://api.example.com/research")
print(response.json())  # Payment handled transparently

Node.js (fetch with proxy)

// Set the environment variable before running your agent
// HTTP_PROXY=http://localhost:4020 node my-agent.js

const response = await fetch("http://api.example.com/research");
const data = await response.json();

HTTPS targets

For HTTPS services, use the gateway mode instead of the proxy mode. Send your request to http://localhost:4020 with a X-TARGET-URL header pointing to the real endpoint.

Configuration

Both CLI and Proxy read configuration from environment variables:

Variable	Default	Description
SOLANA_KEYPAIR_PATH	~/.config/solana/id.json	Path to your Solana keypair file
SOLANA_RPC_URL	devnet	Solana RPC endpoint
AGENT_ID	0	Which agent account to use (you can have multiple)
USDC_MINT	devnet USDC	USDC token mint address

How x402 Payment Works

1. Your agent requests a service

2. Service returns HTTP 402 with price + merchant address

3. x402warden checks your spending policy on-chain

4. If allowed → USDC moves to escrow (not directly to merchant)

5. Request retried with payment proof → service responds with data

6. 5-min dispute window — if service failed, you get a refund

7. After window closes → funds released to merchant