three.ws Billing

Export a billing period's usage line items as a ready-to-save CSV — the same charges query_usage returns, in spreadsheet form. Returns `filename` (suggested download name, e.g. three-ws-invoice-2026-06.csv), `content_type` (text/csv), `csv` (the full CSV text, columns: action,label,count,units,gross_usd,fee_usd,discount_bps with a trailing TOTAL row), `row_count`, and `preview` (the first few parsed rows as objects for a quick look). Same period selection as query_usage: pass `period` (YYYY-MM) or `from`/`to` (ISO-8601); defaults to the current UTC calendar month. Requires THREE_WS_SESSION. Read-only.

Your account's plan tier, the quota ceilings for that tier, and live usage measured against them — the "how much of my plan is left?" call. Returns `plan` (e.g. free | pro), `quotas` (max_avatars, max_bytes_per_avatar, max_total_bytes, mcp_calls_per_day — or null when the tier has no metered ceilings), and `usage` (avatar_count, total_bytes of avatar storage, agent_count, mcp_calls_24h tool calls in the last 24 hours, llm_calls_month LLM calls since the start of this UTC month). Each tool returns a `remaining` map computed from quotas − usage so an agent can see headroom at a glance. Resolved from your three.ws session; requires THREE_WS_SESSION. Read-only.

The current three.ws platform fee rate — the cut taken on marketplace sales, so an agent can reason about net vs gross before a charge settles. Returns `fee_bps` (basis points, e.g. 250 = 2.5%) and `fee_percent` (the same rate as a human string, e.g. "2.5"). Public — needs no session or credential. Read-only.

Fetch a single itemized receipt you own, in one of two forms. Pass `event_id` (numeric, from a usage line item) for a per-CHARGE receipt: action, label, units, gross_usd / fee_usd / net (with USDC atomics), discount_bps + discount_percent, and a `settlement` block (kind, ref, tx_signature, network, explorer_url, token_price_usd) plus issued_at. Pass `purchase_id` (UUID) instead for the cryptographically SIGNED receipt JSON of a confirmed skill purchase (receipt + signature + issued_at). Supply exactly one. Returns the `receipt` object and which `kind` ("charge" | "purchase") it is. Requires THREE_WS_SESSION. Read-only.

Earnings for the agents YOU own — the income side of your account economics (what you EARNED, vs what you were charged in query_usage). Returns `summary` (gross_total, fee_total, net_total in token atomics, plus payment_count, currency_mint, chain), `by_skill` (net_total + count per skill, top first), `timeseries` (net_total + count bucketed by granularity), `subscriptions` (creator-subscription income in USD — income_usd, payment_count, active_subscribers, plan_count — settled directly to your wallet, kept separate from the withdrawable pool so units never mix), `subscription_timeseries`, and `reconciliation`. Optional `agent_id` narrows to one agent; `from`/`to` set the window (default last 30 days); `granularity` is day | week | month (default day). Requires THREE_WS_SESSION. Read-only.

Your metered usage rolled up into an invoice statement for a billing period — what you were charged for, broken down by action. Returns `period_label` + `period` ({from,to} ISO), `line_items` (one per billed action: action id, human label, count, units, gross_usd, fee_usd, gross/fee/net atomics in USDC 6dp, discount_bps holder-tier discount applied), `totals` (charge_count, gross_usd, fee_usd, net_usd, currency), and `reconciliation` (total / reconciled / unreconciled / all_reconciled — whether every charge maps to a real settlement). Defaults to the current UTC calendar month. Pass `period` (YYYY-MM) for a calendar month, or `from`/`to` (ISO-8601) for an explicit window — `period` wins if both are given. For a downloadable CSV of the same line items use export_billing_history. Requires THREE_WS_SESSION. Read-only.