> ## Documentation Index
> Fetch the complete documentation index at: https://conto.finance/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# x402 Payments

> Handle HTTP 402 micropayments through the x402 protocol

# x402 Protocol Payments

Conto integrates with the [x402 protocol](https://www.x402.org/) 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.

## How It Works

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

1. Agent sends a request to an x402-enabled API
2. API returns HTTP 402 with payment details (amount, recipient, facilitator)
3. Agent calls Conto to pre-authorize the payment against policies
4. If approved, agent signs the payment and retries the API call
5. Agent records the transaction in Conto for tracking

## Pre-Authorization

Before making an x402 payment, check it against your policies and budget limits:

```bash theme={null}
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": "x402_session_xyz",
    "facilitator": "0xFacilitatorAddress",
    "scheme": "exact"
  }'
```

Conto derives `serviceDomain` from `resourceUrl`, so you do not need to send it separately.

**Response (Approved):**

```json theme={null}
{
  "authorized": true,
  "wallet": {
    "id": "cmm5b0wal000l49h7ckrtb11p",
    "address": "0xAgentWallet",
    "chainId": "8453",
    "availableBalance": 500.0
  },
  "reasons": ["Within x402 service budget", "Service domain allowed"]
}
```

**Response (Denied):**

```json theme={null}
{
  "authorized": false,
  "error": "X402 pre-authorization denied",
  "code": "BUDGET_EXCEEDED",
  "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"
    }
  ]
}
```

## Recording Transactions

After the x402 payment is executed onchain, record it in Conto:

```bash theme={null}
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",
    "sessionId": "x402_session_xyz",
    "facilitator": "0xFacilitatorAddress",
    "scheme": "exact",
    "walletId": "cmm5b0wal000l49h7ckrtb11p",
    "chainId": "8453"
  }'
```

### Batch Recording

For high-frequency micropayments, batch multiple records:

```bash theme={null}
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",
    "sessionId": "x402_session_xyz",
    "batchItems": [
      { "amount": 0.01, "resourceUrl": "https://api.example.com/v1", "paymentId": "pay_1", "responseCode": 200 },
      { "amount": 0.02, "resourceUrl": "https://api.example.com/v2", "paymentId": "pay_2", "responseCode": 200 }
    ]
  }'
```

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:

```bash theme={null}
GET /api/sdk/x402/services
```

## Budget Tracking

Check remaining budget and burn rate:

```bash theme={null}
GET /api/sdk/x402/budget
```

Pass `?sessionId=...` when you want the burn-rate and remaining-budget view scoped to a specific
x402 session. Session spend is counted from recorded x402 transactions with the same `sessionId`,
so generic payments do not reduce the protocol session budget.

If an agent has an active approved budget request, `/pre-authorize` returns a `budgetRequest`
snapshot and `/record` decrements the remaining budget automatically.

## Unified Machine Spend View

If this agent also uses MPP or multiple paid services, use the shared machine-spend endpoints for a combined view:

```bash theme={null}
GET /api/sdk/service-spend/summary?protocol=x402
GET /api/sdk/service-spend/services?protocol=x402
```

See [Machine Spend](/sdk/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](/policies/advanced#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

<CardGroup cols={2}>
  <Card title="Advanced Policies" icon="shield" href="/policies/advanced">
    Configure x402-specific policy rules
  </Card>

  <Card title="Machine Spend" icon="chart-line" href="/sdk/machine-spend">
    View unified x402 and MPP service spend
  </Card>

  <Card title="Error Handling" icon="bug" href="/sdk/error-handling">
    Handle x402 authorization errors
  </Card>
</CardGroup>