Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

6.3 KB
Raw Blame

x402 Buyer Client

To consume a paid x402 endpoint, ours or anyone's, a caller has to perform the "402 dance": probe the URL, read the payment challenge, sign and settle a payment, then retry with an X-PAYMENT header. three.ws ships a buyer client that wraps that whole sequence in one call, with spending-cap enforcement built in.

Source: api/_lib/x402-buyer-fetch.js, api/_lib/x402-buyer-axios.js, caps api/_lib/x402-spending-cap.js.


buyerFetch(url, opts)

import { buyerFetch } from '../_lib/x402-buyer-fetch.js';

const { ok, response, payment, settled } = await buyerFetch(
  'https://three.ws/api/x402/crypto-intel',
  {
    method: 'POST',
    body: { topic: 'sol' },          // serialized to JSON when an object
    caps: {
      address: 'MyAgentWalletPubkey',
      maxPerCall: '10000',           // $0.01  (USDC atomics, 6 decimals)
      maxPerHour: '1000000',         // $1.00 / hour
      maxPerDay:  '5000000',         // $5.00 / day
    },
    preferNetwork: 'solana',         // string, or fn(accepts) => requirement
    signPayment: ({ requirement }) => signSolanaPayment(kp, requirement),
  },
);

if (!ok) {
  // { ok:false, abort:true, reason } when a cap blocks the call,
  // or { ok:false, status, error } on a protocol error.
} else {
  const data = await response.json();  // the paid result
}

Options

Field Required Purpose
method, headers, body no Standard request shape; an object body is JSON-encoded.
caps recommended Spending-cap envelope: address plus maxPerCall / maxPerHour / maxPerDay in USDC atomics.
signPayment({ requirement }) yes Returns the signed payment payload for the chosen requirement.
preferNetwork no Pick which advertised network to pay on, a network string, or a function over the accepts array.
preferScheme no 'upto' takes an escrow-backed offer when one is advertised, so you pay the measured charge rather than the cap.
preferProtocol no 'mpp' pays an MPP Solana charge when the server offers one. By default an x402 accepts list wins.
dryRun no Stops after the cap check and returns the quote and every offer, signing and paying nothing.
fetchImpl no Inject a custom fetch (tests, proxies).

Why you supply signPayment

Signing differs per chain, EIP-712 transferWithAuthorization on Base, a signed VersionedTransaction on Solana, a contract call on BSC, so the caller owns it. The client owns only the cap check, the header dance, and settlement parsing. The callback receives the selected requirement from the 402 challenge and returns the payment payload to attach.

x402 or MPP from one call

A 402 can speak either protocol. When a server offers only an MPP WWW-Authenticate: Payment Solana charge (or you set preferProtocol: 'mpp'), buyerFetch expresses the charge as the equivalent exact requirement, so caps and signPayment see one shape. signPayment must return a Solana exact payload ({ payload: { transaction } }), which goes back as Authorization: Payment, and the receipt is read from Payment-Receipt. Results carry protocol: 'x402' | 'mpp'; a dryRun result is { ok: true, dryRun: true, protocol, quote, offers: { x402, mpp } }. See MPP on Solana.

Spending caps

Caps are enforced as a reserve → commit / rollback transaction in x402-spending-cap.js, so a call is counted before it fires and rolled back if it fails, caps hold even across concurrent calls. The store is Redis-backed when available. If a call would exceed any window, buyerFetch returns { ok: false, abort: true, reason } without paying. For an upto payment the cap is reserved up front, and once the settlement reports the measured charge the unused part of the reservation is released, so the hourly and daily windows reflect real spend (x402 upto). The platform-wide ceiling defaults live in env (X402_MAX_PER_CALL_ATOMIC, X402_MAX_PER_HOUR_ATOMIC, X402_MAX_PER_DAY_ATOMIC; see Configuration).

Axios variant

import { wrapAxiosWithPaidRequest } from '../_lib/x402-buyer-axios.js';

const client = wrapAxiosWithPaidRequest(axios.create());
const res = await client.requestPaid({ url, method: 'POST', data, caps, signPayment });

Same cap surface and signing contract as buyerFetch, exposed as an Axios instance method for callers already using Axios.

Receipts and builder codes

On settlement the response carries the receipt material the platform issues (X402_RECEIPT_SIGNING_KEY / OFFER_RECEIPT_*). If a challenge declares a builder-code extension, the client echoes it (and X402_BUILDER_CODE_WALLET when set) back into the payment so attribution survives the round trip.

When a settlement is still confirming

A settle has three outcomes, not two. Alongside success and failure, a transaction that has been broadcast but not yet confirmed answers settlement_pending, and it is not a failed payment: the correct response is to retry the settle once with the identical payload and idempotency key, which is what lets the facilitator reconcile against the transaction it already broadcast instead of sending a second one.

Our paid endpoints deliver the response either way and set status: "pending" plus the settlement signature in X-PAYMENT-RESPONSE, so a settled result with that status means the work is yours and the transfer is still confirming. Do not pay again: the authorization is single-use and already spent.

Full behavior on both sides of the wire, including what our own facilitator guarantees: Pending settlement.

Related