Pay for APIs with x402

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

import { randomUUID } from 'node:crypto';
import { Conto } from '@conto_finance/sdk';

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

// Your own signer. On this path Conto checks the payment but never signs it.
declare const wallet: {
  getAddress(): Promise<string>;
  signX402Payment(input: { x402Version: 1 | 2; requirement: any }): Promise<string>; // base64
};

// x402 v1 network names in CAIP-2 form. v2 challenges already use CAIP-2.
const CAIP2: Record<string, string> = { base: 'eip155:8453', 'base-sepolia': 'eip155:84532' };
const toCaip2 = (network: string) => (network.includes(':') ? network : CAIP2[network]);
const decode = (value: string) => JSON.parse(Buffer.from(value, 'base64').toString('utf8'));

async function callPaidApi(url: string, sessionId: string) {
  // Step 1: Call the API
  const first = await fetch(url);
  if (first.status !== 402) return first.json();

  // Step 2: Read the payment requirements (v2 header, or v1 body)
  const requiredHeader = first.headers.get('PAYMENT-REQUIRED');
  const challenge = requiredHeader ? decode(requiredHeader) : await first.json();
  const x402Version: 1 | 2 = challenge.x402Version === 2 ? 2 : 1;
  const requirement = challenge.accepts[0]; // pick the entry your wallet can pay
  const baseUnits = requirement.amount ?? requirement.maxAmountRequired; // v2 ?? v1
  const amount = Number(baseUnits) / 1e6; // USDC uses 6 decimals
  const network = toCaip2(requirement.network);
  const payerAddress = await wallet.getAddress();
  const paymentId = randomUUID(); // persist it: a retry with the same ID returns the same grant

  // Step 3: Check the payment against your Conto policies
  const auth = await conto.x402.preAuthorize({
    amount,
    recipientAddress: requirement.payTo,
    resourceUrl: url,
    scheme: requirement.scheme,
    sessionId,
    paymentId,
    payerAddress,
    network,
  });
  if (!auth.authorized) {
    throw new Error(`${auth.decision}: ${auth.reasons?.join(' ') ?? auth.message}`);
  }

  // Step 4: Sign the payload and retry the API call
  const signed = await wallet.signX402Payment({ x402Version, requirement });
  const paid = await fetch(url, {
    headers: { [x402Version === 2 ? 'PAYMENT-SIGNATURE' : 'X-PAYMENT']: signed },
  });

  // Step 5: Record the settlement with the grant from Step 3
  const receiptHeader = paid.headers.get(
    x402Version === 2 ? 'PAYMENT-RESPONSE' : 'X-PAYMENT-RESPONSE'
  );
  if (!receiptHeader) throw new Error(`Payment not settled: HTTP ${paid.status}`);
  const settlement = decode(receiptHeader); // { success, transaction, network, payer }

  // record() is not retried automatically. On SETTLEMENT_PENDING, call it again later
  // with the same fields before auth.grantExpiresAt. A record after that is flagged as a bypass.
  await conto.x402.record({
    amount,
    recipientAddress: requirement.payTo,
    txHash: settlement.transaction,
    resourceUrl: url,
    paymentId,
    sessionId,
    payerAddress,
    network,
    grantId: auth.grantId,
    grantSignature: auth.grantSignature,
  });

  return paid.json();
}

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": "0xPayToAddress",
    "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"
  }'

{
  "authorized": true,
  "decision": "approved",
  "message": "Payment is approved.",
  "grantId": "cmm59z8fj000l49h7bjqza11p",
  "grantSignature": "pg1.3kq...",
  "grantExpiresAt": "2026-09-18T12:10:00.000Z",
  "x402": {
    "serviceDomain": "api.example.com",
    "amount": 0.05
  }
}

{
  "authorized": false,
  "decision": "declined",
  "message": "Payment was declined by your controls.",
  "reasons": ["This payment exceeds a configured spending limit."],
  "reasonCodes": ["SPENDING_LIMIT"],
  "x402": {
    "serviceDomain": "api.example.com",
    "amount": 0.05
  }
}

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": "0xPayToAddress",
    "txHash": "0xabc123...",
    "resourceUrl": "https://api.example.com/data",
    "paymentId": "pay_01J...",
    "sessionId": "research-run-42",
    "payerAddress": "0x1111111111111111111111111111111111111111",
    "network": "eip155:8453",
    "grantId": "cmm59z8fj000l49h7bjqza11p",
    "grantSignature": "pg1.3kq...",
    "context": {
      "department": "engineering",
      "project": "research"
    }
  }'

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": "0xPayToAddress",
    "txHash": "0xsettlement123...",
    "resourceUrl": "https://api.example.com/batch",
    "paymentId": "batch_01J...",
    "payerAddress": "0x1111111111111111111111111111111111111111",
    "network": "eip155:8453",
    "grantId": "cmm59z8fj000l49h7bjqza11p",
    "grantSignature": "pg1.3kq...",
    "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" }
    ]
  }'

curl -X POST https://conto.finance/api/sdk/x402/pay \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 0.05,
    "recipientAddress": "0xPayToAddress",
    "resourceUrl": "https://api.example.com/data",
    "paymentId": "pay_01J...",
    "paymentRequirements": {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "50000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0xPayToAddress",
      "maxTimeoutSeconds": 60,
      "extra": { "name": "USD Coin", "version": "2" }
    }
  }'

{
  "authorized": true,
  "decision": "approved",
  "message": "Payment is approved and signed.",
  "grantId": "cmm59z8fj000l49h7bjqza11p",
  "grantSignature": "pg1.3kq...",
  "grantExpiresAt": "2026-09-18T12:10:00.000Z",
  "paymentHeaderName": "X-PAYMENT",
  "xPaymentHeader": "eyJ4NDAyVmVyc2lvbiI6MS...",
  "authorization": {
    "from": "0x1111111111111111111111111111111111111111",
    "to": "0xPayToAddress",
    "value": "50000",
    "validAfter": "0",
    "validBefore": "1789733460",
    "nonce": "0x3f..."
  },
  "x402": { "serviceDomain": "api.example.com", "amount": 0.05 }
}

GET /api/sdk/x402/services?period=7d&limit=50

GET /api/sdk/x402/budget?sessionId=research-run-42