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 — and Conto sits in the middle to enforce policies before the agent pays. This guide walks through the complete cycle: receive a 402, check it with Conto, pay, and track spending.

Prerequisites

How x402 Works

Agent calls API  →  HTTP 402  →  Conto pre-authorizes  →  Agent pays & retries  →  Conto records

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

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.

Recommended Starter Policy

Create the policy

Go to Policies → New Policy.

Field	Value
Name	x402 API Guardrails
Policy Type	X402_CONTROLS

Add rules

Add these rules to cap per-request cost and total per-service spend:Rule 1: Cap per API call

Field	Value
Rule Type	X402_MAX_PER_REQUEST
Operator	LTE
Value	0.50
Action	ALLOW

No single x402 payment can exceed $0.50.Rule 2: Budget per service

Field	Value
Rule Type	X402_MAX_PER_SERVICE
Operator	LTE
Value	50
Action	ALLOW

Total spend per API service domain cannot exceed $50.

Assign to agent

Go to the agent’s Permissions tab and assign the policy.

You can also add X402_ALLOWED_SERVICES 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 and check them against Conto:

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",
    "serviceDomain": "api.example.com",
    "facilitator": "0xFacilitatorAddress",
    "scheme": "exact"
  }'

If Authorized

{
  "authorized": true,
  "wallet": {
    "id": "wal_123",
    "address": "0xAgentWallet",
    "chainId": "8453",
    "availableBalance": 500.00
  },
  "reasons": ["Within x402 service budget", "Service domain allowed"]
}

The agent proceeds to sign the payment and retry the API call.

If Denied

{
  "authorized": false,
  "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"
    }
  ]
}

The agent should log the denial and either skip the API call or escalate.

Step 3: Record the Transaction

After the x402 payment executes on-chain, record it in Conto so it counts toward budgets and shows up in analytics:

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",
    "transactionHash": "0xabc123...",
    "resourceUrl": "https://api.example.com/data",
    "serviceDomain": "api.example.com",
    "facilitator": "0xFacilitatorAddress",
    "scheme": "exact",
    "walletId": "wal_123",
    "chainId": "8453"
  }'

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.

Batch Recording

For high-frequency API calls, batch multiple records in one request:

curl -X POST https://conto.finance/api/sdk/x402/record \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batch": [
      {
        "amount": 0.01,
        "recipientAddress": "0xFacilitator",
        "transactionHash": "0x1...",
        "resourceUrl": "https://api.example.com/v1/data",
        "serviceDomain": "api.example.com"
      },
      {
        "amount": 0.02,
        "recipientAddress": "0xFacilitator",
        "transactionHash": "0x2...",
        "resourceUrl": "https://api.example.com/v1/search",
        "serviceDomain": "api.example.com"
      }
    ]
  }'

Step 4: Monitor Spending

Check Budget

See how much your agent has spent and what’s remaining:

curl https://conto.finance/api/sdk/x402/budget \
  -H "Authorization: Bearer $CONTO_API_KEY"

View Services Used

List all x402 API services your agent has interacted with:

curl https://conto.finance/api/sdk/x402/services \
  -H "Authorization: Bearer $CONTO_API_KEY"

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:

import { Conto } from '@conto/sdk';

const conto = new Conto({ apiKey: process.env.CONTO_API_KEY });

async function callPaidApi(url: string) {
  // Step 1: Call the API
  const response = await fetch(url);

  if (response.status !== 402) {
    return response.json(); // No payment needed
  }

  // Step 2: Parse the 402 payment challenge
  const paymentHeader = response.headers.get('X-Payment');
  const { amount, recipient, facilitator } = JSON.parse(paymentHeader);
  const serviceDomain = new URL(url).hostname;

  // Step 3: Pre-authorize through Conto
  const auth = await conto.x402.preAuthorize({
    amount,
    recipientAddress: recipient,
    resourceUrl: url,
    serviceDomain,
    facilitator,
    scheme: 'exact',
  });

  if (!auth.authorized) {
    console.error('Policy denied x402 payment:', auth.reasons);
    throw new Error(`x402 denied: ${auth.reasons.join(', ')}`);
  }

  // Step 4: Sign and pay (via your wallet provider)
  const { txHash } = await walletProvider.signX402Payment({
    amount,
    recipient,
    facilitator,
  });

  // Step 5: Retry the API call with payment proof
  const paidResponse = await fetch(url, {
    headers: { 'X-Payment-Signature': txHash },
  });

  // Step 6: Record in Conto
  await conto.x402.record({
    amount,
    recipientAddress: recipient,
    transactionHash: txHash,
    resourceUrl: url,
    serviceDomain,
    facilitator,
    scheme: 'exact',
    walletId: auth.wallet.id,
    chainId: auth.wallet.chainId,
  });

  return paidResponse.json();
}

x402 Policy Reference

All available x402-specific policy rules:

Rule Type	What It Controls
`X402_MAX_PER_REQUEST`	Max amount per single API call
`X402_PRICE_CEILING`	Hard ceiling on any x402 payment
`X402_MAX_PER_ENDPOINT`	Budget per specific API endpoint
`X402_MAX_PER_SERVICE`	Budget per service domain
`X402_ALLOWED_SERVICES`	Allowlist of API domains
`X402_BLOCKED_SERVICES`	Blocklist of API domains
`X402_ALLOWED_FACILITATORS`	Allowed facilitator addresses
`X402_VELOCITY_PER_ENDPOINT`	Rate limit per endpoint
`X402_SESSION_BUDGET`	Session-level spending cap

See Advanced Policies for value formats and operators.

Anomaly Detection

Conto automatically monitors x402 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.

Troubleshooting

Pre-authorize returns denied but I haven't set x402 policies

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.

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

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-authorization is a policy check, not an on-chain 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

Get Started

Quick Start

CLI

SDK

MCP Server

Policies

Integrations

Guides

Paying for APIs with x402

Paying for APIs with x402

Prerequisites

How x402 Works

Step 1: Set Up x402 Policies

Recommended Starter Policy

Step 2: Pre-Authorize a Payment

If Authorized

If Denied

Step 3: Record the Transaction

Batch Recording

Step 4: Monitor Spending

Check Budget

View Services Used

Dashboard

Full Integration Example

x402 Policy Reference

Anomaly Detection

Troubleshooting

Next Steps

MPP Sessions

x402 SDK Reference

Advanced Policies

Recipes

Get Started

Quick Start

CLI

SDK

MCP Server

Policies

Integrations

Guides

​Paying for APIs with x402

​Prerequisites

​How x402 Works

​Step 1: Set Up x402 Policies

​Recommended Starter Policy

​Step 2: Pre-Authorize a Payment

​If Authorized

​If Denied

​Step 3: Record the Transaction

​Batch Recording

​Step 4: Monitor Spending

​Check Budget

​View Services Used

​Dashboard

​Full Integration Example

​x402 Policy Reference

​Anomaly Detection

​Troubleshooting

​Next Steps

MPP Sessions

x402 SDK Reference

Advanced Policies

Recipes

Paying for APIs with x402

Prerequisites

How x402 Works

Step 1: Set Up x402 Policies

Recommended Starter Policy

Step 2: Pre-Authorize a Payment

If Authorized

If Denied

Step 3: Record the Transaction

Batch Recording

Step 4: Monitor Spending

Check Budget

View Services Used

Dashboard

Full Integration Example

x402 Policy Reference

Anomaly Detection

Troubleshooting

Next Steps