Order inference like an agent

1. Request a quote (expect 402)

   POST the request you actually want. Exactly one of prompt or messages[] is required; snake_case and camelCase keys are both accepted.

   POST /api/v1/inference
   Content-Type: application/json
   
   {
     "offerId": "offer_venice-llama-3_3-70b",
     "messages": [
       { "role": "user", "content": "Explain x402 in one sentence." }
     ],
     "maxOutputTokens": 512,
     "buyerAddress": "0xYourBuyerOrPayerAddress"
   }

2. Read the quote and envelope

   The 402 carries the quote in the body and a base64 PAYMENT-REQUIRED header. The X-DiemSum-Quote-Id and X-DiemSum-Request-Hash headers echo the quote so you can correlate without parsing the body.

   HTTP/1.1 402 Payment Required
   PAYMENT-REQUIRED: <base64 paymentRequirements>
   X-DiemSum-Quote-Id: quote_8f...
   X-DiemSum-Request-Hash: sha256:1c9a...
   
   {
     "error": "Payment required",
     "code": "payment_required",
     "quote": {
       "quoteId": "quote_8f...",
       "requestHash": "sha256:1c9a...",
       "quotedMaxUsd": 0.0123,
       "expiresAt": "2026-06-08T00:05:00.000Z"
     },
     "paymentRequirements": {
       "x402Version": 2,
       "accepts": [{
         "scheme": "exact",
         "network": "eip155:8453",
         "amount": "12345",
         "asset": "0x8335...2913",
         "payTo": "0xSeller...",
         "maxTimeoutSeconds": 300,
         "extra": { "assetTransferMethod": "erc7710", "quoteId": "quote_8f..." }
       }]
     }
   }

3. Sign the payment, then pay

   Build an x402 payload that satisfies accepts[0] exactly (same amount, asset, payTo, network), base64-encode it, and send it as PAYMENT-SIGNATURE on a re-send of the identical body. On a fee-aware v2 quote (off by default) payTo is the settlement router and amount is the gross (seller net + 0.5%): sign it with docs/examples/agent-fee-v2-purchase.ts instead.

   POST /api/v1/inference
   Content-Type: application/json
   PAYMENT-SIGNATURE: <base64 x402 payload>
   
   { ...the EXACT same body you quoted in step 1... }

4. Retrieve the completion

   A 200 returns the completion, a usage receipt, and a nextTurn lineage you keep for follow-ups.

   HTTP/1.1 200 OK
   
   {
     "quote": { "quoteId": "quote_8f...", "conversationId": "conv_...", "turnId": "turn_..." },
     "inferenceRequest": { "inferenceRequestId": "inf_...", "status": "completed" },
     "receipt": { "receiptId": "rcpt_...", "usage": { "promptTokens": 18, "completionTokens": 24 } },
     "completion": { "content": "x402 lets a server demand on-chain payment for a request..." },
     "nextTurn": {
       "conversationId": "conv_...",
       "parentInferenceRequestId": "inf_...",
       "parentReceiptId": "rcpt_..."
     }
   }

// One paid completion = two POSTs to the SAME endpoint with the SAME body.
const base = "https://diemsum.com";
const body = {
  offerId: "offer_venice-llama-3_3-70b",
  messages: [{ role: "user", content: "Explain x402 in one sentence." }],
  maxOutputTokens: 512,
  buyerAddress: "0xYourBuyerOrPayerAddress",
};

// 1) Quote — no payment header, so the server answers 402.
const quoteRes = await fetch(`${base}/api/v1/inference`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify(body),
});
if (quoteRes.status !== 402) throw new Error(`expected 402, got ${quoteRes.status}`);
const { paymentRequirements } = await quoteRes.json();

// 2) Sign an x402 payload that satisfies accepts[0] exactly (ERC-7710
//    delegation for agents; see docs/examples/direct-x402-erc7710.ts). The
//    delegation must cap the transfer at accepts[0].asset + amount, allow zero
//    native value, name the facilitator redeemers, expire no later than the
//    quote, and bind the transfer recipient to accepts[0].payTo (an
//    AllowedCalldata caveat at start index 4 with payTo padded to 32 bytes).
//    Fee-aware v2 quotes (paymentMode "fee-v2", off by default) answer with
//    payTo = the settlement router and amount = gross (net + 0.5%); never sign
//    them with this v1 delegation — see docs/examples/agent-fee-v2-purchase.ts.
const paymentSignature = await signX402(paymentRequirements.accepts[0]);

// 3) Pay — re-send the IDENTICAL body plus PAYMENT-SIGNATURE.
const payRes = await fetch(`${base}/api/v1/inference`, {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "payment-signature": paymentSignature,
  },
  body: JSON.stringify(body), // byte-for-byte identical or you get 400 quoted_request_mismatch
});
const result = await payRes.json();
console.log(result.completion.content);

The agent opens a request with its own delegate address and a recurring budget. DiemSum returns an approval URL the human opens in a browser; they connect MetaMask and grant an ERC-7715 erc20-token-periodic permission whose delegate is the agent's own address — not a browser session key. The agent polls until the grant lands, stores it locally, and redelegates it per quote for each purchase.

1. Request the mandate

   POST your delegate agentAddress and a periodAmountUsd (e.g. 100 per day). DiemSum returns a requestId and an approval URL like /permit/{requestId}.

2. Hand the URL to your human

   They open it, connect MetaMask, and grant the erc20-token-periodic permission. They verify in the MetaMask prompt that the delegate address matches your agent before signing — that verification is the security boundary. Granting needs the MetaMask desktop browser extension; MetaMask Mobile cannot grant ERC-7715 permissions yet, so on a phone the permit page offers a copy-the-link gate and only the decline path.

3. Poll, then store the grant

   GET the request until status is granted, then save the permission context locally (for example ~/.diemsum/permissions.json, chmod 600).

4. Redelegate per purchase

   For each inference, sign a child delegation from the stored root permission to the quoted facilitator redeemers with an exact-amount USDC caveat matching the quote, encode child plus root as the payment context, and send it as PAYMENT-SIGNATURE. A 100-USD-per-day root funds a 1-USD call 100 times a day with no new human approval.