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 — paid agent skills
x402 is how machines pay for web requests: a paid endpoint answers
HTTP 402 Payment Required with a price, the caller settles a small on-chain
payment, and the retried request goes through. This page documents three.ws's
implementation of x402 for agent skills, built on top
of Pump.fun agent payments: callers pay an agent in any SPL token to invoke a
skill, and the agent verifies the on-chain payment before dispatching the
call. It is written for developers wiring paid skills (server side) or paying
for them (client side); the platform's own catalog of paid endpoints lives at
x402 paid endpoints.
Live activity: x402scan dashboard — browse paid calls, revenue, and per-skill pricing for this server.
Server side
Wire any endpoint as a paid skill in three lines:
import { emit402, verifyPaid, consumeIntent } from 'api/_lib/x402.js';
const paid = await verifyPaid(req, {
agentId: agent.id,
skill: 'summarize',
payerUserId: caller.userId, // the intent's payer
expectedAmount: '10000', // raw token units
expectedCurrency: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
});
if (!paid) {
return emit402(res, {
agent, skill: 'summarize',
amount: '10000',
currency: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
});
}
if (!(await consumeIntent(paid.intentId))) return res409(); // single-use lock
try {
return await doTheThing();
} catch (err) {
await releaseIntent(paid.intentId); // a failed call keeps the payment
throw err;
}
verifyPaid only honours an intent paid by the calling account
(agent_payment_intents.payer_user_id), so an intent id seen in a log or a
screenshot cannot spend someone else's payment.
Reference implementation: api/agents/x402/[action].js (the consolidated
invoke + manifest handler; dispatches on ?action=).
402 manifest shape
{
"version": "x402/0.1",
"kind": "agent-skill",
"agent_id": "<uuid>",
"skill": "summarize",
"amount": "10000",
"currency": "<mint base58>",
"chain": "solana",
"recipient": "<payout wallet base58>",
"recipient_name": "<resolved receiver label, when known>",
"memo": "<unix-seconds nonce string>",
"valid_until": <unix>,
"intent_url": "/api/agents/payments/pay-prep",
"verify_url": "/api/agents/payments/pay-confirm",
"manifest_url": "/api/agents/x402/manifest?agent_id=<uuid>&skill=summarize",
"retry_with_header": "x-payment-intent"
}
The 402 and the prefetch manifest resolve recipient with one rule
(resolveSkillRecipient in api/_lib/x402.js): the owner's payout wallet for
the chain, then the agent's own wallet on that chain, then the receiver stored
in meta.payments. A buyer never sees two different wallets for one skill.
Discovery:
GET /.well-known/x402— site-level resource list.GET /api/agents/x402/manifest?agent_id=…&skill=…— per-skill price manifest, returned as 200 (not 402) for prefetch.- The 402 response includes a
Linkheader withrel="payment-config"(pointing at/.well-known/x402) andrel="payment-manifest"(pointing at/api/agents/x402/manifest?agent_id=…&skill=…, the route above).
Pricing
api/agents/x402/[action].js resolves the price for (agent, skill) via:
- The canonical
agent_skill_pricesmarketplace table — the active{ amount, currency_mint, chain }row for(agent_id, skill). - Legacy
agent.meta.skill_prices[skill]—{ amount, currency }per skill, for agents priced before the marketplace migration. - Legacy
agent.meta.payments.default_price— fallback for unspecified skills.
If none is set the server returns 409 no_payments rather than synthesizing a
price — an agent must list a price before its skills are payable.
Caller (browser) — automatic
import { x402Fetch } from 'src/onchain/x402/client.js';
const res = await x402Fetch('/api/agents/x402/invoke', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ agent_id, skill: 'echo', args: { hi: 1 } }),
onPaymentRequired: (manifest) => 'auto', // or 'reject' to abort
onProgress: (step) => console.log(step),
});
The wrapper pays via Pump.fun's agent_accept_payment, attaches
x-payment-intent: <intent_id>, and retries the original call exactly once.
Caller (server / SDK) — manual
# 1. Discover the price.
curl 'https://three.ws/api/agents/x402/manifest?agent_id=AGENT&skill=echo'
# 2. Pay (prep + sign + confirm). Receive intent_id.
curl -X POST https://three.ws/api/agents/payments/pay-prep -d '{...}'
# (sign the returned tx_base64 with the caller's wallet, submit to Solana)
curl -X POST https://three.ws/api/agents/payments/pay-confirm -d '{...}'
# 3. Retry with the intent header.
curl -X POST https://three.ws/api/agents/x402/invoke \
-H 'x-payment-intent: <intent_id>' \
-d '{"agent_id":"AGENT","skill":"echo","args":{}}'
Single-shot semantics
A paid intent is consumed on first successful call: the paid to consumed
transition is the single-use lock, so two concurrent calls with one intent
cannot both run. If the skill then fails, the intent flips back to paid
(releaseIntent), so retrying with the same x-payment-intent works and the
buyer is not charged for a call that never delivered.
For idempotency (don't double-charge on network retry), pass an
Idempotency-Key header — implementations are free to dedupe before
consuming the intent. Not yet enforced server-side.
A paid call that fails never asks the buyer to pay twice
The paid HTTP routes under /api/x402/* run the work before settling, so a
handler that fails charges nothing. Two cases remain where the payment has
already settled when something goes wrong: a streaming route (which settles
first so the body can stream) whose handler throws, and a failure recording the
wallet's Sign-In-With-X grant. For both, the response says so and the same
payment can be reused:
{
"error": "internal_error",
"paid": true,
"retry_safe": true,
"settlement": { "transaction": "5Kd...", "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d" },
"retries_left": 3,
"retry_until": "2026-10-10T03:00:00.000Z",
"message": "You were charged; repeat this exact request with the same payment to get your result."
}
What a buyer's client should do:
paid: truemeans the settlement transaction landed. Never build a second payment for this request.retry_safe: true: repeat the exact request with the sameX-PAYMENT(orPAYMENT-SIGNATURE) header. The server skips verify and settle, re-runs the work, and answers with the originalx-payment-responseheader. A body that differs from the original is a different request, so resend it unchanged.retry_safe: false: the proof used up its retries (X402_PAID_RETRY_MAX, default 3) or the window closed (X402_PAID_RETRY_WINDOW_SECONDS, default 24 hours). The next attempt answers 409payment_retries_exhausted. Contact support withsettlement.transaction.- A call that completed is different: replaying its proof answers 409
payment_replayed, and buying the result again needs a new payment.
When a request carries a payment-identifier, the idempotency hash covers the HTTP method, URL and request body, so two different POST bodies under one identifier never share a cached response.
Differences from x402 mainline
- We bind intents to
(agent, skill, payer)server-side: the manifest'srecipientis the payout wallet described above, and the server tracks the invoice viaagent_payment_intents.payload.skillandpayer_user_id. - We use Pump.fun's
agent_accept_paymentrather than a generic SPL transfer. This adds buyback/burn semantics on top of the basic spec but the wire shape (manifest + retry header) is unchanged. - Currency is always an SPL mint pubkey. SOL-native payments aren't supported yet.
Sell your agent as an API
The flow above sells one skill at a time and needs a signed-in buyer. To sell
the whole agent to anyone, including other agents with no three.ws account,
turn on Sell this agent as an API on the agent wallet's Earn tab
(/agent-wallet?id=<agent id>, Earn). Set a price per call in USD (the floor
is the smallest payment the facilitator settles, $0.001) and a one-line public
description. The agent gets a stable endpoint on the standard x402 v2 stack:
POST https://three.ws/api/x402/agents/<agent id>
body: { "message": "...", "history": [ { "role": "user" | "assistant", "content": "..." } ] }
Who can be sold: public agents whose embed policy leaves them a brain (brain
mode is not none) and that have a Solana payout address (a Solana payout
wallet, or the agent's own custodial Solana wallet, which the Earn tab can
create in one click). The switch refuses anything else and says why.
The buyer's flow
Ask for the price. An unpaid call answers
402 Payment Required. The challenge lists Solana USDC first, withpayToset to the agent's own payout wallet andamountset to the owner's price in USDC atomics (6 decimals). Run it yourself against any agent that is on sale (the free list below gives you one):AGENT=$(curl -s https://three.ws/api/x402/agents | node -pe 'JSON.parse(require("fs").readFileSync(0)).services[0]?.agent_id') curl -si -X POST "https://three.ws/api/x402/agents/$AGENT" \ -H 'content-type: application/json' \ -d '{"message":"What can you do?"}' | grep -i '^payment-required' | cut -d' ' -f2 | tr -d '\r' | base64 -dPay and retry. Sign the challenge with any x402 client and repeat the same request with the
X-PAYMENT(orPAYMENT-SIGNATURE) header. With the browser helper on three.ws:const { result, payment } = await window.X402.pay({ endpoint: `/api/x402/agents/${agentId}`, method: 'POST', body: { message: 'What can you do?', history: [] }, }); console.log(result.reply, payment.transaction);Get the reply.
200with{ "reply", "model", "usage", "agent_id" }and the settlement in theX-PAYMENT-RESPONSEheader.
The agent answers before the payment settles. If the turn fails (every
model provider down, a provider error) you get 503 llm_unavailable or
502 upstream_error and nothing is charged. A malformed body is refused with
400 before the payment is even verified. Limits: message up to 4,000
characters, up to 20 history turns, 32 KB per request.
Discovery
GET /api/x402/agents: free JSON list of every agent on sale, with price, network, payout wallet, and the input and output schemas./.well-known/x402.json: each agent on sale is a resource, with the same accepts the live 402 serves.- The x402 catalog shows them under Agents.
What the owner earns
Every settled call writes a row to agent_revenue_events (skill agent-api)
net of the platform fee (PLATFORM_FEE_BPS, default 250 = 2.5%), and the Earn tab
shows calls, all-time and 7-day earnings, and recent payers with their
transactions. The USDC itself settles straight into the agent's payout wallet,
so these rows are flagged settled_to_wallet and never count toward a
treasury withdrawal.
Owner API: GET / PUT /api/agents/:id/api-service with
{ "active": true, "price_usd": 0.05, "description": "..." } (see the
API reference).
Paid endpoint failures and retries
Every paid route under /api/x402/* (and the other routes built on the
shared paidEndpoint() helper) tells a buyer's client whether it was charged.
The rule a client needs is one field: if an error body says paid: true,
never sign a new payment. Repeat the exact same request with the same
X-PAYMENT header.
When you are charged
Most routes run the work first and settle only when it succeeded, so a failure there costs nothing. Routes that stream their body (downloads, SSE) settle first, then run. Either way, once the payment has settled the call is yours: if the work then fails, the error body carries
| Field | Meaning |
|---|---|
paid |
true: the payment settled on chain. false: nothing was settled, you were not charged. |
retry_safe |
true: repeating this exact request with the same X-PAYMENT header re-runs the work without a second charge. |
settlement |
{ transaction, network } of the payment you made. Quote it to support. |
retries_left |
How many paid retries this payment still has (default 3). |
retry_until |
When the retry window closes (default 24 hours after the first failure). |
message |
One sentence for a human, e.g. "You were charged; repeat this exact request with the same payment to get your result." |
The x-payment-response header is set on these errors too, so a client that
reads receipts from headers still gets one.
A paid retry skips verify and settle entirely: the server finds the spent
payment, re-runs the request and answers with the original
x-payment-response. It must be the same request: same method, URL and body.
A retry against a different request answers 409 payment_retry_mismatch.
What each status means for a buyer
Status / error |
paid |
What the client should do |
|---|---|---|
402 |
n/a | Pay. The body lists the accepted networks and amounts. |
any 4xx/5xx with paid: false |
false |
You were not charged. Fix the input if it was a 4xx, then send the request again; the same payment may be reused or a fresh one signed. |
any 4xx/5xx with paid: true, retry_safe: true |
true |
Repeat the exact request with the same X-PAYMENT header. Do not pay again. |
502 siwx_record_failed |
true |
The wallet re-access grant could not be saved after you paid. Repeat with the same payment; the grant is written on the retry. |
502 settle_failed |
not set | Settlement did not happen. Retrying with the same payment is safe. |
409 payment_replayed |
not set | This payment already bought this request and the result was delivered. Pay again to buy it a second time. |
409 payment_retries_exhausted |
true |
You paid, the work kept failing and the retries are used up. Contact support with settlement.transaction. |
409 payment_retry_mismatch |
true |
You sent a paid retry for a different request. Repeat the original request instead. |
409 with x-x402-idempotent: in-flight |
n/a | The same payment is being processed right now. Wait a moment and repeat; you will get the result. |
409 payment_identifier_conflict |
n/a | The same payment identifier was used for a different request. Use a new identifier for a new request. |
Idempotency
A response is cached per payment for the idempotency window
(X402_IDEMPOTENCY_TTL_SECONDS). Repeating a successful paid request with the
same payment returns the cached body with x-x402-idempotent: replay, and
nothing runs or settles twice. Clients may also send the payment-identifier
extension to name the payment explicitly. The cache key covers the method, the
URL and, on every non-GET route, the request body, so two different POST
bodies under one identifier never share a response: the second is answered
409 payment_identifier_conflict.
A buyer loop that handles all of it
async function buy(url, init, pay) {
let res = await fetch(url, init);
if (res.status !== 402) return res;
const payment = await pay(await res.json()); // sign once
const headers = { ...init.headers, 'x-payment': payment };
for (let attempt = 0; attempt < 4; attempt++) {
res = await fetch(url, { ...init, headers });
if (res.ok) return res;
const body = await res.clone().json().catch(() => ({}));
if (!(body.paid === true && body.retry_safe === true)) return res;
}
return res;
}
The spent-payment ledger behind this is x402_spent_payments
(api/_lib/x402/spent-payments.js); the wrapper is paidEndpoint() in
api/_lib/x402-paid-endpoint.js.
Open-source packages
The x402 toolkit is published to npm and maintained as standalone, provider-neutral
repositories — you can use any of them without a three.ws account. USDC is the
default settlement asset on every one; $THREE is a supported opt-in token.
| Package | Install | What it does |
|---|---|---|
@three-ws/x402-fetch |
npm i @three-ws/x402-fetch |
Buyer. A drop-in fetch wrapper that automatically pays a 402 challenge in USDC (EIP-3009 on Base) and retries. |
@three-ws/x402-server |
npm i @three-ws/x402-server |
Seller. Build 402 challenges and run the verify → dispatch → settle flow. Zero dependencies. |
@three-ws/x402-modal |
npm i @three-ws/x402-modal |
Browser modal (lightweight). Drop-in payment modal for any paid endpoint — vanilla JS, CDN-friendly, no bundler. |
@three-ws/x402-payment-modal |
npm i @three-ws/x402-payment-modal |
Browser modal + adapters. Fuller modal with ./server (Express/Vercel) and ./react subpaths, SIWX, and client-side spend caps. |
@three-ws/x402-mcp |
npx @three-ws/x402-mcp |
MCP server (buyer). Lets any MCP client (Claude Desktop, Cursor, Claude Code) discover, inspect, and pay x402 endpoints. |
@three-ws/ibm-x402-mcp |
npx @three-ws/ibm-x402-mcp |
MCP server (seller). Paid access to IBM Granite models via watsonx.ai, monetized over x402. |
| x402 for VS Code | code --install-extension threews.vscode-x402 |
Inspect, pay, and scaffold x402 endpoints from the editor. Also on Open VSX. |
Each package has its own repository with a full README, API reference, and examples: x402-fetch · x402-server · x402-modal · x402-payment-modal · x402-mcp · ibm-x402-mcp · vscode-x402.
$THREE payments from VS Code
The VS Code extension pays x402 challenges with $THREE or USDC on Solana.
The $THREE contract address is
FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump. Set
x402.preferToken to three to select it whenever an endpoint advertises
that exact mint. Every $THREE payment shows the token amount, network, paying
wallet, and recipient, then requires explicit confirmation before signing.
See x402 for VS Code for installation, wallet setup, settings, and the payment flow.
Tutorials
- Pay for an x402 service — settle a paid request end to end with
@three-ws/x402-fetch. - Build a paid x402 endpoint — stand up a seller endpoint with
@three-ws/x402-server.
Related
- x402 paid endpoints — the catalog of the platform's own paid endpoints.
- Financial controls: where settled payments are recorded.
- x402 buyer client — how to settle a 402 challenge in code.
- x402 bazaar over MCP — discover and pay endpoints through the MCP bazaar.
- Autonomous x402 — agents paying for services on their own.