Paying for APIs with x402
When your AI agent calls a paid API, the API returns HTTP402 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
| Step | Who | What happens |
|---|---|---|
| 1 | Agent | Calls an x402-enabled API |
| 2 | API | Returns 402 Payment Required with amount, recipient, facilitator |
| 3 | Agent | Sends payment details to Conto for policy check |
| 4 | Conto | Evaluates x402 policies, returns authorized or denied |
| 5 | Agent | If authorized, signs payment and retries the API call |
| 6 | Agent | Records the completed transaction in Conto for tracking |
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.Recommended Starter Policy
Add rules
Add these rules to cap per-request cost and total per-service spend:Rule 1: Cap per API call
No single x402 payment can exceed $0.50.Rule 2: Budget per service
Total spend per API service domain cannot exceed $50.
| Field | Value |
|---|---|
| Rule Type | X402_MAX_PER_REQUEST |
| Operator | LTE |
| Value | 0.50 |
| Action | ALLOW |
| Field | Value |
|---|---|
| Rule Type | X402_MAX_PER_SERVICE |
| Operator | LTE |
| Value | {"maxAmount": 50, "period": "DAILY"} |
| Action | ALLOW |
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 withPOST /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.
Step 3: Record the Transaction
After the x402 payment executes onchain, record it withPOST /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.
Step 4: Monitor Spending
Check how much your agent has spent and what’s remaining withGET /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: The TypeScript SDK currently exposes standard payment helpers. 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
Pre-authorize returns denied but I haven't set x402 policies
Pre-authorize returns denied but I haven't set x402 policies
Budget shows $0 remaining but I haven't spent that much
Budget shows $0 remaining but I haven't spent that much
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.
X402_ALLOWED_SERVICES blocks everything
X402_ALLOWED_SERVICES blocks everything
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-authorize is slow
Pre-authorize is slow
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