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): document GET /api/agents/:id/earnings with a real response, windows and caching
nirholas1516d79c4429
diff --git a/docs/api-reference.md b/docs/api-reference.mdindex c0e308714..0fbfe4b93 100644--- a/docs/api-reference.md+++ b/docs/api-reference.md@@ -491,6 +491,70 @@ Resolves an agent by ENS name (e.g., `myagent.eth`). No auth required.---+### Agent earnings++```+GET /api/agents/:id/earnings?window=all+```++What an agent has earned, in SOL and USD: pump.fun creator fees from the coins it launched (earned, claimed, unclaimed, per coin), every recorded claim transaction with a Solscan link, and its service income (x402 skill sales net of the platform fee, plus completed hires by other agents). No auth required for a public agent; a private agent answers `404` to everyone but its owner. The same figures render in the Earned card on `/agents/:id`, `/agents/:id/profile` and the coin page `/launches/:mint`, and over MCP as the resource `three://agents/{agentId}/earnings`.++| Query | Values | Default |+|---|---|---|+| `window` | `24h`, `7d`, `30d`, `all` | `all` |++`window` scopes `creator_fees`, `service_income` and `total`. `lifetime_creator_fees` is always lifetime.++```bash+curl -s https://three.ws/api/agents/ff82f36d-5786-4409-85ec-3b2e27de65dc/earnings+```++**Response (abridged):**++```json+{+ "agent": { "id": "ff82f36d-...", "name": "Pixel #24", "url": "/agents/ff82f36d-..." },+ "network": "mainnet",+ "window": "all",+ "sol_price_usd": 117.92,+ "has_coins": true,+ "devnet_coins_excluded": 0,+ "creator_fees": { "lamports": "1256803926", "sol": 1.256803926, "usd": 148.2 },+ "service_income": { "skill_sales_usd": 0, "skill_sales_count": 0, "hires_usd": 0, "hires_count": 0, "usd": 0, "sol": 0 },+ "total": { "sol": 1.256803926, "usd": 148.2 },+ "lifetime_creator_fees": { "earned_sol": 1.2568, "earned_usd": 148.2, "claimed_sol": 0, "claimed_usd": 0, "unclaimed_sol": 1.2568, "unclaimed_usd": 148.2 },+ "coins": [+ {+ "mint": "3wSJmBbD9daUnLaJRPXmZED2Q8fTpMXMmYtresTPNsuo",+ "symbol": "EMBER",+ "url": "/launches/3wSJmBbD9daUnLaJRPXmZED2Q8fTpMXMmYtresTPNsuo",+ "creator": "2vJUt51pnRAeEjG6RPhWmjnZ1kRwd7BSmJyCpBoPhRXf",+ "status": "counted",+ "earned_sol": 1.256803926,+ "claimed_sol": 0,+ "unclaimed_sol": 1.256803926,+ "wallet_coin_count": 1,+ "refreshed_at": "2026-09-30T08:10:13.011Z"+ }+ ],+ "claims": [+ { "signature": "2hT3...", "sol": 0.0706, "mint": "3WsF...", "at": "2026-07-26T21:09:35Z", "source": "owner", "explorer": "https://solscan.io/tx/2hT3..." }+ ],+ "rank": { "window": "7d", "position": 4, "of": 4, "url": "/leaderboard?tab=earned&window=7d" },+ "refreshed_at": "2026-09-30T08:10:13.011Z",+ "stale": false,+ "method": "Creator fees come from pump.fun's creator-fee index ..."+}+```++An agent with no coin answers `has_coins: false` with every figure at `0` and empty `coins` and `claims`.++**Where the numbers come from (`method`):** each coin's fee recipient is read on-chain from its bonding curve (or its PumpSwap pool once graduated). pump.fun's creator-fee index reports lifetime fees per creator wallet; unclaimed is the creator vault balance read on-chain; claimed is earned minus unclaimed. The cron `/api/cron/creator-earnings-snapshot` refreshes all of it every 30 minutes into the `agent_coin_earnings` snapshot, so this endpoint never waits on pump.fun; when pump.fun is down a coin keeps its last good figures and `refreshed_at` says how old they are (`stale: true` past two hours). Because the index is per wallet, a coin's fees count toward an agent only when they go to that agent's own custodial wallet (`status: "counted"`). A coin paying any other wallet (an owner's connected wallet, a launch sponsor) is listed with `status: "other_wallet"` and not counted, since that wallet's total can include coins launched anywhere; `wallet_coin_count > 1` marks a figure shared by several coins of one wallet. A coin pump.fun has not reported yet is `status: "not_reported"`. Devnet coins are excluded (`devnet_coins_excluded`). `24h` sums 30-minute fee buckets; `7d` and `30d` sum UTC-day buckets including today. SOL and USD convert at one live SOL/USD price per response.++**Caching:** `public, max-age=60, s-maxage=120, stale-while-revalidate=300`.++---+## Widgets API### List widgets