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",
    "facilitator": "https://facilitator.example.com",
    "scheme": "exact",
    "paymentId": "pay_01J...",
    "payerAddress": "0x1111111111111111111111111111111111111111",
    "network": "eip155:8453"
  }'

Conto derives serviceDomain from resourceUrl, so you do not need to send it separately. Send the facilitator, scheme, payment ID, and session ID when they are available so matching policy controls evaluate the actual x402 challenge instead of missing context. Send payerAddress and network together. Use the exact signing address and the CAIP-2 network from the selected x402 requirement. This binds policy evaluation to the wallet that will pay. The binding is required when an agent has more than one active wallet. 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",
    "payerAddress": "0x1111111111111111111111111111111111111111",
    "network": "eip155:8453",
    "context": {
      "department": "engineering",
      "project": "research"
    }
  }'

txHash is required. Before recording spend, Conto verifies a successful settlement on the wallet’s configured chain with the exact sender, recipient, asset, and amount. A pending receipt returns SETTLEMENT_PENDING; a mismatched transfer returns SETTLEMENT_MISMATCH; and an unavailable RPC returns a temporary service error. Only verified settlements are stored as confirmed. Repeat the same payerAddress and network used for pre-authorization. Conto resolves the pair to one active wallet and uses that wallet for settlement verification and spend tracking.

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...",
    "payerAddress": "0x1111111111111111111111111111111111111111",
    "network": "eip155:8453",
    "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. The sum of all batchItems must equal the top-level settlement amount. Use optional context.department and context.project values during pre-authorization and recording to apply scoped budgets and persist those dimensions on the transaction.

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. Those periods use UTC calendar boundaries, include confirming transactions, and count each item in a recorded batch as one call. 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