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.

x402 endpoints enforce explicit API-key scopes. Pre-authorization requires payments:request, recording execution requires payments:execute, and budget or service analytics require analytics:read.

How It Works

Agent calls API  →  Gets 402 response  →  Conto pre-authorizes  →  Agent pays & retries

Agent sends a request to an x402-enabled API
API returns HTTP 402 with payment details (amount, recipient, facilitator)
Agent calls Conto to pre-authorize the payment against policies
If approved, agent signs the payment and retries the API call
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": "research-run-42"
  }'

Conto derives serviceDomain from resourceUrl, so you do not need to send it separately. Response (Approved):

{
  "authorized": true,
  "decision": "approved",
  "message": "Payment is approved.",
  "x402": {
    "serviceDomain": "api.example.com",
    "amount": 0.05
  }
}

Response (Denied):

{
  "authorized": false,
  "decision": "declined",
  "message": "Payment was declined by your controls.",
  "x402": {
    "serviceDomain": "api.example.com",
    "amount": 0.05
  }
}

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",
    "paymentId": "pay_01J...",
    "sessionId": "research-run-42"
  }'

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",
    "paymentId": "batch_01J...",
    "batchItems": [
      { "amount": 0.01, "resourceUrl": "https://api.example.com/v1", "paymentId": "pay_1" },
      { "amount": 0.02, "resourceUrl": "https://api.example.com/v2", "paymentId": "pay_2" }
    ]
  }'

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?sessionId=research-run-42

The response contains the authenticated agent’s aggregate daily, weekly, and monthly spend, effective limits, and usage trend. When sessionId is supplied, spend.session also reports the call count and amount recorded with that customer-defined ID.

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:

Alert	Trigger
Price Spike	API suddenly charging more than usual
High Frequency	Unusual burst of API calls
New Service	Agent paying an API for the first time
Budget Burn	Approaching per-service budget limit
Duplicate Payment	Same amount + endpoint in quick succession
Failed Streak	Repeated 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

Start

Products

Build

Guides

Reference

Changelog

x402 Payments

x402 Protocol Payments

How It Works

Pre-Authorization

Recording Transactions

Batch Recording

Querying Services

Budget Tracking

Unified Machine Spend View

x402 Policy Rules

Anomaly Detection

Next Steps

Advanced Policies

Machine Spend

Error Handling

​x402 Protocol Payments

​How It Works

​Pre-Authorization

​Recording Transactions

​Batch Recording

​Querying Services

​Budget Tracking

​Unified Machine Spend View

​x402 Policy Rules

​Anomaly Detection

​Next Steps

Advanced Policies

Machine Spend

Error Handling

x402 Protocol Payments

How It Works

Pre-Authorization

Recording Transactions

Batch Recording

Querying Services

Budget Tracking

Unified Machine Spend View

x402 Policy Rules

Anomaly Detection

Next Steps