Pay per request with x402.

Ask for a quote

curl -i https://api.usdf.fi/x402/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 64
  }'

Response, headers then body

402 Payment Required
payment-required: <base64 JSON of the "x402" object below>
www-authenticate: Payment id="…", realm="…", method="evm",
  intent="charge", request="…", expires="…"

{
  "type": "https://paymentauth.org/problems/payment-required",
  "title": "Payment Required",
  "status": 402,
  "detail": "payment required",
  "error": { "message": "payment required", "type": "payment_required", "code": "x402" },
  "quote": {
    "model": "<model>",
    "max_tokens": 64,
    "price_version": "<price sheet>",
    "amount": { "units": "<units>", "usd": "<usd>", "usdf": "<usdf>" },
    "asset": "<USDF address>",
    "accepted": [
      { "asset": "<USDF address>", "symbol": "USDF", "method": "permit2", "note": "…" },
      { "asset": "<USDG address>", "symbol": "USDG", "method": "eip3009", "note": "…" }
    ]
  },
  "x402": {
    "x402Version": 2,
    "resource": { "url": "…", "description": "…", "mimeType": "application/json" },
    "accepts": [
      {
        "scheme": "exact", "network": "eip155:<chain-id>", "amount": "<units>",
        "asset": "<USDF address>", "payTo": "<payTo>",
        "maxTimeoutSeconds": 300, "extra": { "assetTransferMethod": "permit2" }
      },
      {
        "scheme": "exact", "network": "eip155:<chain-id>", "amount": "<units>",
        "asset": "<USDG address>", "payTo": "<payTo>",
        "maxTimeoutSeconds": 300, "extra": { "name": "Global Dollar", "version": "1" }
      }
    ]
  }
}

{
  "x402Version": 2,
  "resource": <the resource from the 402>,
  "accepted": <the USDF accept, verbatim>,
  "payload": {
    "signature": "<signature>",
    "permit2Authorization": {
      "from": "<payer>",
      "permitted": { "token": "<USDF address>", "amount": "<units>" },
      "spender": "0x402085c248EeA27D92E8b30b2C58ed07f9E20001",
      "nonce": "<random uint256, decimal>",
      "deadline": "<unix seconds>",
      "witness": { "to": "<payTo>", "validAfter": "0" }
    }
  }
}

With the SDK

npm install @usdf/sdk viem

import { USDF } from "@usdf/sdk";
import { privateKeyToAccount } from "viem/accounts";
const wallet = privateKeyToAccount(process.env.PAYER_KEY as `0x${string}`);
const usdf = new USDF({ wallet }); // or new USDF({ apiKey: process.env.USDF_API_KEY })
const result = await usdf.run("<model>", "Hello");

Sign without the SDK

npm install @x402/core@2.27.0 @x402/evm@2.27.0 viem@2.56.8

import { x402Client } from "@x402/core/client";
import {
  decodePaymentRequiredHeader,
  decodePaymentResponseHeader,
  encodePaymentSignatureHeader,
} from "@x402/core/http";
import { createPermit2ApprovalTx, getPermit2AllowanceReadParams } from "@x402/evm";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { createPublicClient, createWalletClient, defineChain, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";

const url = "https://api.usdf.fi/x402/v1/chat/completions";
const body = JSON.stringify({
  model: "<model>",
  messages: [{ role: "user", content: "Hello" }],
  max_tokens: 256,
});
const headers = { "content-type": "application/json" };
const payer = privateKeyToAccount(process.env.PAYER_KEY as `0x${string}`);
const rhc = defineChain({
  id: <chain id>,
  name: "Robinhood Chain",
  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
  rpcUrls: { default: { http: ["<rpc url>"] } },
});

// Ask without paying: 402, with the accepted payments in the
// PAYMENT-REQUIRED header. The first is USDF through Permit2,
// the second USDG through EIP-3009.
const unpaid = await fetch(url, { method: "POST", headers, body });
const required = decodePaymentRequiredHeader(
  unpaid.headers.get("payment-required") ?? "",
);
const usdf = required.accepts[0];
const token = usdf.asset as `0x${string}`;

// Once per wallet: approve USDF to Permit2. This is the only
// transaction the payer ever sends.
const rpc = createPublicClient({ chain: rhc, transport: http() });
const allowance = await rpc.readContract(getPermit2AllowanceReadParams({
  tokenAddress: token,
  ownerAddress: payer.address,
}));
if (allowance < BigInt(usdf.amount)) {
  const approve = createPermit2ApprovalTx(token);
  await createWalletClient({ account: payer, chain: rhc, transport: http() })
    .sendTransaction({ to: approve.to, data: approve.data });
}

// Allow USDF on this network, then sign. Allowing the USDG accept
// instead (required.accepts[1]) pays by EIP-3009, with no approval.
const client = new x402Client().setSpendControls({
  allowedAssets: [{ network: usdf.network, asset: usdf.asset }],
});
registerExactEvmScheme(client, { signer: payer });
const payload = await client.createPaymentPayload(required);

// The same request with the signed permit. The gateway settles it
// onchain, then serves it.
const paid = await fetch(url, {
  method: "POST",
  headers: {
    ...headers,
    "payment-signature": encodePaymentSignatureHeader(payload),
  },
  body,
});
const result = await paid.json();
console.log(result.choices[0].message.content);
console.log(
  result.receipt.paid.usdf,
  result.receipt.payment.asset,
  "paid in",
  result.receipt.payment.tx,
);
console.log(decodePaymentResponseHeader(
  paid.headers.get("payment-response") ?? "",
));

Paid request

curl https://api.usdf.fi/x402/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: <encoded payment>" \
  -d '{
    "model": "<model>",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 64
  }'

Response, trimmed

payment-response: <base64 JSON: success, transaction, network, payer>
x-request-id: <request_id>

{
  "id": "<request_id>",
  "choices": [ … ],
  "receipt": {
    "request_id": "<request_id>",
    "paid": { "units": "<units>", "usd": "<usd>", "usdf": "<usdf>" },
    "usage_cost": { "units": "<units>", "usd": "<usd>", "usdf": "<usdf>" },
    "refund": { … },
    "payment": {
      "tx": "<transaction hash>", "explorer": "…", "payer": "<payer>",
      "amount": { "units": "<units>", "usd": "<usd>", "usdf": "<usdf>" },
      "asset": "USDF", "method": "permit2"
    },
    "settlement": { "scheme": "x402 exact", "network": "eip155:<chain-id>" },
    "data_policy": { … },
    "log": { "proof": "https://api.usdf.fi/v1/log/proof/<request_id>", "note": "…" }
  }
}

Pay with an MPP credential

npm install viem@2.56.8

import { getAddress, keccak256, stringToHex } from "viem";
import { privateKeyToAccount } from "viem/accounts";

const url = "https://api.usdf.fi/x402/v1/chat/completions";
const body = JSON.stringify({
  model: "<model>",
  messages: [{ role: "user", content: "Hello" }],
  max_tokens: 256,
});
const headers = { "content-type": "application/json" };
const payer = privateKeyToAccount(process.env.PAYER_KEY as `0x${string}`);
const fromB64 = (s: string) =>
  JSON.parse(Buffer.from(s, "base64url").toString("utf8"));

// Ask without paying: 402, with one Payment challenge per asset
// in WWW-Authenticate.
const unpaid = await fetch(url, { method: "POST", headers, body });
const challenges = [...(unpaid.headers.get("www-authenticate") ?? "")
  .matchAll(/Payment ((?:[a-z]+="(?:[^"\\]|\\.)*"(?:, )?)+)/g)].map((m) =>
  Object.fromEntries([...m[1].matchAll(/([a-z]+)="((?:[^"\\]|\\.)*)"/g)]
    .map((p) => [p[1], p[2].replace(/\\(.)/g, "$1")])),
);

// The USDG challenge: an EIP-3009 authorization whose nonce is
// keccak256(id || realm), valid until the challenge expires.
const c = challenges.find((x) =>
  fromB64(x.request).methodDetails.credentialTypes[0] === "authorization")!;
const request = fromB64(c.request);
const nonce = keccak256(stringToHex(c.id + c.realm));
const validBefore = BigInt(Math.floor(Date.parse(c.expires) / 1000));
const signature = await payer.signTypedData({
  domain: {
    name: "Global Dollar",
    version: "1",
    chainId: request.methodDetails.chainId,
    verifyingContract: getAddress(request.currency),
  },
  types: {
    TransferWithAuthorization: [
      { name: "from", type: "address" },
      { name: "to", type: "address" },
      { name: "value", type: "uint256" },
      { name: "validAfter", type: "uint256" },
      { name: "validBefore", type: "uint256" },
      { name: "nonce", type: "bytes32" },
    ],
  },
  primaryType: "TransferWithAuthorization",
  message: {
    from: payer.address,
    to: getAddress(request.recipient),
    value: BigInt(request.amount),
    validAfter: 0n,
    validBefore,
    nonce,
  },
});
const credential = {
  // The challenge as issued, every parameter (opaque included) unchanged.
  challenge: {
    id: c.id, realm: c.realm, method: c.method, intent: c.intent,
    request: c.request, expires: c.expires, opaque: c.opaque,
    ...(c.description ? { description: c.description } : {}),
  },
  payload: {
    type: "authorization", from: payer.address, to: request.recipient,
    value: request.amount, validAfter: "0",
    validBefore: validBefore.toString(), nonce, signature,
  },
  source: `did:pkh:eip155:${request.methodDetails.chainId}:${payer.address}`,
};

// The same request with the credential. The gateway settles it
// onchain, then serves it.
const paid = await fetch(url, {
  method: "POST",
  headers: {
    ...headers,
    authorization: `Payment ${Buffer.from(JSON.stringify(credential)).toString("base64url")}`,
  },
  body,
});
const result = await paid.json();
console.log(result.choices[0].message.content);
console.log(fromB64(paid.headers.get("payment-receipt") ?? ""));