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(api-reference): document the Solana transfer, swap, and explain endpoints
nirholasf7d8632dc1fe
diff --git a/docs/api-reference.md b/docs/api-reference.mdindex 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 Blinkdiff --git a/prompts/swarm-100/api-tx-01.md b/prompts/swarm-100/api-tx-01.mddeleted file mode 100644index 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.