Skip to main content

Paying for APIs with x402

When your AI agent calls a paid API, the API returns HTTP 402 Payment Required with a payment challenge. The x402 protocol standardizes this flow. Conto sits in the middle to enforce policies before the agent pays. This guide is a walkthrough. For the endpoint reference (request/response shapes, scopes, error codes), see SDK > x402 payments.

Prerequisites

An active agent with an SDK key (Quickstart)
A funded wallet (Base USDC or Tempo USDC.e for production, or Tempo Testnet pathUSD for testing)
An x402-enabled API to call (or use the examples below to simulate)

How x402 Works

Conto never touches the x402 payment itself. It acts as the policy and tracking layer. Your agent (or wallet provider like Sponge) handles the actual signing and payment.

Step 1: Set Up x402 Policies

Before your agent starts paying for APIs, set guardrails. Without x402-specific policies, only your general spend limits apply.
1

Create the policy

Go to PoliciesCreate Policy.
2

Add rules

Add these rules to cap per-request cost and total per-service spend:Rule 1: Cap per API callNo single x402 payment can exceed $0.50.Rule 2: Budget per serviceTotal spend per API service domain cannot exceed $50.
3

Assign to agent

Go to the agent’s Permissions tab and assign the policy.
You can also add X402_ALLOWED_SERVICES with a JSON array value such as ["api.example.com", "data.provider.io"] to restrict which API domains your agent can pay. This is the strongest guardrail: the agent can only pay APIs you’ve explicitly approved.

Step 2: Pre-Authorize a Payment

When your agent receives an HTTP 402, extract the payment details (amount, recipient, facilitator) and check them against Conto with POST /api/sdk/x402/pre-authorize. Conto evaluates your x402 policies plus your general spend limits and responds one of two ways:
  • Authorized: the response includes the wallet to pay from. The agent signs the payment and retries the API call.
  • Denied: the response lists the violated rules. The agent should log the denial and either skip the API call or escalate.
See Pre-Authorization in the SDK reference for the full request and response shapes.

Step 3: Record the Transaction

After the x402 payment executes onchain, record it with POST /api/sdk/x402/record so it counts toward budgets and shows up in analytics. For high-frequency API calls, batch multiple records in one request. See Recording Transactions and Batch Recording for the request shapes.
If you skip recording, Conto can’t track budget consumption. Your per-service limits won’t enforce correctly because Conto doesn’t know the payment happened.

Step 4: Monitor Spending

Check how much your agent has spent and what’s remaining with GET /api/sdk/x402/budget, and list the x402 API services it has interacted with via GET /api/sdk/x402/services. See Budget Tracking and Querying Services for details, including session-scoped budget views.

Dashboard

Go to Analytics in the dashboard to see:
  • x402 spend trends over time
  • Per-service cost breakdown
  • Request frequency and average cost per call

Full Integration Example

Here’s how an agent handles the complete x402 flow in TypeScript: For x402 flows, call the SDK REST endpoints directly:

x402 Policy Reference

The complete list of x402 rule types, value formats, and operators lives in Advanced Policies > x402 Protocol Rules.

Anomaly Detection

Conto automatically monitors x402 patterns and creates alerts for price spikes, high-frequency bursts, new services, budget burn, duplicate payments, and failed streaks. See Anomaly Detection in the SDK reference for what triggers each alert and where to configure thresholds.

Troubleshooting

Your general spend limits still apply to x402 payments. If the x402 amount plus today’s spend exceeds your daily limit, it’s denied. Check your wallet-level and agent-level spend limits.
Ensure you’re recording transactions after they execute. If you skip the record step, Conto can’t decrement the budget correctly. Also check if batch records are being sent for high-frequency calls.
The allowlist is strict, only listed domains can receive x402 payments. Make sure you’ve added the exact domain (e.g., api.example.com, not example.com or www.api.example.com).
Pre-authorization is a policy check, not an onchain operation. If it’s slow, it’s likely network latency to the Conto API. Consider caching authorization results for repeated calls to the same endpoint within a short window.

Next Steps

MPP Sessions

Session-based micropayments for streaming APIs

x402 SDK Reference

Full API reference for x402 endpoints

Advanced Policies

All x402 policy rule types and value formats

Recipes

Copy-paste x402 recipes