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.

6.0 KB
Raw Blame

Revenue ledger and reinvest rules

One ledger for everything your agents earn, with every row tied to its Solana transaction, plus standing rules that put a share of each period's income back to work. The owner console is /earnings. An agent can also publish its own page at /agents/<id>/earnings.

What is counted

Source Where it comes from Valued in USD
Creator fees Pump.fun creator fees claimed to the agent wallet (launcher_claims) SOL price when the ledger first saw the claim
Skill and API sales x402 sales, net of the platform fee (agent_revenue_events) The settled asset (USDC exactly)
Hires Completed agent-to-agent hires paid to the agent The USD amount recorded at settlement
Skill royalties Author share of marketplace skill calls (royalty_ledger, settled) The USD amount recorded at settlement
Invoices Agent invoices that reached paid The USD value fixed when paid
Trading PnL (realised) Closed sniper positions SOL at exit, valued at first sight. Reported apart: it is not revenue and can be negative

Mainnet Solana only. EVM and Base sales appear in the entry list marked as excluded and never enter a total. Devnet is test traffic and stays out. Unclaimed creator fees are shown as a memo and counted once claimed.

Each entry is copied from the table that owns it, keyed by (source, source_ref), so a sync can run any number of times without double counting. The price used is stored on the row (usd_price, usd_basis) and never re-computed, so a past total does not move when the market does.

Reconciliation

An hourly cron (/api/cron/revenue-ledger-reconcile, 11 * * * *) re-derives each source total from the owning table and compares it with the ledger (database drift), and checks recent entries' signatures on chain (verified, mismatch or not found). The console shows the latest run and a verified count. Chain history reaches back REVENUE_CHAIN_HISTORY_DAYS days (default in code). A drift or mismatch raises a notification.

Projection

The projection is the trailing revenue (default 30 days) divided by the days covered, held flat for 30 days, with no growth assumed. It needs at least 7 days of history and 3 income entries in the window and says so when it has too little to project.

Public earnings page

Off by default. The owner switches it on per agent in the console. The public view carries entries with their transaction links and the totals, and leaves out counterparty addresses and internal ids. Switching it off removes it immediately.

Reinvest rules

A rule says what share of each period's income goes where.

Leg What it does
Model credits USDC from the agent wallet to the platform deposit wallet, then your credit balance is credited from that signature
Tools budget The same deposit, then the credits move into a named x402 payment session's budget
DCA into the agent's own coin A pump.fun buy of the agent's own coin through the standard trade pipeline

The base is the last complete period (day, week or month, UTC) of revenue, or revenue plus realised trading profit.

Safety, in the order it bites:

  1. A rule only runs after the owner confirms its exact terms in a signed-in browser. The confirmation table lists every destination, asset, chain, amount and both caps. An API key or agent token cannot confirm (POST /rules/:id/confirm is session-only).
  2. Any edit changes the rule hash and clears the confirmation.
  3. A per-run cap and a lifetime cap scale every leg by the same factor, so the split ratios survive the cap. Below the minimum run size nothing executes.
  4. Each period runs once. The run row is unique on (rule, period) and every leg has its own idempotency key, so a retry never sends twice.
  5. Every leg passes the same spend guards as any agent spend. A guard that needs the owner parks the leg in the approvals inbox instead of failing.
  6. Repeated failures pause the rule and notify the owner.

A test run plans the next run and paper-trades the buys. Nothing is sent. Every real run leaves a receipt with its legs, transaction signatures and approval state, shown on the console under the rule.

An hourly cron (/api/cron/revenue-reinvest, 37 * * * *) runs due rules.

API

All under /api/revenue. Owner routes take a session, API key or OAuth token with wallet:read (agents:write for settings).

Method and path Purpose
GET /public/:agentId Public earnings, only when the owner switched them on
GET /sources The sources and how each is calculated
GET /ledger?agent_id&period&from&to Totals by source and period, projection, unclaimed memo, chain checks, reconcile status
GET /entries?agent_id&source&before&limit Ledger rows, each with its explorer link
GET /export?format=csv|json Every row for the scope
GET /reconcile Latest reconcile run
GET /sessions Active Solana payment sessions, targets for a tools-budget leg
POST /sync Bring the ledger up to date now
GET/PUT /agents/:id/settings The public toggle
GET/POST /rules, PATCH/DELETE /rules/:id Manage rules
GET /rules/:id/preview The confirmation table for the rule's current terms
POST /rules/:id/confirm The explicit yes (session only), body { hash }
POST /rules/:id/pause, POST /rules/:id/test-run Pause, or paper-run
GET /runs?agent_id&rule_id Run receipts

Files

  • Pure logic: api/_lib/revenue-ledger-core.js. Database and sync: api/_lib/revenue-ledger.js. Reconcile: api/_lib/revenue-reconcile.js. Rules and runs: api/_lib/revenue-reinvest.js. Routes: api/_lib/revenue-routes.js, mounted at api/revenue/[...route].js.
  • Crons: api/cron/revenue-ledger-reconcile.js, api/cron/revenue-reinvest.js.
  • Migration: api/_lib/migrations/20261023170000_revenue_ledger.sql.
  • Pages: pages/earnings.html with src/earnings-page.js, src/earnings-chart.js, src/earnings.css; public pages/agent-earnings.html with src/agent-earnings-page.js.
  • Tests: tests/revenue-ledger.test.js.