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.

19.5 KB
Raw Blame

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 Link header with rel="payment-config" (pointing at /.well-known/x402) and rel="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:

  1. The canonical agent_skill_prices marketplace table — the active { amount, currency_mint, chain } row for (agent_id, skill).
  2. Legacy agent.meta.skill_prices[skill] — { amount, currency } per skill, for agents priced before the marketplace migration.
  3. 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: true means the settlement transaction landed. Never build a second payment for this request.
  • retry_safe: true: repeat the exact request with the same X-PAYMENT (or PAYMENT-SIGNATURE) header. The server skips verify and settle, re-runs the work, and answers with the original x-payment-response header. 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 409 payment_retries_exhausted. Contact support with settlement.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's recipient is the payout wallet described above, and the server tracks the invoice via agent_payment_intents.payload.skill and payer_user_id.
  • We use Pump.fun's agent_accept_payment rather 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

  1. Ask for the price. An unpaid call answers 402 Payment Required. The challenge lists Solana USDC first, with payTo set to the agent's own payout wallet and amount set 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 -d
    
  2. Pay and retry. Sign the challenge with any x402 client and repeat the same request with the X-PAYMENT (or PAYMENT-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);
    
  3. Get the reply. 200 with { "reply", "model", "usage", "agent_id" } and the settlement in the X-PAYMENT-RESPONSE header.

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

Related