Webapp analytics and charting API

Category: webapp Verified against: structs-webapp 08e13e2 (2026-09-30) Base URL: ${webappBaseUrl} (default: http://localhost:8080, public guild webapp: http://crew.oh.energy)

These routes exist to draw the board, not to look up one entity. Leaderboards, inventory, bank history, time-series aggregates, market snapshots, and census counts all return chart-ready rows: amounts as strings, optional meta.height for the indexer tip, and (where noted) ?bucket=1h|1d windows over the last 30 days.

They still sit behind a session cookie. Public prefixes remain /api/auth/*, /api/guild/this, /api/timestamp, /api/setting. /api/block needs auth.

Envelope: { "success", "errors", "data" } plus optional meta.height and total. Unwrap data after success. Protocol: webapp-api-protocol. Per-entity lookup routes stay on their entity pages; this file is the charting map.

Limits (PaginationLimits in structs-webapp):

What to call for a dashboard

_p fields are base-precision strings (ualpha, milliwatt, …). Unsuffixed twins are truncated display values. Read /api/denom for precision_suffix, unit scales, and .infused / .defusing state suffixes.

Units and lookup

GET /api/denom

• ID: webapp-denom

Unit registry: ualpha and ore, plus every uguild.{guild_id} (optional guild_meta.denom JSON scale). Also state_suffixes, unknown_denom, energy base (milliwatt / watt, exponent 3), and precision_suffix: "_p". data.amounts is "string"; counts and ratios are numbers.

GET /api/resolve?q=

• ID: webapp-resolve

Required q. Object key (N-M) returns one typed row. Bech32 ≥32 chars looks up player_address. Anything else is ILIKE on player username, guild name/tag, substation name. Cap PaginationLimits::BATCH_IDS_MAX (200). address (8-N) and infusion (7-N) are not addressable by object key — object is null.

GET /api/objects?ids=

• ID: webapp-objects

Comma-separated object keys, same typed fetch as resolve. Cap 200 ids (RegexPattern::IDS); more than that is 400. Projections are explicit column lists, not SELECT *.

Resolvable types: guild, player, planet, reactor, substation, struct, allocation, fleet, provider, agreement.

Leaderboards

GET /api/leaderboard/{kind}

• ID: webapp-leaderboard

kind ∈ player|guild|reactor|substation|provider. Query: order (allowlisted per kind or 400 order_invalid), limit (default 50, clamp 1–10000).

Player also has username, guild_id. Height stamped from api_refresh_state for that leaderboard model.

Inventory and guild banks

There is an HTTP bank read. Mint/redeem/convert remain chain txs; balances and ratios come from these catalog tables.

GET /api/inventory/denom/{denom}/page/{page}

• ID: webapp-inventory-by-denom

Optional ?limit=. Rows from structs.api_inventory: owner_type, owner_id, denom, balance (text), order balance DESC.

GET /api/inventory/owner/{owner_type}/{owner_id}

• ID: webapp-inventory-by-owner

Same table, one owner. owner_type is a structs.object_type enum value (player, guild, …).

GET /api/guild-bank

• ID: webapp-guild-bank

Every row in structs.api_guild_bank: guild_id, denom, collateral, supply (text), ratio. This is the live collateral picture that used to require a bank-module query.

GET /api/guild-bank/{guild_id}/history

• ID: webapp-guild-bank-history

Optional ?bucket=1h (else day). Last 30 days. Ledger actions minted|burned|infused|defusion_completed on uguild.{id} and uguild.{id}.%. Rows: bucket, action, denom, volume (signed text; debits negative).

Markets

GET /api/provider/market

• ID: webapp-provider-market

Every provider with substation owner, inferred guild_id, alpha_equivalent_rate_p (guild-token rates converted via api_guild_bank.ratio; ualpha/alpha pass through), and committed_capacity of still-open agreements. Height stamped from the guild_bank refresh model.

GET /api/agreement/owner/{owner}/market

• ID: webapp-agreement-owner-market

That owner’s agreements plus blocks_remaining and escrow_remaining (capacity × rate × remaining blocks, text). owner is a player id.

Time series

Raw per-object range still lives on stat.md. Charting additions:

• Optional ?bucket=1h|1d on the per-object range: date_trunc + AVG(value). With a bucket the max window is 30 days (2592000 s); without it the max stays 7 days.
• Optional ?limit= on that range (default 100, max 10000).

GET /api/stat/{metric}/aggregate/range

• ID: webapp-stat-aggregate-range

Required query: object_type, start_time, end_time (unix seconds). Optional bucket (1h default, or 1d). Max window 30 days. 400 object_type_start_time_end_time_required if any of the three is missing.

Reads precomputed LOCF hourly snapshots from structs.stat_rollup (sum, population, samples; avg is sum / population when population > 0). Empty buckets are absent. The unfinished current hour is not present until the :02 cron writes it. ?bucket=1d takes the last hourly row of each day and sums that day’s samples.

Family-two metrics still require their entity object_type (structs_load → player, connection_* → substation, struct_health/struct_status → struct).

GET /api/planet-activity/stats

• ID: webapp-planet-activity-stats

Optional category, bucket (1h or 1d; omit = daily). Last 30 days from planet_activity_hourly / planet_activity_daily. Rows: bucket, category, count.

GET /api/planet-activity/player/{player_id}/stats

• ID: webapp-planet-activity-player-stats

Daily only (400 bucket_invalid on 1h). Optional category, role (attacker|target|owner|planet_owner|defender|protected|fleet_owner). Last 30 days from planet_activity_player_daily. Rows: bucket, category, role, count.

The matching event feed is GET /api/planet-activity/player/{player_id}/page/{page} (?category=, ?role=, ?since_height=, ?order=asc|desc). See planet-activity.md.

GET /api/ledger/stats

• ID: webapp-ledger-stats

Optional bucket, denom. Last 30 days. Rows: bucket, action, denom, volume (text), count.

Power, raids, census

Entity pages that own the non-charting routes: player, planet, struct, fleet, ledger, work, system, grid, agreement, provider, planet-activity, stat.

Guild banking economics: guild-banking.md.