Stats and Wallet

Stats & Wallet

Five read-only tools. get_stats and get_token_price work with the ordinary read scope; the three wallet tools need the opt-in finance scope. None of them can change anything — no generation, no organising, and, by construction, no money movement.

get_stats

How active have I been this month, and what did it cost?

One consolidated read. The first line is a ready-made summary the agent can relay verbatim:

1 284 creations (23 this week, streak 6d) · 4.2/50 GB · 30d: 210 gens, $14.30 · stats 12min old

The JSON block underneath has three sections:

• overview — storage (used/quota, split by images, video, uploads, trash), counters (total and this-week creations, folder counts, trash), the daily creation streak, smart-collection counts, and per-tool recents (latest creation ids per generation tool — a natural "continue where I left off" hook).
• generations — volume and spend over the window (days: 30 default, or 90): totals, per-day series, per-tool split, and a per-origin split between machine (work made through API keys — SDK, MCP, REST) and studio (the web app). The quickest way to see what your automation costs versus your hands-on work.
• top — your most-used references (each with the tool and settings you usually pair it with), top styles and top keywords. Agents use topRefs to re-run "the usual" without hardcoding anything.

The numbers come from a server-side cache — cheap enough to poll. Its age is reported, and a stale cache refreshes itself in the background; re-ask in a moment for fresher numbers.

Wallet reads

get_wallet_status

What's my balance and tier right now?

One snapshot: $2DAI token balance, USD credit (what generations burn), and the account's effective tier together with the four signals it derives from — an explicit assignment, the staking watermark, the 24-hour hold watermark, and what the live wallet value qualifies for; the highest wins. Also flags anything in flight: a pending withdrawal, a pending swap, an active staking lock.

get_lock

Staking-lock lifecycle: none, active (with time remaining), or expiring-soon (under 24 hours left). Locks are created and released in the dashboard — never through this server.

get_wallet_history

Four kinds under one tool:

kind	Returns
transactions	Deposits, withdrawals and swaps, newest first, paged (limit 5–50, page 0-based)
balance	$2DAI balance chart points over a window (limit in days, 7–365, default 90)
credit	USD-credit chart points, same windowing
sources	Where credit came from and went over days (default 30): accrued, bonuses, swapped in, spent on generations

get_token_price

The cached $2DAI/USD quote with its staleness. Machine calls never trigger a live price refresh — you get the platform's cache and its age, so treat the number as indicative. Needs only read, because it carries no account data. When no cached quote exists yet, the tool says so — retry in a few minutes rather than treating it as a zero price.

The finance scope

Wallet data is more sensitive than your creation library, so it follows two deliberate rules:

• Opt-in, never default. The key dialog never pre-selects finance — a key only carries it if you ticked it at mint time, and existing keys never gain it retroactively. Mint a dedicated key when you want an agent seeing wallet data.
• Read-only, structurally. There is no deposit, withdraw, swap or lock operation anywhere on the machine surface — not on this server, not on the underlying API-key surface. Money mutations live in the dashboard, behind its own confirmations. A leaked finance key can see your numbers; there is no call it could make to move funds.

Two reads sit deliberately outside the scope: get_token_price (above) and the tier catalogue the wallet tools use for pretty tier names — neither carries account data.

When the scope is missing

Nothing crashes. A wallet tool on a key without finance returns a plain, actionable error the agent can relay:

Wallet data needs the opt-in "finance" scope, which this API key does not carry. Enable it on the key (or create a finance-scoped key) at 2dai.io → Dashboard → Integrations → API keys, then retry.

If you never intend an agent to read wallet data, simply never grant the scope — the other 20 tools are unaffected.