AI Agent Integration

Guide for AI agents to autonomously discover, pay for, and access x402-enabled APIs using the SVM Facilitator on Solana.

Overview

AI agents can programmatically interact with paid APIs using the x402 protocol. When an agent encounters an HTTP 402 Payment Required response, it can automatically:

1. Parse payment requirements
2. Construct a signed payment transaction
3. Retry the request with the payment attached
4. Access the paid resource

No accounts, API keys, or registration needed — just a Solana wallet with USDC.

How It Works

sequenceDiagram
    participant Agent
    participant Server
    participant Facilitator as facilitator.svmacc.tech

    Agent->>Server: GET /api/data
    Server-->>Agent: 402 + Payment Requirements
    Note over Agent: Sign USDC transfer tx
    Agent->>Server: GET /api/data + X-PAYMENT header
    Server->>Facilitator: POST /verify (validate payment)
    Facilitator-->>Server: { isValid: true }
    Server->>Facilitator: POST /settle (execute on-chain)
    Facilitator-->>Server: { success: true, tx_hash }
    Server-->>Agent: 200 + Response Data

Quick Start with SDK

The simplest way to integrate x402 into an AI agent is using the client SDKs, which handle the entire payment flow automatically.

TypeScript (Fetch)

npm install x402-fetch viem

import { wrapFetchWithPayment } from "x402-fetch";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(PRIVATE_KEY);
const fetchWithPayment = wrapFetchWithPayment(fetch, account);

// Automatically handles 402 → sign → retry
const response = await fetchWithPayment("https://merchant.example/api/data");
const data = await response.json();

TypeScript (Axios)

npm install x402-axios axios viem

import axios from "axios";
import { withPaymentInterceptor } from "x402-axios";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(PRIVATE_KEY);
const client = withPaymentInterceptor(axios.create(), account);

const response = await client.get("https://merchant.example/api/data");

Python (httpx)

pip install httpx eth-account x402

from eth_account import Account
from x402.client.httpx import x402HttpxClient

account = Account.from_key(PRIVATE_KEY)

async with x402HttpxClient(account=account, base_url=SERVER_URL) as client:
    response = await client.get("/api/data")
    data = await response.aread()

Python (requests)

pip install requests eth-account x402

from eth_account import Account
from x402.client.requests import x402Session

account = Account.from_key(PRIVATE_KEY)
session = x402Session(account=account)

response = session.get("https://merchant.example/api/data")
data = response.json()

Payment Requirements Format

When an agent receives a 402 response, the body contains:

{
  "x402Version": 1,
  "error": "Payment required to access this resource",
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana",
      "maxAmountRequired": "1000",
      "asset": "<USDC_TOKEN_ADDRESS>",
      "payTo": "<MERCHANT_WALLET>",
      "resource": "https://merchant.example/api/data",
      "description": "Access premium data",
      "maxTimeoutSeconds": 60
    }
  ]
}

Payment Header Format

The agent constructs a Solana transaction and sends it as a base64-encoded X-PAYMENT header:

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "solana",
  "payload": {
    "transaction": "<base64-encoded-partially-signed-transaction>"
  }
}

Settlement Response

After successful payment, the X-PAYMENT-RESPONSE header contains:

{
  "success": true,
  "transaction": "<solana_tx_signature>",
  "network": "solana",
  "payer": "<payer_wallet_address>"
}

Agent Decision Guide

When encountering a paid API, the agent should:

1. Check the price — accepts[].maxAmountRequired (in atomic units, e.g. 1000 = $0.001 USDC)
2. Verify the network — must be solana
3. Confirm the asset — must be USDC
4. Evaluate cost vs value — is the data worth the price for the current task?
5. Check wallet balance — ensure sufficient USDC before attempting payment
6. Proceed or skip — only pay if the resource is necessary

Error Handling

HTTP Status	Meaning	Agent Action
200	Success	Process response normally
402	Payment required	Parse requirements, sign tx, retry
400	Invalid payment	Check payload format and retry
500	Server error	Retry after delay

Facilitator Error Codes

Code	Meaning
insufficient_funds	Wallet doesn't have enough USDC
invalid_network	Network not supported by facilitator
invalid_payload	Malformed payment data
invalid_scheme	Unsupported payment scheme
invalid_transaction_state	Transaction rejected by Solana

SKILL.md for AI Agents

A machine-readable skill file is available at:

https://docs.svmacc.tech/SKILL.md

AI agents can fetch this file to learn how to interact with x402 APIs using the SVM Facilitator.