X402

Accept USDC and pathUSD payments via x402 protocol

x402 Payments

Accept cryptocurrency payments using the x402 protocol on Base network and Tempo chain.

Overview

x402 is a payment protocol that enables HTTP requests to require payment. Agents can pay for API access programmatically. The protocol supports the following networks:

• Base — USDC payments for general API access
• Tempo — pathUSD payments for agent-to-agent operations such as cloning
• Solana — Recipient addresses on Solana are accepted for the pay action. Solana addresses use Base58 encoding (32–44 characters).

x402 Gateway (v4.0.1-mppx)

The Agentbot x402 Gateway is deployed on Railway and provides:

• MPP (Machine Payment Protocol) — Standard 402 payment flow via mppx/express
• Agent Marketplace — Discovery, A2A payments, fitness scoring
• Session-based billing — Pay-per-use without per-transaction signing
• Anti-scam guard — Rate limits, payment caps, cooldowns, blacklist

Gateway URL

https://x402-gw-v2-production.up.railway.app

Health Check

curl https://x402-gw-v2-production.up.railway.app/health

Response:

{
  "status": "healthy",
  "service": "x402-gateway",
  "version": "4.0.1-mppx",
  "mpp": true,
  "testnet": true,
  "operator": {
    "address": "0x23c3b2Eff9633793DFDc70Ae2b9e4A669b146a62",
    "configured": true
  }
}

Session-Based Endpoints (MPP)

Session endpoints use the MPP protocol for pay-per-use billing. Clients deposit once, then use off-chain vouchers for subsequent requests.

Available Services

Endpoint	Price	Description
/api/sessions/inference	£0.05/call	AI inference calls
/api/sessions/blockdb	£0.001/query	Blockchain data queries
/api/sessions/premium	£0.01/request	Premium API access
/api/sessions/visual-synth	£0.02/render	Visual content generation
/api/sessions/setlist	£0.03/set	Music setlist generation
/api/sessions/stream	£0.001/token	SSE streaming

Example: AI Inference

# First request — returns 402 Payment Required
curl -v https://x402-gw-v2-production.up.railway.app/api/sessions/inference

# Response includes MPP challenge:
# HTTP/1.1 402 Payment Required
# Content-Type: application/json
{
  "type": "https://paymentauth.org/problems/payment-required",
  "title": "Payment Required",
  "status": 402,
  "detail": "Payment is required.",
  "challengeId": "pyksVi15Phh-HG0zNW5IlajnpZ_bFo_7wRUTZFvwGHo"
}

Agent Marketplace

List All Agents

curl https://x402-gw-v2-production.up.railway.app/gateway/marketplace

Response:

{
  "agents": [
    {
      "id": "atlas",
      "walletAddress": "0xd8fd0e1dce89beaab924ac68098ddb17613db56f",
      "totalTransactions": 5,
      "successfulTransactions": 5,
      "totalAmount": 0.009,
      "successRate": 100,
      "tier": "premium",
      "colonyId": "tempo-x402",
      "createdAt": "2026-03-23T00:05:39.093Z"
    }
  ],
  "total": 1,
  "colonies": 1
}

Discover Agent

curl https://x402-gw-v2-production.up.railway.app/gateway/marketplace/atlas

Agent Fitness Score

curl https://x402-gw-v2-production.up.railway.app/gateway/fitness/atlas

Response:

{
  "score": 75,
  "tier": "standard",
  "details": {
    "successRate": 100,
    "recencyBonus": 14.64,
    "volumeBonus": 0.00009,
    "totalTransactions": 5,
    "totalAmount": 0.009
  }
}

Dynamic Pricing

curl https://x402-gw-v2-production.up.railway.app/gateway/pricing/atlas

Premium agents (>80 fitness) get 20% discount. Standard agents (>60) get 10%.

Join Colony

curl -X POST https://x402-gw-v2-production.up.railway.app/gateway/colony/join \
  -H "Content-Type: application/json" \
  -d '{"agentId": "my-agent", "walletAddress": "0x..."}'

Agent-to-Agent Payment

curl -X POST https://x402-gw-v2-production.up.railway.app/gateway/marketplace/pay \
  -H "Content-Type: application/json" \
  -d '{"fromAgentId": "buyer", "toAgentId": "seller", "amount": 0.01}'

Auto-Settlement

The operator wallet sponsors gas and handles auto-settlement:

curl -X POST https://x402-gw-v2-production.up.railway.app/gateway/settle/auto \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "atlas",
    "amount": 0.01,
    "recipient": "0xd8fd0e1dce89beaab924ac68098ddb17613db56f"
  }'

Response:

{
  "status": "settled",
  "hash": "0x...",
  "amount": 0.01,
  "recipient": "0xd8fd0e1dce89beaab924ac68098ddb17613db56f",
  "agentId": "atlas",
  "gasSponsored": true
}

402 Index listing

Our gateway is registered on the 402 Index — a protocol-agnostic directory of paid APIs:

Service	Protocol	Status
Agentbot AI Inference	MPP	healthy
Agentbot BlockDB	MPP	healthy
Agentbot Premium API	MPP	healthy
Agentbot Visual Synth	MPP	healthy
Agentbot Setlist Oracle	MPP	healthy
Agentbot Stream	MPP	healthy

Domain verified: x402-gw-v2-production.up.railway.app

Domain verification endpoint

402 Index verifies domain ownership through a static verification file served at a well-known path:

GET /.well-known/402index-verify.txt

This endpoint returns a SHA-256 hash token that 402 Index uses to confirm you control the domain. The response is a plain-text string with no additional formatting.

The verification token is managed by the 402 Index team. If you need to reset or rotate your token, contact 402 Index support.

Anti-scam guard

The gateway and the Agentbot API include built-in payment protections:

• Rate limiting — Per-IP request limits (60 requests/min, 1,000 requests/hr on the web API)
• Payment caps — Maximum single payment of $100 via the /api/x402 pay action. Contact support for higher limits.
• Address validation — Recipient addresses are validated against EVM (42-character 0x-prefixed hex) and Solana (32–44 character Base58) formats before any payment is processed
• Cooldowns — Minimum time between payments
• Blacklist — Blocked addresses/IPs
• Whitelist — Trusted agents bypass checks
• Audit logging — Every payment attempt is logged with the user’s email, amount, currency, recipient, and payment method

curl https://x402-gw-v2-production.up.railway.app/gateway/guard

x402-Node Bridge

The gateway can proxy requests to the tempo-x402 x402-node for on-chain settlement:

curl -X POST https://x402-gw-v2-production.up.railway.app/gateway/x402-node/settle \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "/instance/info",
    "method": "GET",
    "agentId": "atlas"
  }'

Architecture

┌─────────────────────────────────────────────────────────┐
│                   Agentbot Gateway                       │
│  (Vercel — agentbot.raveculture.xyz)                     │
├─────────────────────────────────────────────────────────┤
│  Auth (Base SDK SIWE)    │  Stripe Checkout             │
│  Agent Provisioning      │  Dashboard                   │
└────────────────┬────────────────────────┬───────────────┘
                 │                        │
    ┌────────────▼────────────┐  ┌───────▼────────────────┐
    │  x402 Gateway (Railway) │  │  Stripe Webhooks       │
    │  v4.0.1-mppx            │  │  (Render)              │
    ├─────────────────────────┤  └────────────────────────┘
    │  MPP Session Billing    │
    │  Agent Marketplace      │
    │  Anti-Scam Guard        │
    │  Auto-Settlement        │
    └────────────┬────────────┘
                 │
    ┌────────────▼────────────┐
    │  Tempo Network          │
    │  (Testnet: 42431)       │
    │  pathUSD Token          │
    └─────────────────────────┘

scheme: “exact”, price: “$0.001”, network: “eip155:8453”, payTo: x402Config.payTo, }, description: “Premium API endpoint”, mimeType: “application/json”, };

### Step 3: Check for Payment

```typescript
export async function GET(req: NextRequest) {
  const server = getX402Server();
  
  const authHeader = req.headers.get("x-payments");
  if (!authHeader) {
    return new NextResponse(
      JSON.stringify({ 
        error: "Payment required",
        payment: paymentRequirements 
      }), 
      { status: 402 }
    );
  }

  // Verify and process payment
  // Return data
  return Response.json({ data: "Hello, paid user!" });
}

Paying a Solana recipient

You can send payments to Solana wallet addresses through the pay action. Provide a valid Base58-encoded address (32–44 characters) in the recipient field.

curl -X POST https://agentbot.sh/api/x402 \
  -H "Content-Type: application/json" \
  -H "Cookie: next-auth.session-token=YOUR_SESSION" \
  -d '{
    "agentId": "inst_abc123",
    "action": "pay",
    "amount": 5.0,
    "currency": "USDC",
    "recipient": "DRpbCBMxVnDK7maPGv7USk2Lgt2GXEimhi82kUhP2GBn"
  }'

The gateway validates the address format before processing. If the address is not a valid EVM or Solana address, the request returns a 400 error with the message Invalid recipient address.

Solana support is limited to the pay action. Session-based MPP endpoints, colony membership, and clone payments continue to use Base (USDC) and Tempo (pathUSD) networks.

Agent payment flow

Agents can make paid API calls:

// Agent makes a paid request
const response = await fetch('https://api.example.com/paid-endpoint', {
  headers: {
    'x-payments': paymentHeader // Automatically handled by x402 SDK
  }
});

if (response.status === 402) {
  // Payment required - x402 SDK handles payment automatically
  const data = await response.json();
  // Retry with payment
}

Tempo chain

The Tempo chain extends the x402 protocol for agent-to-agent payments using pathUSD. This is used by the clone endpoint to enable agent self-replication.

Clone payment flow

Agents pay 1.0 pathUSD on the Tempo chain to clone themselves. The flow is:

1. The parent agent sends 1.0 pathUSD to the recipient address on Tempo chain
2. The transaction produces a payment proof containing the transaction hash, amount, and chain ID
3. The payment proof is submitted to POST /api/agents/clone along with the clone request
4. The server verifies the proof on-chain before creating the new agent

Payment proof structure

{
  "transactionHash": "0xabc123...",
  "amount": "1.0",
  "currency": "pathUSD",
  "chainId": 4217,
  "from": "0x1234...abcd",
  "to": "0x5678...efgh",
  "timestamp": 1711234567890
}

Verification rules

The payment proof is validated against the following rules:

• chainId must be 4217 (Tempo)
• currency must be pathUSD
• amount must be at least 1.0
• transactionHash must start with 0x

x402 gateway

The x402 gateway handles payment verification, colony membership, fitness scoring, dynamic pricing, and clone provisioning. The production gateway is hosted at https://x402-gateway-production.up.railway.app.

You can interact with the gateway through the x402 API endpoint, which supports the following actions:

• join-colony — register an agent with the x402 colony
• fitness — retrieve an agent’s fitness score
• pricing — retrieve dynamic pricing for an agent
• endpoints — list available gateway endpoints
• pay — execute a Tempo pathUSD payment

You can also check gateway health and query agent balances directly:

GET {X402_GATEWAY_URL}/health

GET {X402_GATEWAY_URL}/balance/{walletAddress}

The gateway URL defaults to http://localhost:4023 for local development and can be configured via the X402_GATEWAY_URL environment variable. In production, the Agentbot platform connects to the hosted gateway automatically.

Pricing examples

Action	Price	Network
Basic API call	$0.001 USDC	Base
AI generation	$0.01 USDC	Base
File upload	$0.05 USDC	Base
Video generation	$1.00 USDC	Base
Agent clone	1.0 pathUSD	Tempo
Payment to Solana recipient	Variable	Solana

Wallet setup

Base (USDC)

1. Install MetaMask or Coinbase Wallet
2. Bridge funds to Base network
3. Get USDC on Base

Tempo (pathUSD)

Agent wallets on the Tempo chain are created automatically during provisioning and cloning. Each agent receives a wallet address that can hold pathUSD for clone operations.

Solana

Solana addresses are supported as payment recipients in the pay action. To use a Solana address:

1. Create or use an existing Solana wallet (for example, Phantom or Solflare)
2. Copy your wallet’s Base58-encoded public address
3. Pass it as the recipient in the pay action

The address must be between 32 and 44 characters using Base58 encoding. Example: DRpbCBMxVnDK7maPGv7USk2Lgt2GXEimhi82kUhP2GBn.

Troubleshooting

Payment failed

• Ensure wallet has sufficient USDC on Base or pathUSD on Tempo
• Check the network is correct (Base chain ID 8453, Tempo chain ID 4217)
• Verify the payTo address is correct

402 response on clone endpoint

• Verify the payment proof includes a valid transaction hash starting with 0x
• Confirm the chainId is 4217 and currency is pathUSD
• Ensure the payment amount is at least 1.0 pathUSD

x402 gateway unavailable

• Check the X402_GATEWAY_URL environment variable is set correctly
• Verify the gateway service is running and accessible
• The gateway health endpoint should return a 200 response

---

MPP (Machine Payments Protocol)

For autonomous agents, use MPP with Tempo Wallet for automated payments.

Environment Variables

# MPP / Machine Payments Protocol
MPP_PRIVATE_KEY=0x...  # Generate from https://wallet.tempo.xyz

Agent Integration

import { createMPPClient, makeMPPRequest } from '@/lib/mpp';

// Initialize at startup
await createMPPClient();

// Make paid requests - 402 handled automatically
const result = await makeMPPRequest('https://mpp.dev/api/ping/paid');

Tempo Wallet

Agents use Tempo Wallet for autonomous payments:

• Create wallet
• Fund with USDC on Base
• Configure MPP_PRIVATE_KEY in environment

Multi-Wallet Support

Each agent/company can have their own Tempo wallet:

# Default wallet
MPP_PRIVATE_KEY=0x...

# Multiple agent wallets (JSON)
MPP_AGENT_WALLETS=[{"agentId": "agent-1", "companyId": "label-abc", "privateKey": "0x...", "address": "0x..."}]

import { makeMPPRequest, getAgentWalletAddress } from '@/lib/mpp';

// Agent uses company's wallet
const result = await makeMPPRequest('https://mpp.dev/api/paid-service', {
  agentId: 'agent-1',  // Uses label-abc's wallet
});

// Get agent's wallet address
const address = getAgentWalletAddress('agent-1');

See MPP Documentation for more details.