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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
docs(duels): document trader duels, how they resolve and their API, and link them from start-here and the quests doc
nirholas6a0696a3eabd
diff --git a/docs/start-here.md b/docs/start-here.mdindex 9e2b92aa4..1d0bc38ff 100644--- a/docs/start-here.md+++ b/docs/start-here.md@@ -153,6 +153,7 @@ Want the model in your hands rather than on a screen? [Materialize](./materializ- **Not ready to risk money on a trader yet?** → [Ghost-copy](./ghost-copy.md): paper-copy any verified agent over their real closed on-chain trades and see the equity curve your budget would have had, sized by the same engine that runs live copy trades. No wallet, no signature, no account, and every trade your budget could not reach is listed with the reason- **Rather copy with a crew?** → [Syndicates](./syndicates.md): a named team that follows the same verified traders together, each member from their own wallet under their own caps. A live group curve from members' real copies, a roster, and a rival on the board. Nothing pooled, nothing custodied, and leaving stops only what joining started- **Want a reason to show up tomorrow?** → [Daily trading quests](./trading-quests.md): five small goals a day scored from on-chain proof (verified trades, forks, first ghost-copies, acted copy intents, your agent's live wins), with XP, levels, a clear streak and badges+- **Think you can call the winner?** → [Trader duels](./trader-duels.md): free-to-play calls on which of two neighbouring traders books more realized profit over a UTC day or week, resolved from the on-chain ledger. Daily free points (no cash value), XP, a monthly season board and badges- **Have an audience of your own?** → [The trader card](./trader-card-embed.md): one script tag puts a trader's live on-chain record on your site, blog, link in bio or stream overlay, with a Fork button on every coin and a ghost-copy call to action, all signed by the reader's own wallet. It carries your referral code, holds no funds and asks for no key- **Running the platform?** → [Trading growth programs](./growth-programs.md): the big-win X poster, the first-rug softener and the early-leader $THREE bonus. All three ship disarmed; the page shows how to read what each would do today, every flag and cap, and the exact steps to arm one- **Running a chart page, a launchpad or a wallet?** → [Token in 3D, as an embed](./coin3d-embed.md): one iframe puts a live 3D view of any Solana market on your page, keyed by the mint or by the pair address your own URL already carries, with the coin's logo on a medallion, its holders as a galaxy sized by balance, a graduation ring and real swaps arriving on a tape. Free, keyless, no account, and it degrades to a data view where WebGL is unavailablediff --git a/docs/trader-duels.md b/docs/trader-duels.mdnew file mode 100644index 000000000..5d26b9cda--- /dev/null+++ b/docs/trader-duels.md@@ -0,0 +1,150 @@+# Trader duels++A free-to-play skill-prediction game on real trader agents. Two traders who sit+next to each other on the 30-day board, one fixed UTC window, one question: who+books more realized profit? You make your call before the window starts, and+the result comes straight from the on-chain trade ledger.++**Free to play. Points have no cash value and cannot be bought, sold,+transferred or redeemed.** There is no deposit, no escrow, no payout and no+token of any kind. Every account gets a free daily points allowance, and points+only ever buy calls on duels.++Page: [/duels](https://three.ws/duels) · one duel: `/duels/:id` · API: `/api/duels`++## How a duel works++1. **Generated from the rivalry engine.** Every 15 minutes the+ `duels-tick` cron asks [the rivalry engine](rivalries.md) for trader pairs+ that sit next to each other on the 30-day board (at least 3 closed trades+ each, public, not deleted) and opens up to three duels for the next window+ that has none yet:+ - a **24-hour duel** for the next UTC day, open for calls all of the day before;+ - a **week duel** for the Monday-to-Monday week, open from four days before it starts.+2. **Calls.** A signed-in user picks a side and stakes 10 to 100 points. One+ call per user per duel.+3. **Lock.** Calls lock the moment the window starts. The duel page then shows+ the race live: each trader's realized P&L inside the window so far.+4. **Resolve.** About 15 minutes after the window closes (a grace period for+ late ledger writes), the cron measures each trader's round-trips that+ **closed inside the window**, from both `agent_sniper_positions` and+ `agent_strategy_positions`, through `computeTraderMetrics`: the same math the+ [trader card](trader-card.md) and `/trader/:id` use, including the rule that+ profit on a trader's own coins is not credited.+5. **Settle.** More realized SOL wins.++| Outcome | What happens to calls |+|---|---|+| Your trader booked more | You get **2x your stake** back and **15 XP** |+| The other trader booked more | Your stake is gone |+| Exactly level (tie) | Void: every stake refunded, no XP |+| Neither trader closed a trade in the window | Void: every stake refunded |+| A trader went private or was deleted, at any time before resolution | Void immediately: every stake refunded |+| One trader closed trades, the other sat out | The idle trader counts as flat (0 SOL): sitting out beats a loss and loses to a profit |++## Points, XP, seasons, badges++- **Daily allowance:** 100 points per UTC day, credited the first time you open+ `/duels` (or make a call) that day. Unspent points carry over.+- **XP:** each correct call adds 15 XP to the same level you build on+ [daily trading quests](trading-quests.md) (ledger code `duel:<duel id>` in+ `trading_quest_completions`). Duel XP does not count as a completed quest.+- **Seasons:** a season is a UTC calendar month. The season board ranks+ predictors by net points from decided calls on duels resolved in that month+ (a win nets the stake, a loss costs it, voids count for nothing). Ties break+ on more correct calls, then fewer calls.+- **Badges** (shared `user_badges`, shown on your profile):++| Badge | Earned by |+|---|---|+| First Call | your first call |+| Called It | your first correct call |+| Hot Hand | three decided calls in a row correct (refunds neither break nor extend a run) |+| Sharp Caller | right on at least 70% of ten or more decided calls |++## Anti-abuse++Every rule is checked up front for a clear error, then enforced again inside+the single statement that writes the call, so a racing request can only be+refused, never slip through:++- **One call per user per duel:** unique index on `(market_id, user_id)`.+- **Locked at window start:** the insert compares `window_start` with the+ database clock.+- **No calls on your own agent:** if you own either trader, the insert refuses.+- **No overdraft:** the balance lives in `duel_wallets` with `check (balance >= 0)`;+ the pick, the ledger row and the debit are one statement.+- **No double payout:** settlement updates only `open` picks, and the ledger has+ a unique index on `(user_id, market_id, kind)`, so a replayed tick pays nothing twice.++## API++### `GET /api/duels`++Query: `phase` = `open` (taking calls) | `live` (window running or awaiting+resolution) | `settled` | `all` (default), `agent` (an agent id), `network`+(`mainnet` default), `limit` (1 to 60, default 30). Signed-in callers also get+their own call on each duel.++```bash+curl -s "https://three.ws/api/duels?phase=open"+```++```json+{+ "phase": "open",+ "counts": { "open": 2, "live": 2, "settled": 4 },+ "eligible_traders": 3,+ "rules": { "daily_allowance": 100, "min_stake": 10, "max_stake": 100, "win_multiplier": 2, "xp_per_win": 15 },+ "duels": [{+ "id": "<duel id>", "url": "/duels/<duel id>",+ "window_kind": "day", "window_start": "2026-10-01T00:00:00.000Z", "window_end": "2026-10-02T00:00:00.000Z",+ "resolves_at": "2026-10-02T00:15:00.000Z", "phase": "open",+ "a": { "agent_id": "<agent id>", "name": "…", "links": { "trader": "/trader/<agent id>", "trade_room": "/trade-rooms/<agent id>" } },+ "b": { "agent_id": "<agent id>", "name": "…" },+ "crowd": { "a": { "calls": 3, "points": 90 }, "b": { "calls": 1, "points": 25 } },+ "my_call": null+ }]+}+```++### `GET /api/duels/:id`++One duel with both traders' 30-day records (`record`), the in-window standing+(`standing`: live while the window runs, final once resolved), the crowd, and+`viewer.can_call`.++### `POST /api/duels/:id`++`{ "side": "a" | "b", "stake": 10..100 }`, signed in (session cookie with CSRF,+or a bearer token). `201 { call, balance }`. Errors: `invalid_side`,+`invalid_stake` (400), `unauthorized` (401), `own_agent` (403), `not_found`+(404), `duel_locked`, `already_called`, `not_enough_points`,+`duel_unavailable` (409).++### `GET /api/duels/me`++Signed in: `{ wallet: { balance, granted_now, daily_allowance, next_grant_at },+xp: { level, total, from_duels, ... }, season: { id, label, standing }, calls,+badges, newly_unlocked }`. Reading it credits today's allowance. Signed out:+`{ signed_in: false, rules }`.++### `GET /api/duels/leaderboard?season=YYYY-MM&limit=25`++`{ season, leaders: [{ rank, name, profile, net, wins, decided, accuracy }], me }`.++## Data and code++Migration `api/_lib/migrations/20260930150000_trader_duels.sql`: `duel_markets`,+`duel_picks`, `duel_wallets`, `duel_points_ledger`. Model+`api/_lib/trader-duels.js`, endpoints `api/duels/*`, cron+`api/cron/duels-tick.js` (every 15 minutes, in `vercel.json`), pages+`pages/duels.html` + `src/duels.js` and `pages/duel.html` + `src/duel.js`,+trader-profile widget `src/trader-duels.js`, tests `tests/trader-duels.test.js`.++## Related++- [Rivalries](rivalries.md): where the pairings come from+- [Trader card](trader-card.md): the same realized-P&L math+- [Daily trading quests](trading-quests.md): the XP level duels add to+- [Syndicates](syndicates.md): copy-trade as a teamdiff --git a/docs/trading-quests.md b/docs/trading-quests.mdindex 6198a7a14..c1c66b7dd 100644--- a/docs/trading-quests.md+++ b/docs/trading-quests.md@@ -29,7 +29,9 @@ signed in with), and each signature can be claimed once.Reaching level `L` takes `50 x L x (L - 1)` XP in total: 100 XP for level 2,300 for level 3, 600 for level 4. XP is an insert-only ledger, so it never goes-down when an underlying row later changes.+down when an underlying row later changes. Correct calls on+[trader duels](trader-duels.md) add 15 XP each to the same ledger (code+`duel:<duel id>`); they raise your level but do not count as completed quests.| Badge | Earned by ||---|---|@@ -125,5 +127,6 @@ ghost-copies per leader), `trading_quest_completions` (the XP ledger) and## Related- [Syndicates](syndicates.md): copy-trade as a team+- [Trader duels](trader-duels.md): free-to-play calls on head-to-head traders, more XP- [Fork a trade](fork-trade.md) and [Ghost-copy](ghost-copy.md): two of the quests- [Copy trading](copy-trading.md): where copy intents come from