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.
Autonomous x402 Loop
The autonomous x402 loop is the engine that makes three.ws an active participant in the x402 agent-to-agent economy rather than just a passive facilitator. On a schedule it pays — with real USDC over x402 — to call our own paid endpoints (and a bounded set of external, bazaar-discovered services), turning the results into market intel, health checks, and analytics the rest of the platform consumes.
This is the system that already does "an agent buys polling information": the loop's seeder wallet pays per call for crypto/token intel and feeds the result to the sniper oracle gate.
Source:
api/cron/x402-autonomous-loop.js, registryapi/_lib/x402/autonomous-registry.js, pipelines underapi/_lib/x402/pipelines/.
How a tick works
The loop runs from the x402-autonomous-loop cron endpoint, invoked every
minute by the economy-tick dispatcher (see the
economy heartbeat) rather than by its own schedule
entry; per-entry Redis cooldowns decide what actually fires on any given tick.
Each tick:
- Selects up to
X402_AUTONOMOUS_MAX_PER_TICKready registry entries — those whose Redis cooldown has elapsed — sorted by priority descending. - For each entry, probes the endpoint for a
402challenge, builds a Solana USDC payment, and fires the request with anX-PAYMENTheader. - If the paid replay itself answers
402, re-fetches the challenge once and settles against the fresh requirements before giving up. A 402 on the replay means the endpoint refused the proof (a re-quote between probe and replay, or re-issued requirements), and the signed transfer is never broadcast in that case, so no money moved and one retry is safe. The retry is bounded at one attempt, re-applies the spend cap and the recipient allowlist to the new quote, and is reported asretriedAfter402by the buyer client. - Records every call (success and failure) to
x402_autonomous_log. - For
oracle/sniperpipeline entries, extracts signal data and upserts it intooracle_intel_signalsfor the sniper oracle gate to consume. - Enforces a daily USDC spend cap across all calls in the loop.
Payments are real on chain — no mocks, no simulations.
Two per-tick balance reads act as hard pause switches in front of every paid
call, because neither cap above can see them: the payer's USDC float (an
empty float skips paid entries instead of signing payments that die at settle
with "Simulation failed") and the sponsor fee wallet's SOL settle floor
(below X402_SPONSOR_SOL_FLOOR_LAMPORTS the self-facilitator fail-closes every
sponsor-mode settle, so the loop skips paid entries rather than hammering
hundreds of doomed 502s per hour). Both fire one deduped CRITICAL ops alert
naming the wallet; free endpoints and run()-style monitors keep running while
paused, and api/cron/treasury-topup refuels the wallets when the economy
master holds funds.
Configuration
| Env var | Default | Purpose |
|---|---|---|
X402_SEED_SOLANA_SECRET_BASE58 |
(preferred) | The seeder keypair that pays for calls. |
X402_AGENT_SOLANA_SECRET_BASE58 |
(fallback) | Used if the seeder secret is absent. |
X402_AUTONOMOUS_ENABLED |
enabled | Set to false to pause without removing entries. |
X402_AUTONOMOUS_MAX_PER_TICK |
12 |
Max calls per cron tick. Raised from the original demo curve (8) to serve more of the ready backlog each tick; per-endpoint cooldowns still gate how often any one endpoint is hit. |
X402_AUTONOMOUS_DAILY_CAP_ATOMIC |
15000000 ($15) |
Daily USDC cap across the whole loop, in 6-decimal atomics. Raised from $5 so the higher per-tick throughput isn't money-starved mid-day; still a hard, env-tunable ceiling enforced per tick. |
X402_VOLUME_BATCH_PER_RUN |
6 |
Volume Bootstrap Loop: endpoints swept per run (cursor advances by this). Default sized so a default-cadence hour covers the full autobuy rotation — trailing-30-day settle activity is what keeps endpoints ranked on the x402 discovery surfaces. |
X402_VOLUME_PER_RUN_CAP_ATOMIC |
1100000 ($1.10) |
Volume Bootstrap Loop: self-imposed per-run cap, on top of the daily cap, so one tick can't drain the day. Floor set by RING_SETTLE_DEFAULT_PRICE_ATOMICS ($1.00): drop below it and the config validator raises ring_price_exceeds_run_cap and the ring skips ring-settle every tick. Source of truth: api/_lib/x402/ring-constants.js. |
X402_DATAPOINT_SWEEP_BATCH |
6 |
Datapoint Fabric Volume Sweep: distinct datapoint URLs settled per run (cursor advances by this over the ~5k-URL live pool). |
X402_DATAPOINT_SWEEP_CAP_ATOMIC |
50000 ($0.05) |
Datapoint Fabric Volume Sweep: self-imposed per-run cap, on top of the shared daily cap. |
CRON_SECRET |
(required) | Shared secret authorizing cron invocations (Cloud Scheduler). |
X402_ASSET_MINT_SOLANA |
USDC mint | The asset paid with (Solana USDC). |
SOLANA_RPC_URL |
— | RPC used to build and submit the payment. |
This loop's treasury is separate from the circulation engine
treasury (CIRCULATION_TREASURY_SECRET). Circulation funds agent-to-agent SOL /
$THREE activity; this loop funds USDC intel purchases. They do not fund each
other.
The seeder wallet is the same keypair the ring economy calls the
x402-ring-payer signer role, and it refills its own USDC: the
economy-rebalance cron (every 30 minutes) swaps a capped slice of the wallet's
own SOL into USDC whenever its USDC float drops below a floor (default $10,
ECONOMY_REBALANCE_RING_USDC_FLOOR). The rebalancer is inert (dry-run plan
only) unless ECONOMY_REBALANCE_ENABLED=1, and every swap is reserve-,
per-swap-, per-run- and slippage-capped.
The registry
Every scheduled call is a registry entry in autonomous-registry.js. An entry
declares:
| Field | Purpose |
|---|---|
id |
Unique key; also the Redis cooldown key. |
name |
Human label for logs and analytics. |
path |
URL path (self-call) or full URL (external bazaar service). |
method, body |
Request shape; body may be a function of the run context. |
cooldown_s |
Minimum seconds between calls. |
priority |
1–100; higher wins when several entries are ready. |
pipeline |
Tag grouping related entries. In production today: health, oracle, volume, self, finance, discovery, sniper, agents, security, reconciliation, datapoint, qa, forge, external, circuit-breaker, and a few singletons (reliability, observability, feed, commerce, canonicalize). |
enabled |
Set false to pause an entry. |
extractSignal |
Optional: maps the response into signal_data (for oracle entries, { mint?, signal, confidence, headline }). |
resolveTarget |
Optional: computes the request path dynamically per call (for entries that rotate over a set of resources). |
storeValue |
Optional: persists the extracted value to a dedicated table; wrapped in try/catch so a DB failure never crashes the tick. |
run |
Optional: owns a full multi-call sequence (its own payments, recording, extraction) and returns one summary row. |
Pipelines
The registry groups entries into pipelines. The main ones in production:
oracle— pays for our owncrypto-intel(SOL / BTC / ETH / $THREE / pump),token-intel, USDC peg monitoring, pump volume/whale anomaly scans, fact-checks, bazaar price trends and new-listing scans, and skill-marketplace price distribution. Results upsert intooracle_intel_signals.sniper— token-intel pre-snipe gate and sniper intel enrichment that feed the sniper's entry decisions.discovery/external— bazaar discovery warmup and catalog refresh that sweep external x402 service categories so the platform's directory stays fresh.health/circuit-breaker— wallet-balance monitors, cross-network circuit-breaker probes, club/social analytics.security— payment-proof idempotency and API-key bypass audits that exercise our own payment guards end to end.volume— small, bounded activity entries that keep the economy's heartbeat visible, including the Volume Bootstrap Loop (see below).reconciliation— the daily financial-integrity job (see below).qa/forge/self— animation-retarget QA, forge content generation, GLB size optimization, avatar thumbnail regeneration.
To pause any entry without a deploy, set its enabled: false; to pause the whole
loop, set X402_AUTONOMOUS_ENABLED=false.
The Volume Bootstrap Loop (volume-bootstrap-loop)
One registry entry — volume-bootstrap-loop, pipeline volume, cooldown 300s —
owns a full sweep rather than a single call. On each run it advances a
Redis-backed round-robin cursor, reserves the next X402_VOLUME_BATCH_PER_RUN
endpoints from the autobuy rotation in
api/_lib/x402/ring-catalog.js (mapped into
the shared driver by pipelines/volume-shared.js),
and pays each one a real on-chain USDC payment at that endpoint's own price
(from $0.001 for the cheap probes up to $1.00 for ring-settle, the rotation's
largest single call). It respects both
the loop's daily cap and its own X402_VOLUME_PER_RUN_CAP_ATOMIC per-run cap. It
records every call in x402_autonomous_log and upserts the per-endpoint ledger
x402_volume_metrics (call / success / fail counts, total + last USDC spent, last
tx signature, liveness timestamps). To add an endpoint to the sweep, add it to
ring-catalog.js with autobuy: true — the cursor and ledger pick it up
automatically (and tests/x402-ring-catalog.test.js fails until it is cataloged).
This is synthetic, not organic. The sweep pays our own endpoints from our own seed wallet; the USDC round-trips back to the platform treasury. It is a liveness canary + proof-of-volume mechanism, deliberately kept small — not external demand. Treat
x402_volume_metricsas monitoring, and exclude the seed wallet'spayerfrom any "marketplace volume" or facilitator-ranking number you publish. Scaling this loop to manufacture a big volume figure is wash volume: real transactions, fake demand, and detectable on-chain. Drive real volume through external demand (the Circulation engine, realagent_hirecommerce, discovery), not a heavier self-paid sweep.
Excluding it is mechanical, not a matter of remembering to.
api/_lib/x402/revenue-split.js classifies every settled payment in
x402_audit_log into three buckets by payer: internal (any
platform-controlled wallet, resolved through ringAllowedAddresses()),
synthetic (a payer string that is not a plausible on-chain address at all, such
as the literal PAYER written by replay-test paths), and external (a real
address we do not control). Only the last one is revenue.
npm run readout:revenue # trailing 30 days
npm run readout:revenue -- --window all # all time
npm run readout:revenue -- --json # machine-readable
The same split ships as revenue_split on the x402_volume report of the paid
/api/x402/analytics endpoint, so a buyer reading total_usdc_paid can see what
share of it is our own money, and the volume loop's own
x402_autonomous_log.signal_data now carries external_usdc beside the gross
figure.
The classification is deliberately conservative in one direction. If the
controlled-wallet registry (x402_ring_wallets) returns no enabled rows, the
ring's own wallets would be classified as external customers and the headline
number would inflate. The split reports confident: false with the reason
instead, and the readout script exits 2 rather than printing a figure it cannot
stand behind. An unavailable split is reported as null, never as a confident
zero: "we could not classify" and "there was no external revenue" are different
claims.
The Datapoint Fabric Volume Sweep
One registry entry — datapoint-volume-sweep, pipeline datapoint, cooldown
300s, settles real on-chain USDC against the
datapoint fabric
(the 1,000,000+ endpoints served by the single api/x402/d/[...path].js route),
which the Volume Bootstrap Loop above never touches (its rotation is the ~45
named catalog endpoints flagged autobuy: true). On each run it advances its own Redis-backed cursor
over a pool of concrete datapoint URLs — resolved at runtime from the same cached
feeds the paid route reads, so no third-party id is hardcoded — and pays the next
X402_DATAPOINT_SWEEP_BATCH (default 6) of them on Solana through the shared
pipelines/volume-shared.js
settleAndRecord path. A datapoint is the cheapest call in the catalog
($0.0005), so this is the most transactions-per-dollar-efficient sweep; over
successive runs the cursor walks the whole ~5k-URL pool, giving each distinct
datapoint URL its own on-chain settlement history. It draws from the same
daily cap the main loop respects (remainingCap) plus its own
X402_DATAPOINT_SWEEP_CAP_ATOMIC per-run cap, so it cannot increase total ring
spend — it only routes a slice of the capped budget at the cheapest endpoints.
No-op (graceful skip, no spend) when the wallet/RPC is unconfigured. See
pipelines/datapoint-volume-sweep.js.
Same synthetic-vs-organic caveat as the Volume Bootstrap Loop applies. This pays our own datapoint endpoints from our own seed wallet; the USDC round-trips to the treasury. It proves the fabric's payment path settles and gives x402scan per-resource settlement history, but it is canary volume, not demand. Do not publish it as marketplace volume, and do not read a high datapoint settle count as external traction — that would be wash volume. Real ranking comes from external buyers, not a heavier self-paid sweep.
Reconciliation (revenue-reconciliation)
The revenue-reconciliation entry (pipeline reconciliation, cooldown 86400s —
daily) is the financial-integrity watchdog. It cross-checks every record that
claims an on-chain settlement — outbound x402_autonomous_log rows and inbound
agent_payment_intents — against the actual Solana transaction via
getSignatureStatuses, and upserts a verdict per record into
payment_reconciliation. It is read-only, so it runs even with no spend
wallet configured (keyless RPC; the /api/x402-status probe it reads is free). A
reconciled = false row means the books claim a settlement the chain does not
corroborate — the ops financial-integrity surface alerts on those. Detail:
Financial controls.
Where results land
| Sink | Written by |
|---|---|
x402_autonomous_log |
Every call (success or failure), with signal_data / value_extracted. error_msg is reserved for calls that actually failed: the external uptime monitor probes third-party services for free and records an alive-but-unexpected status (a templated path answering 400, a verb-picky route answering 405) in value_extracted.status only, so a liveness observation never lands in the loop's failure stats. |
oracle_intel_signals |
oracle / sniper entries, keyed by source + topic; consumed by the sniper oracle gate. Each row carries tx_signature, the settle signature of the paid call that bought it, so a gate decision can cite its receipt (surfaced as signal_receipts on gate results). |
forge_creations |
Every settled POST /api/x402/forge generation (any buyer, not just this loop). The row lands in the public community gallery with x402_payer / x402_tx_sig / x402_price_atomic provenance; the gallery renders a Solscan-linked "x402 · $price" badge. Inline-done lanes materialize immediately; async lanes store the full job token and api/cron/forge-finalize completes them server-side. |
agent_custody_events |
The USDC spend, with category: 'x402' (see Money feed). |
x402_volume_metrics |
Per-endpoint proof-of-volume + liveness ledger from the Volume Bootstrap Loop. |
payment_reconciliation |
One verdict per settlement claim from the daily reconciliation job (see Financial controls). |
| Dedicated stores | Pipeline-specific tables (pricing tracker, reputation snapshots, leaderboard, sniper analytics, …). |
Related
- x402 endpoints — the paid endpoints this loop calls.
- Financial controls: where settlements land and how the reconciliation job audits them.
- x402 buyer client — the client wrappers it pays with.
- Circulation engine — the separate SOL/$THREE activity loop.