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): 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.md
index 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