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.

docs(api-reference): document the Solana transfer, swap, and explain endpoints

nirholasf7d8632dc1fe
diff --git a/docs/api-reference.md b/docs/api-reference.md
index e2816311d..899dde631 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -5460,6 +5460,148 @@ curl -s -b cookies.txt 'https://three.ws/api/users/referrals?funnel_days=7' | jq
---
+## Transaction API: build and explain
+
+Three endpoints the in-app wallet and the chat wallet tools
+([chat/src/tools.js](../chat/src/tools.js)) use to prepare a transaction for the
+user's wallet to sign, and to read one back in plain English. **The server never
+signs and never broadcasts**: it returns unsigned bytes, and the wallet owns the
+approval.
+
+### Build a Solana transfer
+
+```
+POST /api/tx/solana/build-transfer
+```
+
+Session cookie required (`401 unauthorized` without one). Builds an unsigned legacy
+transaction moving SOL or any SPL token from `sender` to `recipient`.
+
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `sender` | string | required | Base58 wallet address. Also the fee payer. |
+| `recipient` | string | required | Base58 wallet address. |
+| `amount` | number | required | UI amount (SOL, or whole tokens), > 0 and at most 1e12. Converted to base units with fixed-point string math, so no float drift. |
+| `token` | string | `SOL` | `SOL` for a native transfer, otherwise the SPL mint address. |
+| `memo` | string | none | Attached as an SPL Memo instruction. Max 512 bytes. |
+| `network` | string | `mainnet` | `mainnet` or `devnet`. |
+
+The mint's owning program is read from the chain, so **Token-2022 mints work**,
+including `$THREE` and every other pump.fun-era launch. The transfer instruction is
+`TransferChecked`, which Token-2022 mints carrying a transfer-fee extension require.
+The recipient's associated token account is created in the same transaction when it
+does not exist yet, paid for by the sender.
+
+```json
+{
+ "transaction": "AQAAAAAA...",
+ "network": "mainnet",
+ "blockhash": "7yfLFPfbbzAk52tx5BxfsDcfrneAoJfwEihVJtnkM9ph",
+ "lastValidBlockHeight": 417508552
+}
+```
+
+Deserialize `transaction` (base64), have the wallet sign it, then broadcast and
+confirm against `blockhash` / `lastValidBlockHeight`.
+
+Caller faults answer 4xx before anything is built, so a user is never asked to
+approve a transaction that can only fail:
+
+| Code | Status | When |
+|---|---|---|
+| `validation_error` | 400 | A field is missing or malformed (a non-base58 address, a non-positive amount, an oversized memo, an unknown network). `issues[]` names the field. |
+| `invalid_mint` | 400 | `token` is not on-chain, or is not an SPL mint. |
+| `invalid_owner` | 400 | `sender` or `recipient` is a program-derived address, which has no associated token account and no key to sign with. |
+| `insufficient_balance` | 400 | The sender holds less of the token than requested. |
+| `invalid_amount` | 400 | The amount rounds to zero at the mint's precision, or exceeds the lamport ceiling. |
+| `upstream_error` | 502 | Solana RPC would not answer. |
+
+```bash
+curl -s -X POST https://three.ws/api/tx/solana/build-transfer \
+ -H 'content-type: application/json' -b cookies.txt \
+ -d '{"sender":"<wallet>","recipient":"<wallet>","amount":0.1,"memo":"gm"}' | jq -r .blockhash
+```
+
+### Build a Solana swap
+
+```
+POST /api/tx/solana/build-swap
+```
+
+Session cookie required. Quotes and builds an unsigned Jupiter swap through the
+shared lite-api client ([api/_lib/token/jupiter.js](../api/_lib/token/jupiter.js)).
+
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `sender` | string | required | Base58 wallet address; the swap's `userPublicKey`. |
+| `inputMint` | string | required | Base58 mint to spend. Must differ from `outputMint`. |
+| `outputMint` | string | required | Base58 mint to receive. |
+| `amount` | number | required | UI amount of `inputMint`, > 0. Scaled by that mint's decimals. |
+| `slippageBps` | integer | `50` | 1 to 5000. |
+| `network` | string | `mainnet` | `mainnet` only. |
+
+```json
+{
+ "transaction": "AQAAAAAA...",
+ "network": "mainnet",
+ "inputAmount": 0.01,
+ "outputAmount": 123.456789,
+ "outputMint": "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump",
+ "priceImpactPct": "0.12"
+}
+```
+
+`transaction` is a base64 `VersionedTransaction`. `no_route` (422) means Jupiter
+found no route for the pair and size, `swap_failed` (422) that it quoted but could
+not build, `invalid_route` (400) that both mints are the same, and `upstream_error`
+(502) that Jupiter was unreachable.
+
+### Explain a transaction
+
+```
+POST /api/tx/explain
+```
+
+No auth; IP rate-limited. Reads a confirmed transaction on Solana or Ethereum
+mainnet and returns its transfers plus, when an LLM lane is configured, a one
+paragraph plain-English `summary`.
+
+| Field | Type | Notes |
+|---|---|---|
+| `chain` | string | `solana` or `evm`. |
+| `sig` | string | Solana: a base58 signature that decodes to exactly 64 bytes. EVM: a `0x`-prefixed 32-byte tx hash. |
+
+Solana reads go to the Helius enhanced-transaction API and fall back to
+`getParsedTransaction` over the rotating RPC chain, reconstructing transfers from
+balance deltas. EVM reads walk a failover chain of Alchemy, any configured RPC, then
+keyless public nodes, and decode ERC-20 `Transfer` logs.
+
+```json
+{
+ "tokenTransfers": [],
+ "nativeTransfers": [{ "account": "<pubkey>", "amount": -5000 }],
+ "description": "",
+ "type": "",
+ "feePayer": "<pubkey>",
+ "source": "rpc-fallback",
+ "summary": "The account paid a 5,000 lamport fee ..."
+}
+```
+
+A finished explanation is cached for 24 hours per `chain:sig`, so re-explaining the
+same transaction costs nothing upstream. A malformed `chain` or `sig` is
+`400 bad_request` and never reaches a billed upstream; an unknown transaction is
+`404 not_found`; an RPC outage is `502 upstream_error`; exhausting the shared
+enhanced-API cost ceiling is `429`.
+
+```bash
+curl -s -X POST https://three.ws/api/tx/explain \
+ -H 'content-type: application/json' \
+ -d '{"chain":"solana","sig":"<base58 signature>"}' | jq -r .summary
+```
+
+---
+
## Solana Actions API (Blinks)
three.ws publishes a Solana Action so "Claim Your 3D Avatar" unfurls as a Blink
diff --git a/prompts/swarm-100/api-tx-01.md b/prompts/swarm-100/api-tx-01.md
deleted file mode 100644
index 01dacfd44..000000000
--- a/prompts/swarm-100/api-tx-01.md
+++ /dev/null
@@ -1,102 +0,0 @@
-# API audit: api/tx batch 01 (2 files)
-
-How to run: paste this file's repo path into a fresh Claude Code chat in this
-repository and say "run this work order". This file is fully self-contained:
-it depends on no other prompt file anywhere. If neighboring files in
-prompts/swarm-100/ are gone, that work is done; if present, ignore them.
-Every claim below rots; step 0 re-measures, and what you measure wins.
-
-## Operating clause (binding)
-
-- Read CLAUDE.md first. Its rules override everything, including this file.
-- Finish 100% in this session. Never end the turn with a question, an option
- list, or an unexecuted plan. A judgment call goes in one line of the final
- report; it never becomes a question that halts work.
-- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real
- funds or any irreversible on-chain write, git push or a production deploy,
- committing content that references a crypto project other than $THREE, and
- destroying unrecoverable data.
-- No mocks, no fake data, no placeholder stubs, no unfinished-work markers, no
- commented-out code. Real APIs and real integrations only.
-- The em-dash and en-dash characters are banned in everything you write.
-- Concurrent agents share this worktree: stage explicit paths only (never a
- bare add-everything), and commit finished work promptly.
-- Before committing, run: npm run check:rules -- --paths <files you touched>.
- It must exit 0.
-
-## Step 0: re-derive the current state
-
-1. Confirm each file below still exists; deleted ones are done, skip them.
-2. For each, decide routability: grep its path in vercel.json and read how
- server/index.mjs maps filesystem handlers. Routed files get an endpoint
- audit; internal modules get a code and test audit.
-3. Start a local server for endpoint checks: node server/index.mjs with .env
- loaded, on a free PORT if 3000 is busy.
-
-## Task: audit these api files, then fix everything found
-
-Files in this batch:
-
-- api/tx/explain.js
-- api/tx/solana/[action].js
-
-For every routed handler:
-
-1. Exercise it with curl against the local server: the success path returns
- real data with the correct status; malformed input returns a 4xx JSON
- error, never a stack trace or an HTML error page; auth is enforced where
- the code intends it; CORS matches neighboring handlers.
-2. Hard-rule scan: no mock fallbacks, no fake-data arrays, no stubbed
- responses, no unfinished markers. Errors are handled at the boundary and
- internal code trusts itself.
-3. Do not spend funds or sign anything on-chain while probing. Payment and
- trading handlers get their validation and error paths exercised, never a
- live settlement.
-
-For every internal (non-routed) module:
-
-4. Something must import it; if nothing does, delete it as dead code (verify
- with a repo-wide grep first).
-5. Its main path and one failure path must be covered in tests/; add the
- missing test if not.
-
-## Definition of done
-
-- [ ] Every listed file has recorded evidence: a curl transcript for routed
- handlers, a passing test or a deletion for internal modules.
-- [ ] Zero hard-rule violations remain in these files.
-- [ ] vitest run passes; npm run check:rules -- --paths <touched files>
- exits 0.
-
-## Never blocked
-
-| Blocker | Resolution (act, do not ask) |
-|---|---|
-| Missing env var or credential | Check .env and .env.local, then the Cloud Run service env, then Secret Manager (the CLAUDE.md self-unblock playbook has the exact commands). If it truly exists nowhere, wire the code fully behind the env var, prove the wiring with a dry run, and name the single missing var in the report. |
-| gcloud not on PATH | Run: export PATH="$HOME/google-cloud-sdk/bin:$PATH" |
-| Dev server port 3000 busy | Another agent may be serving this repo; probe it and reuse if so. Otherwise start your own on a free port: npx vite --port 3101 |
-| Playwright browser missing | npx playwright install chromium |
-| A surface needs a signed-in user | Register a fresh account through the real /register flow against the real API and use it. Never mock the session. |
-| A defect sits in code you did not touch | Fix it if it blocks a Definition of done line (root cause it, never mask it). Otherwise note it in the report and continue. |
-| An unrelated test is red | Same rule. Never pipe npm test through tail; it masks exit codes. |
-
-## Close out (required)
-
-1. Verify every Definition of done line with the actual command output in
- front of you. Never claim a line you did not verify.
-2. Commit with explicit paths and a subject that describes the diff (house
- style: type(scope): what changed and why a reader cares).
-3. Delete this prompt file in that same commit:
-
- git rm prompts/swarm-100/api-tx-01.md
-
- The shrinking directory is this campaign's only progress ledger; there is
- no progress log to update.
-4. Final report: what step 0 measured, what changed (file list), evidence per
- Definition of done line, and any one-line judgment calls. No trailing
- questions, no unexecuted plans.
-
-If a line genuinely cannot pass inside this session (an external party must
-respond, or an owner-gated action is the final step), finish everything else,
-leave this file in place, and state exactly which line remains and who owns
-it. Never delete this file on a partial.