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 and budget limits: 
curl -X POST https://conto.finance/api/sdk/x402/pre-authorize \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 0.05,
    "recipientAddress": "0xFacilitatorAddress",
    "resourceUrl": "https://api.example.com/data",
    "sessionId": "x402_session_xyz",
    "facilitator": "0xFacilitatorAddress",
    "scheme": "exact"
  }'
Conto derives serviceDomain from resourceUrl, so you do not need to send it separately. Response (Approved): 
{
  "authorized": true,
  "wallet": {
    "id": "cmm5b0wal000l49h7ckrtb11p",
    "address": "0xAgentWallet",
    "chainId": "8453",
    "availableBalance": 500.0
  },
  "reasons": ["Within x402 service budget", "Service domain allowed"]
}
Response (Denied): 
{
  "authorized": false,
  "error": "X402 pre-authorization denied",
  "code": "BUDGET_EXCEEDED",
  "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 onchain, record it in Conto: 
curl -X POST https://conto.finance/api/sdk/x402/record \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 0.05,
    "recipientAddress": "0xFacilitatorAddress",
    "txHash": "0xabc123...",
    "resourceUrl": "https://api.example.com/data",
    "sessionId": "x402_session_xyz",
    "facilitator": "0xFacilitatorAddress",
    "scheme": "exact",
    "walletId": "cmm5b0wal000l49h7ckrtb11p",
    "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_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 0.03,
    "recipientAddress": "0xFacilitatorAddress",
    "txHash": "0xsettlement123...",
    "resourceUrl": "https://api.example.com/batch",
    "sessionId": "x402_session_xyz",
    "batchItems": [
      { "amount": 0.01, "resourceUrl": "https://api.example.com/v1", "paymentId": "pay_1", "responseCode": 200 },
      { "amount": 0.02, "resourceUrl": "https://api.example.com/v2", "paymentId": "pay_2", "responseCode": 200 }
    ]
  }'
Use the flat top-level settlement fields shown above. For multiple micropayments, put the per-call details in batchItems; the record endpoint does not accept a top-level payments array.

​
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
Pass ?sessionId=... when you want the burn-rate and remaining-budget view scoped to a specific x402 session. Session spend is counted from recorded x402 transactions with the same sessionId, so generic payments do not reduce the protocol session budget. If an agent has an active approved budget request, /pre-authorize returns a budgetRequest snapshot and /record decrements the remaining budget automatically.

​
Unified Machine Spend View

If this agent also uses MPP or multiple paid services, use the shared machine-spend endpoints for a combined view: 
GET /api/sdk/service-spend/summary?protocol=x402
GET /api/sdk/service-spend/services?protocol=x402
See Machine Spend for the combined x402 + MPP analytics view.

​
x402 Policy Rules

Configure x402-specific policies to control micropayment behavior. The complete list of x402 rule types, value formats, and operators lives in Advanced Policies > x402 Protocol Rules.

​
Anomaly Detection

Conto automatically monitors x402 spending patterns and creates alerts for:
AlertTrigger
Price SpikeAPI suddenly charging more than usual
High FrequencyUnusual burst of API calls
New ServiceAgent paying an API for the first time
Budget BurnApproaching per-service budget limit
Duplicate PaymentSame amount + endpoint in quick succession
Failed StreakRepeated authorization failures
Configure alert thresholds in Alerts in the dashboard.

​
Next Steps

Advanced Policies

Configure x402-specific policy rules

Machine Spend

View unified x402 and MPP service spend

Error Handling

Handle x402 authorization errors