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.
Payment Sessions
A Payment Session is a platform-managed spend envelope for agents. You fund a
budget from your prepaid credits, receive a bearer token, and hand that token
to an agent (or any script). The agent then calls paid x402 endpoints through
POST /api/pay/execute without ever holding a private key: the platform's
Solana wallet signs each payment, and a spend governor enforces your budget,
host allowlist, and per-transaction cap on every call. This is for developers
who want an agent to spend real money inside hard limits, with a full
execution ledger and an unspent-budget refund when the session ends.
The design principle: the agent does not hold a wallet. It proposes spend; governance enforces policy.
Base URL: https://three.ws
How the pieces fit
- Credits are your prepaid balance, denominated in USD. Top up by sending
SOL or $THREE to the platform deposit wallet, then verifying the transfer
with
POST /api/credits/deposit. - A session locks part of that balance into a budget envelope
(
POST /api/pay/session). Creation debits your credits up front and returns a one-time bearer token in the formpss_<session-id>_<random>. Only an HMAC-SHA256 hash of the token is stored; if you lose it, cancel the session and create a new one. - Executions spend the envelope. Each
POST /api/pay/executecall probes the target URL for its 402 challenge, runs the governance checks, reserves budget atomically, signs a Solana USDC transfer with the platform payer wallet, presents theX-PAYMENTheader, and records the result in the session's execution ledger. - Cancel or expire to get the rest back.
DELETE /api/pay/session/:idrefunds the unspent budget to your credits immediately; a scheduled sweep (/api/cron/payment-session-sweep, every 5 minutes) does the same for sessions that pass their expiry while still active.
The dashboard at /payments
Everything below is available in the browser at
three.ws/payments, which is the fastest way to
create a first session and watch it spend. The page lists every session you
own with its budget bar, remaining balance, expiry countdown, host allowlist
and per-transaction cap, and expanding a card loads that session's last ten
executions with a Solscan link per settled payment. Press N anywhere on the
page to open the create dialog.
Two things the dashboard does that the API does not do for you:
- The token is shown exactly once, right after creation, with a copy button
and a ready-made
PAYMENT_SESSION_TOKEN=line. Only its HMAC hash is stored, so there is no endpoint that can hand it back later. Copy it before closing. - Cancel and refund is one button per active session, and it tells you how much went back to your credits.
Using a session from an MCP client
Each session card carries a Copy MCP config button that emits the block
below for @three-ws/agentcore-payments-mcp,
which exposes the session tools to any MCP client:
{
"mcpServers": {
"three-ws-payments": {
"command": "npx",
"args": ["-y", "@three-ws/agentcore-payments-mcp"],
"env": {
"THREE_WS_SESSION": "${THREE_WS_SESSION}",
"PAYMENT_SESSION_TOKEN": "${PAYMENT_SESSION_TOKEN}"
}
}
}
}
The config references the two environment variables rather than inlining either secret, so the file itself never carries a credential. Export both before starting the server:
PAYMENT_SESSION_TOKEN: thepss_...token shown once when the session was created. Backs thepay_with_sessiontool when no inline token is passed.THREE_WS_SESSION: the value of your__Host-sidbrowser cookie, with no__Host-sid=name prefix. Only the session-management tools (create, list, cancel) need it; paying does not.
Authentication
The session-management and credits endpoints accept either credential:
- Browser session cookie (the normal three.ws login). These endpoints do not require a CSRF token.
Authorization: Bearer <token>with a three.ws API key (sk_live_.../sk_test_...) or an OAuth access token.
POST /api/pay/execute is different: it authenticates with the session
token itself (session_token in the JSON body). No cookie or API key is
needed, which is the point: the token is a time-bounded spending grant you can
hand to an untrusted agent process.
Rate limits: GET /api/credits shares the authenticated-read bucket
(300 requests per 5 minutes per IP). Everything else here shares the strict
auth bucket (50 requests per 10 minutes per IP) and returns 429 with a
Retry-After header when exceeded.
Prepaid credits
GET /api/credits
Your balance, recent ledger, where to deposit, and the fixed-price actions credits can buy.
curl -s https://three.ws/api/credits \
-H 'authorization: Bearer sk_live_...'
{
"balance_usd": 12.5,
"lifetime_deposited_usd": 20,
"lifetime_spent_usd": 7.5,
"deposit": {
"wallet": "<platform deposit address>",
"network": "mainnet",
"assets": [
{ "asset": "SOL", "label": "SOL", "mint": null, "decimals": 9, "native": true,
"rate": { "kind": "live_price", "source": "mainnet quote at verification" }, "bonus_bps": 0 },
{ "asset": "USDC", "label": "USDC", "mint": "<USDC mint for the network>", "decimals": 6, "native": false,
"rate": { "kind": "fixed", "usd_per_unit": 1, "source": "published rate" }, "bonus_bps": 0 },
{ "asset": "THREE", "label": "$THREE", "mint": "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump", "decimals": 6, "native": false,
"rate": { "kind": "live_price", "source": "mainnet quote at verification" }, "bonus_bps": 0 }
],
"accepts": ["SOL", "USDC", "THREE"],
"three_mint": "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump",
"three_symbol": "THREE",
"three_decimals": 6
},
"holder": {
"tier": { "level": 2, "id": "silver", "label": "Silver", "discount_bps": 1000 },
"usd_held": 140.0,
"discount_bps": 1000,
"next_tier": { "id": "gold", "label": "Gold", "min_usd": 500 },
"usd_to_next": 360.0
},
"buys": [ { "id": "...", "label": "...", "category": "...", "policy": "...", "usd": 0.05 } ],
"ledger": [ { "id": "...", "kind": "deposit", "amount_usd": 20, "...": "..." } ],
"next_cursor": null
}
deposit.assets is the live catalog of what the deposit wallet accepts and
how each asset is priced: SOL and $THREE at the mainnet quote when the
transfer is verified, USDC at the published fixed rate (one USDC is one
dollar of credits). bonus_bps is the extra credit granted for paying in
that asset, read from owner policy at request time (THREE_CREDIT_BONUS_BPS,
see inference-billing.md);
it is zero unless the owner has set one. The /credits
page renders its asset picker and rate list from this array. accepts,
three_mint, three_symbol and three_decimals are kept for older clients.
holder is the $THREE tier every debit on this account is already priced at:
the same shape GET /api/pricing returns. discount_bps
is the discount applied to each spend (1000 = 10% off), usd_held is the USD
value of the $THREE held by the linked wallet, and next_tier / usd_to_next
say how much more $THREE reaches the next rung (next_tier is null at the
top tier). Resolving it reads a Solana balance, so it degrades to null rather
than failing the balance read; treat null as "tier unknown", not "no
discount".
ledger is newest-first (25 entries here); each item carries id, kind
(deposit, refund, grant, adjust, or a spend), amount_usd,
balance_after, action, ref_type, ref_id, tx_signature, asset,
asset_amount, price_usd, and created_at.
POST /api/credits/deposit
Verify an on-chain transfer into the deposit wallet and credit your balance. Server-authoritative: the platform confirms the transaction on-chain, requires that a signer is a Solana wallet linked to your account, and computes the amount actually received from pre/post balances. Credits land only once the transaction is finalized.
curl -s https://three.ws/api/credits/deposit \
-H 'authorization: Bearer sk_live_...' \
-H 'content-type: application/json' \
-d '{ "asset": "SOL", "tx_signature": "<signature>", "network": "mainnet" }'
Body fields:
| Field | Type | Notes |
|---|---|---|
asset |
string | "SOL", "USDC" or "THREE", required |
tx_signature |
string | The Solana transaction signature, required |
network |
string | "mainnet" (default) or "devnet" |
Success:
{
"ok": true,
"replay": false,
"balance_usd": 32.5,
"credited_usd": 20,
"bonus_usd": 0,
"bonus_bps": 0,
"usd": 20,
"asset": "SOL",
"amount": 0.125,
"price_usd": 160,
"tx_signature": "<signature>"
}
If the transaction is confirmed but not yet finalized you get a retryable
{ "ok": false, "pending": true, "status": "awaiting_finalization", ... };
poll again in a few seconds. Crediting is idempotent per (signature, asset): a
replay returns "replay": true with credited_usd: 0 and bonus_usd: 0
instead of double-crediting.
A USDC deposit reads the deposit wallet's USDC token-account delta from the
finalized transaction (the network's USDC mint, 6 decimals) and credits it at
the fixed rate, so price_usd is 1 and usd equals amount. A $THREE
deposit also earns the configured bonus: bonus_usd is usd times
bonus_bps over ten thousand, granted as a separate grant ledger row
(action deposit.three_bonus, ref_type deposit_three_bonus) that replays
with the deposit and never counts toward lifetime_deposited_usd. With no
bonus configured both fields are zero.
Error codes: bad_request (400), wallet_not_linked (403, the transfer was
not signed by a wallet linked to your account), tx_failed, tx_not_found,
no_funds_received, amount_too_small (all 422), price_unavailable and
deposit_unavailable (503).
Creating a session
POST /api/pay/session
curl -s https://three.ws/api/pay/session \
-H 'authorization: Bearer sk_live_...' \
-H 'content-type: application/json' \
-d '{
"label": "research agent",
"budget_usd": 1.00,
"max_per_tx_usd": 0.01,
"allowed_hosts": ["three.ws"],
"blocked_hosts": ["untrusted.example.com"],
"approval_threshold_usd": 0.50,
"per_rail_daily_usd": { "solana": 5.00 },
"expiry_seconds": 86400
}'
Body fields:
| Field | Type | Notes |
|---|---|---|
budget_usd |
number | Required. Min $0.001, max $1000. Debited from credits immediately. |
label |
string | Optional, trimmed to 120 chars. |
max_per_tx_usd |
number | Optional per-payment ceiling, must be above $0.000001. null means no cap. |
allowed_hosts |
string[] | Optional, max 50 entries, deduplicated. Empty means any host. |
blocked_hosts |
string[] | Optional, max 50 entries, deduplicated. Checked after the allowlist, so an explicit block always wins over a broad allow, even on a session with no allowlist set. |
approval_threshold_usd |
number | Optional. A call priced above this amount gets a requires_approval verdict instead of settling. null means no threshold. |
per_rail_daily_usd |
object | Optional, keyed by network name ("solana", "base") or CAIP-2 id. A rolling 24h spend cap on that settlement rail, enforced with the same atomic reserve-then-roll-back pattern as the budget. |
agent_id |
string | Optional agent to associate with the session. |
network |
string | "solana" (default) or "base". Stored on the session; execution settles on Solana (see below). |
expiry_seconds |
number | Default 3600. Min 60, max 7776000 (90 days). |
metadata |
object | Arbitrary caller metadata, stored and echoed back. |
Response is 201 with the session object and the token, shown exactly
once:
{
"session": {
"id": "0b2f...",
"user_id": "...",
"agent_id": null,
"label": "research agent",
"budget_usd": 1,
"spent_usd": 0,
"remaining_usd": 1,
"max_per_tx_usd": 0.01,
"allowed_hosts": ["three.ws"],
"blocked_hosts": [],
"approval_threshold_usd": null,
"per_rail_daily_usd": {},
"network": "solana",
"status": "active",
"expires_at": "2026-07-31T00:00:00.000Z",
"metadata": {},
"created_at": "2026-07-30T00:00:00.000Z"
},
"token": "pss_0b2f..._4f8a...",
"note": "Store this token securely ..."
}
Errors: 402 insufficient_credits when your balance cannot cover
budget_usd (the message includes the required and available amounts), and
400 with invalid_budget, invalid_ttl, or bad_request for out-of-range
fields.
Session status is one of active, exhausted (budget fully spent),
cancelled, or expired.
Inspecting, listing, updating
GET /api/pay/session
Lists your sessions newest-first plus aggregate stats. Query parameters:
status (filter by status), limit (default 20, max 100), cursor (pass the
previous page's next_cursor, a created_at timestamp).
{
"items": [ { "id": "...", "status": "active", "...": "..." } ],
"next_cursor": null,
"stats": {
"sessions": { "active": 1, "exhausted": 0, "cancelled": 2, "expired": 0,
"total_budget_usd": 3, "total_spent_usd": 1.2 },
"executions": { "settled": 40, "failed": 2, "settled_usd": 1.2, "unique_endpoints": 3 }
}
}
GET /api/pay/session/:id
Returns { "session": { ... } } for a session you own, 404 not_found
otherwise.
GET /api/pay/session/:id/executions
The payment ledger for one session, newest-first, with limit (default 20,
max 100) and cursor pagination. Each item:
{
"id": "...",
"endpoint_url": "https://three.ws/api/x402/ping",
"endpoint_host": "three.ws",
"method": "GET",
"amount_usd": 0.001,
"network": "solana",
"tx_hash": "5Kd...",
"payer_address": "...",
"payee_address": "...",
"status": "settled",
"error_code": null,
"duration_ms": 1843,
"created_at": "2026-07-30T00:01:00.000Z"
}
status is settled or failed; failed rows carry an error_code (see the
execute error table below).
GET /api/x402/outbound-receipts
The account-wide view across every session: what your agents spent at other,
external x402 merchants, enriched with what the Solana chain itself says
settled, not just what the merchant's response claimed. This is the
counterpart to GET /api/x402/my-receipts (what three.ws
billed a wallet); this endpoint answers what your agents spent elsewhere. It
backs the Outbound tab on the Receipt Vault.
Authenticates with the account session cookie or a bearer token scoped
wallet:write (the same credential GET /api/pay/session/:id/executions
accepts). Query params: network (solana or base), host (filter by
merchant host), cursor, limit (default 20, max 100).
curl -s "https://three.ws/api/x402/outbound-receipts?network=solana&limit=20" \
-H 'authorization: Bearer sk_live_...'
{
"receipts": [
{
"id": "...",
"sessionId": "...",
"endpointUrl": "https://api.example.com/paid",
"endpointHost": "api.example.com",
"method": "GET",
"network": "solana",
"reportedAmountUsd": 0.05,
"txHash": "5Kd...",
"reportedPayer": "...",
"reportedPayee": "...",
"status": "settled",
"createdAt": "2026-10-15T00:01:00.000Z",
"resolved": {
"payer": "...", "payee": "...", "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"amountAtomics": "50000", "decimals": 6, "feeLamports": 5000, "slot": 123456, "blockTime": 1792048039
},
"resolveError": null,
"resolvePending": false
}
],
"nextCursor": null,
"summary": { "total": 1, "totalSpendUsd": 0.05, "verified": 1, "unverified": 0, "uniqueMerchants": 1 }
}
resolved is the first-party settlement record, read straight from the
transaction's own token-balance change (payer, payee, mint, amount, fee, slot,
time) the first time anyone views that row, then cached. It is Solana-only for
now; a Base-network execution carries resolved: null and shows its reported
fields. resolveError is set if that resolution failed permanently (a code
like tx_not_found); resolvePending is true while a Solana row has not been
resolved yet.
PATCH /api/pay/session/:id
Update the mutable fields of an active session: label, allowed_hosts,
max_per_tx_usd (pass null to remove the cap), blocked_hosts,
approval_threshold_usd (pass null to remove the threshold), and
per_rail_daily_usd (pass {} to remove the cap). Budget, network, and
expiry cannot be changed after creation.
curl -s -X PATCH https://three.ws/api/pay/session/<id> \
-H 'authorization: Bearer sk_live_...' \
-H 'content-type: application/json' \
-d '{ "allowed_hosts": ["three.ws", "api.example.com"] }'
Returns { "session": { ... } }. Errors: 400 nothing_to_update when no
recognized field is present, 404 not_found when the session is missing, not
yours, or no longer active.
DELETE /api/pay/session/:id
Cancels an active or exhausted session and refunds the unspent budget to
your credit balance. The refund is idempotent per session.
{ "cancelled": true, "session_id": "0b2f...", "refunded_usd": 0.85 }
404 not_found if the session does not exist, is not yours, or is already
cancelled or expired. Expired sessions are refunded automatically by the
sweep, so there is nothing left to cancel.
Spending a session
POST /api/pay/execute
Executes one x402 payment against any public https endpoint, using the session token as the only credential.
Body fields:
| Field | Type | Notes |
|---|---|---|
session_token |
string | Required. The pss_... token from session creation. |
url |
string | Required. Public https endpoint to call. Private and non-public addresses are rejected. |
method |
string | "GET" (default) or "POST". Anything else is treated as GET. |
body |
object or string | Optional JSON body, sent when method is POST. |
idempotency_key |
string | Optional but recommended. Recorded with the execution; the executions table is unique on it, so duplicate submissions of the same key collapse to a single recorded execution. |
What happens, in order:
- Token check. The token is verified against its stored hash.
- Probe. The endpoint is fetched (SSRF-guarded, 20 s timeout, redirects
not followed). If it answers with a success and no 402, the call was free:
you get the response back with
"paid": falseand the session is not touched. If it answers with an error status and no 402, there was nothing to pay and nothing succeeded, so you get502 endpoint_errorcarrying the realupstream_statusandupstream_body. The session is not touched either way. - Accept selection. From the 402 challenge's
accepts[], the platform picks a Solana USDC accept (the challenge must offer networksolana..., asset USDC, and afeePayerinextra). Sessions created withnetwork: "base"store that preference, but execute settles on Solana only; a challenge with no Solana option fails withno_solana_accept. - Governance. Checks run in order: session is active, not expired, host
is in the allowlist (exact hostname or a subdomain of an allowed host),
host is not in the denylist (checked even with no allowlist set), amount is
within
max_per_tx_usd, amount fits the rollingper_rail_daily_usdcap for the settlement network, remaining budget covers the amount, and amount is at or belowapproval_threshold_usd. The budget and rail-cap reservations are atomic SQL statements, so concurrent calls can never collectively overspend a session or a rail; when two racing calls both fit individually but not together, exactly one wins and the other getsinsufficient_budgetorrail_daily_exceeded. Every verdict (allow or reject) carries apolicy_digest(sha256 of the policy it was judged against) and an HMAC signature over the verdict, digest, request, and timestamp, stored with the execution: editing session policy after the fact changes the digest and breaks the signature on that old verdict. - Sign and pay. The platform Solana payer wallet signs a USDC transfer
matching the accept and re-requests the endpoint with the
X-PAYMENTheader. The service's fee payer covers the transaction fee; your budget is charged only the payment amount. - Record. The execution lands in the session ledger with the settlement
transaction hash (read from the endpoint's
x-payment-responseheader) and a Solscan explorer link. On a pre-settlement rejection (the endpoint answers 402 again), the reservation is rolled back and your budget is restored.
curl -s https://three.ws/api/pay/execute \
-H 'content-type: application/json' \
-d '{
"session_token": "pss_0b2f..._4f8a...",
"url": "https://three.ws/api/x402/rate-limit-probe",
"method": "POST",
"body": { "endpoint": "/api/x402/forge" },
"idempotency_key": "probe-2026-07-30-001"
}'
Success:
{
"ok": true,
"paid": true,
"result": { "remaining_calls": 412, "reset_at": "...", "cooldown_active": false },
"payment": {
"session_id": "0b2f...",
"amount_usd": 0.001,
"network": "solana",
"payer": "...",
"pay_to": "...",
"tx_hash": "5Kd...",
"explorer": "https://solscan.io/tx/5Kd..."
},
"session": { "id": "0b2f...", "spent_usd": 0.001, "remaining_usd": 0.999 },
"duration_ms": 1843
}
Free endpoint (no 402 challenge):
{ "ok": true, "paid": false, "note": "Endpoint served response without a 402 ...", "status": 200, "result": { "...": "..." } }
Execute error codes
| HTTP | Code | Meaning | Budget |
|---|---|---|---|
| 400 | missing_token, missing_url, invalid_url |
Request is malformed or the URL is not a public https endpoint. | untouched |
| 400 | blocked_url |
The target resolves to a private or unreachable address. | untouched |
| 401 | invalid_token |
Token is malformed, unknown, or does not match its stored hash. | untouched |
| 403 | session_inactive, session_expired |
Session is exhausted, cancelled, or past its expiry. | untouched |
| 403 | allowlist_blocked |
Target host is not in the session's allowlist. detail carries the host and the allowlist. |
untouched |
| 403 | host_blocked |
Target host is in the session's blocked_hosts denylist. detail carries the host. |
untouched |
| 403 | requires_approval |
The call's price exceeds approval_threshold_usd. detail carries amount_usd and threshold_usd. A human must approve the call before it can execute. |
untouched |
| 402 | per_tx_exceeded |
The endpoint's price exceeds max_per_tx_usd. detail carries amount_usd and cap_usd. |
untouched |
| 402 | rail_daily_exceeded |
The call would exceed the rolling 24h per_rail_daily_usd cap for the session's settlement network. detail carries the would-spend, spent-so-far, and cap amounts. |
untouched |
| 402 | insufficient_budget |
Remaining budget cannot cover the price. detail carries need_usd and remaining_usd. |
untouched |
| 402 | payment_rejected |
The service rejected the payment before settlement. | rolled back |
| 422 | no_solana_accept, unsupported_asset, missing_fee_payer |
The challenge offers no payable Solana USDC option. | untouched |
| 502 | endpoint_unreachable, invalid_challenge |
Could not reach the endpoint or parse its challenge. | untouched |
| 502 | endpoint_error |
The endpoint answered an error status with no payment challenge. Carries upstream_status and upstream_body. |
untouched |
| 502 | build_failed |
Building the Solana transaction failed. | rolled back |
| 502 | settle_uncertain |
Network failure after signing: chain state unknown. Do not retry immediately; check the session executions and wallet activity first. | kept reserved |
| 502 | upstream_error |
The endpoint returned a non-402 error after payment. Check wallet activity before retrying. | kept reserved |
| 503 | wallet_unconfigured |
The platform payer wallet is not configured. | rolled back |
The two "kept reserved" cases are deliberate: funds may have moved on-chain,
so the platform refuses to silently restore budget it cannot prove was
unspent. Both are recorded as failed executions with the matching
error_code.
Full walkthrough
BASE=https://three.ws
AUTH='authorization: Bearer sk_live_...'
# 0. Check your credit balance (top up first via POST /api/credits/deposit if empty)
curl -s $BASE/api/credits -H "$AUTH" | jq '{balance_usd, deposit}'
# 1. Create a $0.50 session, capped at $0.01 per call, three.ws only, 24 h
CREATE=$(curl -s $BASE/api/pay/session -H "$AUTH" -H 'content-type: application/json' -d '{
"label": "walkthrough",
"budget_usd": 0.50,
"max_per_tx_usd": 0.01,
"allowed_hosts": ["three.ws"],
"expiry_seconds": 86400
}')
TOKEN=$(echo "$CREATE" | jq -r .token)
SID=$(echo "$CREATE" | jq -r .session.id)
# 2. Spend it: pay a $0.001 x402 endpoint (no auth header needed, the token is the credential)
curl -s $BASE/api/pay/execute -H 'content-type: application/json' -d '{
"session_token": "'$TOKEN'",
"url": "'$BASE'/api/x402/rate-limit-probe",
"method": "POST",
"body": { "endpoint": "/api/x402/forge" },
"idempotency_key": "walkthrough-1"
}' | jq '{paid, payment, session}'
# 3. Inspect the session and its execution ledger
curl -s $BASE/api/pay/session/$SID -H "$AUTH" | jq .session
curl -s $BASE/api/pay/session/$SID/executions -H "$AUTH" | jq .items
# 4. Cancel and refund the unspent budget back to credits
curl -s -X DELETE $BASE/api/pay/session/$SID -H "$AUTH" | jq .
curl -s $BASE/api/credits -H "$AUTH" | jq .balance_usd
Related
- x402 Protocol: the challenge / verify / settle mechanics behind every paid call.
- x402 Buyer Client: paying x402 endpoints from your own wallet instead of a session.
- Receipt Vault: the Inbound/Outbound UI over
my-receiptsandoutbound-receipts. - x402 Developer Tools: free echo / debug / receipt-verification tools for debugging a paid call.