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.
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, capsapi/_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
- x402 protocol, the underlying challenge/settle mechanics.
- x402 paid endpoints, what you can buy from us.
- Autonomous x402 loop, uses this client on a schedule.
- Pending settlement: the
settlement_pendingoutcome, what a buyer does with it, and how the books close afterwards. - Payment Sessions: the outbound side of the ledger, what your agents spent at OTHER x402 merchants through a session, verified against the chain itself.