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): give integrators one error table with retry guidance, the real rate limits, idempotency, key storage and a pre-launch checklist

nirholase9340dd05659
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c324b27a4..fba842577 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,6 +19,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
- **skill.md** (`/skill.md`): The three.ws Agent Skill: how an AI agent connects to three.ws, the rules it follows around money and official addresses, and an index of the focused skills for 3D generation, avatars and agents. Load it like any SKILL.md.
- **Syndicates: copy-trade as a team** (`/syndicates`): Named teams of copiers who follow the same verified pump.fun trader agents together. Each member copies from their own wallet under their own caps; the team shares a flag, a live equity curve from members' real copies, and a rival on the board. No pooled funds, no custody.
- **3D Studio in ChatGPT finishes every model, however long it takes**: ChatGPT stops waiting on a tool after one minute, and a detailed 3D model takes one to four. The 3D Studio plugin now answers inside that minute and the inline viewer finishes the job itself: it shows a live timer, drops the model in the moment it is ready, rigs an avatar's skeleton on its own when that step is still to come, and keeps a refined model's version history so you can flip back to the original. Inspecting an existing model now shows it in the viewer too, avatars always come out as a full body ready to pose even when the prompt helper is unavailable, and busy periods no longer let one ChatGPT user's generations use up everyone else's. (`/docs/mcp-studio`) `[improvement, fix]`
+- **API docs you can build a production integration from**: The API reference now has one error table that says, for every common error, whether retrying can help and what to do instead, plus the real rate limits with the headers that tell a client how much budget it has left, how idempotent retries work, how API keys are stored and revoked, a pre-launch integration checklist, and what to include when asking for help. (`/docs/api-reference`) `[docs]`
- **Copy Coach: your first copy trade, the careful way**: Never copied a trader before? The new Copy Coach walks you through it in four small steps. First it shows a real verified win, right next to the full record of the agent that made it, so one lucky trade never passes for a track record. Then you ghost-copy a leader with fake money over their real trades. Only then can you set up one tiny real copy: capped at 0.05 SOL per trade and 0.2 SOL a day by the server, paused automatically if the leader starts losing, and spending nothing until you sign each trade from your own wallet. Ask the coach anything along the way; it answers from the real numbers on the page and never promises returns. (`/copy-coach`) `[feature]`
- **Daily trading quests with XP, levels and badges**: A new quests page gives you five small trading goals every day: make three trades, fork a verified trade, ghost-copy an agent you have never tried, act on a copy intent, and have your own agent close a winning trade. Each one is checked against real on-chain activity rather than a button press. Clear three in a day to keep your streak going, level up with XP, and earn the First Quest, Daily Clear and Quest Streak 7 badges on your profile. (`/quests`) `[feature]`
- **Know the real three.ws and the real $THREE at a glance**: Every page footer now states that three.ws is the only official website and that the $THREE address shown there is the only official mint, so a look-alike site or copycat token is easier to spot. The same notice leads the llms.txt index that AI assistants read, which is now a short curated guide to the key pages instead of a list of nearly a thousand, with the full list still in llms-full.txt. (`/three-token`) `[security, improvement]`
diff --git a/data/changelog.json b/data/changelog.json
index a71b5302a..eef512fb4 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,13 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-09-29",
+ "title": "API docs you can build a production integration from",
+ "summary": "The API reference now has one error table that says, for every common error, whether retrying can help and what to do instead, plus the real rate limits with the headers that tell a client how much budget it has left, how idempotent retries work, how API keys are stored and revoked, a pre-launch integration checklist, and what to include when asking for help.",
+ "tags": ["docs"],
+ "link": "/docs/api-reference"
+ },
{
"date": "2026-09-29",
"title": "One link teaches any AI agent to use three.ws",
diff --git a/docs/api-reference.md b/docs/api-reference.md
index aec2cf58a..ca84301a9 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -22,9 +22,15 @@ Authorization: Bearer sk_live_xxxxx
Session cookies (set after SIWE or Privy login) are accepted on all endpoints that support Bearer auth.
+**API keys.** Create one at [Dashboard → API](https://three.ws/dashboard/api). A key starts with `sk_live_` and is shown exactly once: three.ws stores only its SHA-256 hash plus the first 14 characters as a visible prefix, so a lost key cannot be recovered, only replaced. Each key carries the scopes you chose when you made it, and a call outside them fails with `insufficient_scope`. Revoking a key takes effect on the next request, because keys are checked against the database on every call. Keep keys server-side; never ship one in a browser or mobile bundle.
+
+**OAuth tokens.** MCP clients and the [CLI](/docs/cli) sign in with OAuth instead of a key. Access tokens last one hour and refresh automatically. Revoking a client under [Dashboard → Settings → Connected apps](https://three.ws/dashboard/settings) stops its refresh token at once, so the client loses access when its current access token expires, within the hour.
+
### Response format
-All responses are JSON. Successful responses return the resource or a result object. Errors return a machine-readable code plus a human-readable description:
+All responses are JSON. Successful responses return the resource or a result object. Errors come in one of two shapes, depending on the surface.
+
+Most endpoints return a machine-readable code plus a human-readable description:
```json
{
@@ -33,16 +39,36 @@ All responses are JSON. Successful responses return the resource or a result obj
}
```
+The versioned agents API (`/api/v1/agents`, `/runs`, `/automations`, `/models`, `/me`, `/intel`, `/strategies`) wraps every response in one envelope, and also sends the request id as an `x-request-id` header:
+
+```json
+{ "data": { "…": "…" }, "meta": { "requestId": "6f0e…", "timestamp": "2026-09-29T12:00:00.000Z" } }
+{ "error": { "code": "insufficient_scope", "message": "This route requires the \"wallet:write\" scope.", "details": null }, "meta": { "requestId": "6f0e…" } }
+```
+
Some endpoints add extra fields (e.g. `retry_after` on rate limits). Error responses are never cached.
### Rate limits
-| Tier | Limit |
-| --------------- | ----------- |
-| Authenticated | 100 req/min |
-| Unauthenticated | 20 req/min |
+Limits are set per endpoint family rather than as one global number, and each is sized to what that endpoint costs. A few examples:
+
+| Surface | Limit | Keyed by |
+| --- | --- | --- |
+| Versioned agents API (`/api/v1/…`) | 120 requests per minute | API key, else user, else IP |
+| Sign-in and other credential checks | 50 requests per 10 minutes | IP |
+| Agent creation (`POST /api/agents`) | 20 per 10 minutes | IP |
+
+Every limited response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` headers, so a client can pace itself before it is cut off. Past the limit the answer is HTTP 429 with a `Retry-After` header (seconds) and this body:
-Rate-limited responses return HTTP 429 with `{ "error": "...", "code": "RATE_LIMITED" }`.
+```json
+{ "error": "rate_limited", "error_description": "too many requests", "retry_after": 42 }
+```
+
+If the body also has `"reason": "rate_limiter_unavailable"`, you did not hit a quota: the limiter itself was briefly unreachable and failed closed on a sensitive route. Wait `retry_after` seconds and retry as normal.
+
+### Idempotency
+
+Writes on the versioned agents API accept an `Idempotency-Key` header (up to 200 characters). The first request with a key runs; a retry with the same key and the same body within 24 hours gets the stored response back with `Idempotent-Replayed: true`, and nothing runs twice. Reusing a key with a different body is rejected with `422 idempotency_key_reused`, and a retry that arrives while the first is still running gets `409 idempotency_in_progress`. Other write endpoints are not idempotent unless their section says so, so guard retries on your side. Paid x402 endpoints are idempotent per payment: see [x402](/docs/x402).
---
@@ -8808,23 +8834,47 @@ GET /api/v1/pump/launches?limit=24&offset=24
## Error codes
-Codes are lowercase snake_case in the `error` field. The common ones, shared across endpoints:
-
-| Code | HTTP Status | Description |
-| -------------------- | ----------- | ----------------------------------------------- |
-| `unauthorized` | 401 | Missing or invalid auth |
-| `forbidden` | 403 | Authenticated but not allowed |
-| `insufficient_scope` | 403 | Bearer token lacks the required scope |
-| `not_found` | 404 | Resource doesn't exist |
-| `rate_limited` | 429 | Too many requests (see `retry_after`) |
-| `validation_error` | 400 | Request body or query validation failed |
-| `not_configured` | 503 | A required provider/env is unset on this deploy |
-| `upstream_error` | 502 | A third-party upstream returned an error |
+Codes are lowercase snake_case: in the `error` field on most endpoints, in `error.code` on the versioned agents API. The common ones, shared across endpoints, with whether a retry can help:
+
+| Code | HTTP | Meaning | Retry? | What to do |
+| --- | --- | --- | --- | --- |
+| `validation_error`, `bad_json`, `missing_parameter`, `invalid_parameter` | 400 | The body or query failed validation. `details.parameter` names the field on v1 | No | Fix the request |
+| `unauthorized` | 401 | No credential, or it is invalid, expired or revoked | No | Check the `Authorization` header; re-sign in or create a new key |
+| (x402 challenge) | 402 | A paid x402 endpoint needs payment. The body's `accepts` list carries the terms (price, asset, network, recipient), mirrored base64-encoded in the `PAYMENT-REQUIRED` header when it fits | After paying | Pay with an x402 client and repeat the same request with the payment header ([x402](/docs/x402)) |
+| `forbidden` | 403 | Signed in, but this account may not do this (not the owner, or a cross-site cookie write) | No | Use a resource your account owns; send cookie writes same-site |
+| `insufficient_scope` | 403 | The key or token lacks the scope this route needs | No | Create a key, or sign in again, with that scope |
+| `not_found` | 404 | No such resource, or not visible to you | No | Check the id |
+| `conflict`, `idempotency_in_progress` | 409 | The resource already exists, or the same idempotent request is still running | Conflict no, in-progress yes | Read the existing resource, or retry shortly with the same `Idempotency-Key` |
+| `idempotency_key_reused` | 422 | The `Idempotency-Key` was already used with a different body | No | Use a new key for a new request |
+| `rate_limited` | 429 | Over the limit for this endpoint | Yes, after `Retry-After` | Back off for the stated seconds |
+| `internal_error` | 500 | An unexpected failure. The message is sanitized | Yes, with backoff | Report it with the `requestId` if it persists |
+| `upstream_error` | 502 | A third-party upstream failed | Yes, with backoff | Retry; nothing on your side to change |
+| `not_configured` | 503 | A required provider is not set on this deployment | No | Contact support: this is ours to fix |
+
+Only retry a write if it carries an `Idempotency-Key` or its section says it is idempotent; otherwise a retry after a timeout can run it twice.
Endpoint-specific codes (e.g. `quota_exceeded`, `invalid_avatar`, `no_client_id`) are documented in each endpoint's Errors table above.
---
+## Integration checklist
+
+Run through this before you ship an integration:
+
+- The API key lives in a server-side secret store, never in a browser or mobile bundle, and carries only the scopes your product needs.
+- Every request goes to `https://three.ws/api/…`. Clients drop the `Authorization` header when a request is redirected to another host, so do not call through a redirecting domain.
+- Every write you might retry sends an `Idempotency-Key`, or is one the docs mark idempotent.
+- Retries happen only on 429, 5xx and network errors, honor `Retry-After`, and back off exponentially.
+- A 402 is read as payment terms, and a person or a spend policy approves the amount and recipient before anything is paid.
+- `x-request-id` (or `meta.requestId`) is logged for every failed call, so a support request can point at it.
+- Calls that can take long (agent chat turns, 3D generation, launches) have a client timeout of at least 120 seconds.
+
+## Support
+
+Open an issue on [GitHub](https://github.com/nirholas/three.ws/issues) or message [@trythreews](https://x.com/trythreews) with the endpoint, the UTC time, the HTTP status, the request id if the response had one, and your key's prefix (the first 14 characters). Never send the full key: nobody at three.ws needs it to help you.
+
+---
+
## SDK
For building on the platform from JavaScript, the official npm package is [`@three-ws/sdk`](https://www.npmjs.com/package/@three-ws/sdk). It is not a thin wrapper over every REST route above; it ships the higher-level building blocks: `AgentKit` (chat panel + ERC-8004 registration + `.well-known` manifest generation), `AgentClient` (x402 agent-to-agent paid skill calls), `PermissionsClient` (ERC-7710 delegations), and the Solana identity/attestation helpers. Full docs: [SDK & Library](sdk.md).
diff --git a/pages/connect.html b/pages/connect.html
index 7fb41b9a7..3d89e73bd 100644
--- a/pages/connect.html
+++ b/pages/connect.html
@@ -334,7 +334,7 @@
</div>
<div class="cn-fact">
<h3>Revoke it any time</h3>
- <p>Every client you connect appears under <a href="/dashboard/settings">Dashboard → Settings → Connected apps</a>. Revoking one signs that client out immediately; your agents and balances are untouched.</p>
+ <p>Every client you connect appears under <a href="/dashboard/settings">Dashboard → Settings → Connected apps</a>. Revoking one stops that client within an hour, when its current access token expires. Your agents and balances are untouched.</p>
</div>
<div class="cn-fact">
<h3>Every tool is labelled</h3>
diff --git a/public/changelog-recent.json b/public/changelog-recent.json
index c275770f3..996dccae9 100644
--- a/public/changelog-recent.json
+++ b/public/changelog-recent.json
@@ -1,11 +1,11 @@
{
- "generated_at": "2026-09-29T23:36:04.596Z",
+ "generated_at": "2026-09-29T23:41:56.111Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
"url": "https://three.ws"
},
- "total": 3779,
+ "total": 3780,
"complete": false,
"full_feed": "/changelog.json",
"entries": [
@@ -140,6 +140,16 @@
"fix"
]
},
+ {
+ "date": "2026-09-29",
+ "type": "update",
+ "title": "API docs you can build a production integration from",
+ "summary": "The API reference now has one error table that says, for every common error, whether retrying can help and what to do instead, plus the real rate limits with the headers that tell a client how much budget it has left, how idempotent retries work, how API keys are stored and revoked, a pre-launch integration checklist, and what to include when asking for help.",
+ "link": "/docs/api-reference",
+ "tags": [
+ "docs"
+ ]
+ },
{
"date": "2026-09-29",
"type": "update",
@@ -1581,17 +1591,6 @@
"improvement",
"docs"
]
- },
- {
- "date": "2026-09-09",
- "type": "update",
- "title": "Restyle Studio: a failed save now tells you what went wrong and what still works",
- "summary": "A full audit of /restyle, the material and PBR editor. Every failure coming back from the server was thrown away and replaced with a bare status code: a rejected model URL read as \"Restyle failed: restyle failed (400)\" when the server had actually said which part of the URL it would not accept. The page now shows the real reason on all four calls it makes (AI restyle, seeded variants, version checkpoints, and texture generation). A second case got its own wording: when the model store itself is unavailable, the note says so, and points out that your edits are still live in the viewer and that Export GLB keeps working, because export runs entirely in your browser and needs no server at all. Dropping a local file used to be told to \"load a public URL instead\" even when the URL was never the problem, which sent people in circles; the advice now matches the actual failure. Verified end to end in a real browser: the 18 material presets, the live metalness, roughness, colour and emissive sliders, the seeded variant strip, Reset, and a validated GLB export all check out, as do the loading and error states, keyboard focus on every control, and the layout at 320, 768 and 1440 pixels.",
- "link": "/restyle",
- "tags": [
- "fix",
- "improvement"
- ]
}
]
}
diff --git a/public/changelog.json b/public/changelog.json
index 7eef7b65c..53b6afc25 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-09-29T23:36:04.578Z",
+ "generated_at": "2026-09-29T23:41:56.093Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
@@ -137,6 +137,16 @@
"fix"
]
},
+ {
+ "date": "2026-09-29",
+ "type": "update",
+ "title": "API docs you can build a production integration from",
+ "summary": "The API reference now has one error table that says, for every common error, whether retrying can help and what to do instead, plus the real rate limits with the headers that tell a client how much budget it has left, how idempotent retries work, how API keys are stored and revoked, a pre-launch integration checklist, and what to include when asking for help.",
+ "link": "/docs/api-reference",
+ "tags": [
+ "docs"
+ ]
+ },
{
"date": "2026-09-29",
"type": "update",
diff --git a/public/changelog.xml b/public/changelog.xml
index bd95c4320..0815d86f7 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -110,6 +110,14 @@
<category>improvement</category>
<description>ChatGPT stops waiting on a tool after one minute, and a detailed 3D model takes one to four. The 3D Studio plugin now answers inside that minute and the inline viewer finishes the job itself: it shows a live timer, drops the model in the moment it is ready, rigs an avatar's skeleton on its own when that step is still to come, and keeps a refined model's version history so you can flip back to the original. Inspecting an existing model now shows it in the viewer too, avatars always come out as a full body ready to pose even when the prompt helper is unavailable, and busy periods no longer let one ChatGPT user's generations use up everyone else's.</description>
</item>
+ <item>
+ <title>API docs you can build a production integration from</title>
+ <link>https://three.ws/docs/api-reference</link>
+ <guid isPermaLink="false">2026-09-29:API docs you can build a production integration from</guid>
+ <pubDate>Tue, 29 Sep 2026 12:00:00 GMT</pubDate>
+ <category>docs</category>
+ <description>The API reference now has one error table that says, for every common error, whether retrying can help and what to do instead, plus the real rate limits with the headers that tell a client how much budget it has left, how idempotent retries work, how API keys are stored and revoked, a pre-launch integration checklist, and what to include when asking for help.</description>
+ </item>
<item>
<title>Copy Coach: your first copy trade, the careful way</title>
<link>https://three.ws/copy-coach</link>