x402 Protocol

LimitGuard implements the x402 V2 micropayment protocol for AI agent pay-per-use access. No subscription or API key required — agents pay per call in USDC.

Overview

x402 extends HTTP with a payment layer. The flow is simple:

Request without payment

Agent makes a normal API request.

Receive HTTP 402

Server returns payment requirements — chain, amount, recipient, contract address.

Build payment signature

Agent constructs an EIP-3009 TransferWithAuthorization signature.

Retry with X-PAYMENT header

Agent retries the same request with the base64-encoded payment header.

Receive response

Server verifies signature, processes the request, and returns the result.

Supported Networks

Network	CAIP-2 Chain ID	USDC Contract
Base Mainnet	`eip155:8453`	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
Base Sepolia	`eip155:84532`	`0x036CbD53842c5426634e7929541eC2318f3dCF7e`
Solana Mainnet	`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`	`EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`
Solana Devnet	`solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`	`4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU`

Step 1: Discover Payment Requirements

Make a request without payment to get the requirements:

curl -X POST https://api.limitguard.ai/v1/entity/check \
  -H "Content-Type: application/json" \
  -d '{"entity_name": "Acme Corp BV", "country": "NL"}'

HTTP 402 Response

{
  "x402Version": "2",
  "error": "Payment Required",
  "accepts": [
    {
      "chainId": "eip155:8453",
      "currency": "USDC",
      "contractAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "50000",
      "decimals": 6,
      "recipient": "0xFacilitatorAddress",
      "description": "LimitGuard API call (0.05 USDC)"
    },
    {
      "chainId": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "currency": "USDC",
      "contractAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "amount": "50000",
      "decimals": 6,
      "recipient": "SolanaFacilitatorAddress",
      "description": "LimitGuard API call (0.05 USDC)"
    }
  ]
}

Step 2: Build EVM Payment (Base / EIP-3009)

import base64, json, secrets, time
from eth_account import Account
from eth_account.messages import encode_typed_data

def build_x402_payment(
    chain_id: str,          # e.g. "eip155:8453"
    amount: int,            # in USDC 6-decimal units
    sender_key: str,        # private key (hex)
    recipient: str,         # facilitator address
    usdc_address: str,      # USDC contract address
) -> str:
    sender = Account.from_key(sender_key).address
    chain_num = int(chain_id.split(":")[1])  # 8453

    nonce = "0x" + secrets.token_hex(32)
    now = int(time.time())

    # EIP-712 domain
    domain = {
        "name": "USD Coin",
        "version": "2",
        "chainId": chain_num,
        "verifyingContract": usdc_address,
    }

    # EIP-3009 TransferWithAuthorization
    message = {
        "from": sender,
        "to": recipient,
        "value": amount,
        "validAfter": now - 10,
        "validBefore": now + 300,
        "nonce": bytes.fromhex(nonce[2:]),
    }

    types = {
        "EIP712Domain": [
            {"name": "name", "type": "string"},
            {"name": "version", "type": "string"},
            {"name": "chainId", "type": "uint256"},
            {"name": "verifyingContract", "type": "address"},
        ],
        "TransferWithAuthorization": [
            {"name": "from", "type": "address"},
            {"name": "to", "type": "address"},
            {"name": "value", "type": "uint256"},
            {"name": "validAfter", "type": "uint256"},
            {"name": "validBefore", "type": "uint256"},
            {"name": "nonce", "type": "bytes32"},
        ],
    }

    signable = encode_typed_data(domain, types, "TransferWithAuthorization", message)
    signed = Account.sign_message(signable, private_key=sender_key)

    payload = {
        "chainId": chain_id,
        "amount": str(amount),
        "sender": sender,
        "recipient": recipient,
        "nonce": nonce,
        "signature": signed.signature.hex(),
        "validAfter": now - 10,
        "validBefore": now + 300,
    }

    return base64.b64encode(json.dumps(payload).encode()).decode()

import { ethers } from "ethers";

async function buildX402Payment(
  chainId,      // "eip155:8453"
  amount,       // 50000 (USDC 6-decimal)
  signer,       // ethers.Wallet
  recipient,    // facilitator address
  usdcAddress   // USDC contract
) {
  const chainNum = parseInt(chainId.split(":")[1]);
  const nonce = "0x" + [...crypto.getRandomValues(new Uint8Array(32))]
    .map((b) => b.toString(16).padStart(2, "0")).join("");
  const now = Math.floor(Date.now() / 1000);

  const domain = {
    name: "USD Coin",
    version: "2",
    chainId: chainNum,
    verifyingContract: usdcAddress,
  };

  const types = {
    TransferWithAuthorization: [
      { name: "from", type: "address" },
      { name: "to", type: "address" },
      { name: "value", type: "uint256" },
      { name: "validAfter", type: "uint256" },
      { name: "validBefore", type: "uint256" },
      { name: "nonce", type: "bytes32" },
    ],
  };

  const message = {
    from: signer.address,
    to: recipient,
    value: amount,
    validAfter: now - 10,
    validBefore: now + 300,
    nonce: nonce,
  };

  const signature = await signer.signTypedData(domain, types, message);

  const payload = {
    chainId,
    amount: String(amount),
    sender: signer.address,
    recipient,
    nonce,
    signature,
    validAfter: now - 10,
    validBefore: now + 300,
  };

  return btoa(JSON.stringify(payload));
}

Step 3: Make Paid Request

import httpx

x_payment = build_x402_payment(
    chain_id="eip155:8453",
    amount=50_000,           # $0.05 for /v1/entity/check (fresh)
    sender_key="0xYOUR_PRIVATE_KEY",
    recipient="0xFacilitatorFromThe402Response",
    usdc_address="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
)

response = httpx.post(
    "https://api.limitguard.ai/v1/entity/check",
    headers={"X-PAYMENT": x_payment, "Content-Type": "application/json"},
    json={"entity_name": "Acme Corp BV", "country": "NL"},
)
print(response.json())

curl -X POST https://api.limitguard.ai/v1/entity/check \
  -H "X-PAYMENT: <base64-encoded-payment>" \
  -H "Content-Type: application/json" \
  -d '{"entity_name": "Acme Corp BV", "country": "NL"}'

Response Headers

On successful payment verification, these headers are included:

Header	Value	Meaning
`X-Payment-Verified`	`true`	Payment accepted
`X-Payment-Amount`	`50000`	Amount verified (6-decimal USDC)
`X-Payment-Fallback`	`true`	Circuit breaker triggered (rare)

Replay Prevention

Each nonce can only be used once. Nonces are tracked in Redis with a 5-minute TTL. Reusing a nonce returns:

HTTP 402
{
  "error": "Nonce already used (replay detected)"
}

Quality Tiers with x402

Control cost via the X-Response-Quality header. The amount in X-PAYMENT must match or exceed the price for the selected tier:

Tier	/v1/entity/check	/v1/risk/score	/v1/kyb/check
`cached`	$0.01 (10,000)	$0.005 (5,000)	$0.25 (250,000)
`fresh`	$0.05 (50,000)	$0.01 (10,000)	$1.25 (1,250,000)
`enhanced`	$0.15 (150,000)	$0.05 (50,000)	$2.50 (2,500,000)

If the payment amount is insufficient for the requested tier, you’ll receive HTTP 402 with the correct amount.

Circuit Breaker Fallback

If the payment facilitator is unavailable (circuit breaker open), LimitGuard falls back to a verified wallet cache. Wallets that have previously completed verified payments are cached. The response includes X-Payment-Fallback: true when this path is used.

Discovery

AI agents can discover LimitGuard’s x402 payment requirements automatically:

curl https://api.limitguard.ai/.well-known/x402.json

Returns a Bazaar-compatible service listing with all endpoints, pricing, and accepted payment methods.

V1 Backward Compatibility

The older PAYMENT-SIGNATURE header (V1 format) is still accepted for backward compatibility. V2 (X-PAYMENT) is recommended for all new integrations.

Get Started

Core Concepts

Guides

Overview

Supported Networks

Step 1: Discover Payment Requirements

Step 2: Build EVM Payment (Base / EIP-3009)

Step 3: Make Paid Request

Response Headers

Replay Prevention

Quality Tiers with x402

Circuit Breaker Fallback

Discovery

V1 Backward Compatibility

​Overview

​Supported Networks

​Step 1: Discover Payment Requirements

​Step 2: Build EVM Payment (Base / EIP-3009)

​Step 3: Make Paid Request

​Response Headers

​Replay Prevention

​Quality Tiers with x402

​Circuit Breaker Fallback

​Discovery

​V1 Backward Compatibility

Overview

Supported Networks

Step 1: Discover Payment Requirements

Step 2: Build EVM Payment (Base / EIP-3009)

Step 3: Make Paid Request

Response Headers

Replay Prevention

Quality Tiers with x402

Circuit Breaker Fallback

Discovery

V1 Backward Compatibility