Skip to main content

​
x402 Protocol Payments

Conto integrates with the x402 protocol to let AI agents pay for HTTP APIs that return 402 Payment Required. Conto acts as a policy layer between your agent and the x402 facilitator.

​
How It Works

Agent calls API  →  Gets 402 response  →  Conto pre-authorizes  →  Agent pays & retries
  1. Agent sends a request to an x402-enabled API
  2. API returns HTTP 402 with payment details (amount, recipient, facilitator)
  3. Agent calls Conto to pre-authorize the payment against policies
  4. If approved, agent signs the payment and retries the API call
  5. Agent records the transaction in Conto for tracking

​
Pre-Authorization

Before making an x402 payment, check it against your policies: 
curl -X POST https://conto.finance/api/sdk/x402/pre-authorize \
  -H "Authorization: Bearer $CONTO_SDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 0.05,
    "recipientAddress": "0xFacilitatorAddress",
    "resourceUrl": "https://api.example.com/data",
    "serviceDomain": "api.example.com",
    "facilitator": "0xFacilitatorAddress",
    "scheme": "exact"
  }'
Response (Approved): 
{
  "authorized": true,
  "wallet": {
    "id": "wal_123",
    "address": "0xAgentWallet",
    "chainId": "8453",
    "availableBalance": 500.00
  },
  "reasons": ["Within x402 service budget", "Service domain allowed"]
}
Response (Denied): 
{
  "authorized": false,
  "reasons": ["X402 price ceiling exceeded: $0.05 > $0.01 max"],
  "violations": [
    {
      "type": "X402_PRICE_CEILING",
      "limit": 0.01,
      "current": 0.05,
      "message": "Amount exceeds x402 price ceiling"
    }
  ]
}

​
Recording Transactions

After the x402 payment is executed on-chain, record it in Conto: 
curl -X POST https://conto.finance/api/sdk/x402/record \
  -H "Authorization: Bearer $CONTO_SDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 0.05,
    "recipientAddress": "0xFacilitatorAddress",
    "transactionHash": "0xabc123...",
    "resourceUrl": "https://api.example.com/data",
    "serviceDomain": "api.example.com",
    "facilitator": "0xFacilitatorAddress",
    "scheme": "exact",
    "walletId": "wal_123",
    "chainId": "8453"
  }'

​
Batch Recording

For high-frequency micropayments, batch multiple records: 
curl -X POST https://conto.finance/api/sdk/x402/record \
  -H "Authorization: Bearer $CONTO_SDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batch": [
      { "amount": 0.01, "recipientAddress": "0x...", "transactionHash": "0x1...", "resourceUrl": "https://api.example.com/v1", "serviceDomain": "api.example.com" },
      { "amount": 0.02, "recipientAddress": "0x...", "transactionHash": "0x2...", "resourceUrl": "https://api.example.com/v2", "serviceDomain": "api.example.com" }
    ]
  }'

​
Querying Services

View which x402 services your agent has used: 
GET /api/sdk/x402/services

​
Budget Tracking

Check remaining budget and burn rate: 
GET /api/sdk/x402/budget

​
x402 Policy Rules

Configure x402-specific policies to control micropayment behavior. See Advanced Policies for the full rule type reference. Key rule types:
  • X402_MAX_PER_REQUEST — Cap per individual request
  • X402_PRICE_CEILING — Hard price ceiling
  • X402_MAX_PER_SERVICE — Budget per service domain
  • X402_ALLOWED_SERVICES — Allowlist of service domains
  • X402_BLOCKED_SERVICES — Blocklist of service domains
  • X402_SESSION_BUDGET — Session-level budget cap

​
Anomaly Detection

Conto automatically monitors x402 spending patterns and creates alerts for:
  • Price spikes (sudden cost increases)
  • High-frequency calls (unusual request rates)
  • New services (first-time service usage)
  • Budget burn rate (approaching limits)
  • Duplicate payments
  • Failed streaks (repeated failures)

​
Next Steps

Advanced Policies

Configure x402-specific policy rules

Error Handling

Handle x402 authorization errors