---
title: "Commercial and valuation metrics, derived read-only from tables the gateway already writes: the x402 settlement journal (migration 0011), the identity plan/Stripe columns (0012), `api_keys.first_success_at` (0015) and `usage_counters` (0001)."
method: GET
path: "/admin/commercial"
tags: ["admin"]
---

# Commercial and valuation metrics, derived read-only from tables the gateway already writes: the x402 settlement journal (migration 0011), the identity plan/Stripe columns (0012), \`api_keys.first_success_at\` (0015) and \`usage_counters\` (0001).

`GET /admin/commercial`

## Request

- Base URL: `https://api.mapmap.ai`
- URL: `https://api.mapmap.ai/admin/commercial`
- Auth: HTTP bearer

Every figure here is something the database actually holds. In
particular there is **no Stripe MRR**: the gateway stores no
subscription amounts, so the response carries plan counts and lets the
console annotate them with published list prices under an explicit
estimate label. `retention_proxy` is a proxy by construction: see
[`RetentionMonth`].

## Response `200`

Settled revenue, plan distribution, activation funnel, usage mix and the month-on-month retention proxy

- CommercialResponse: Response for `GET /admin/commercial`.
  - `demo_lane` DemoLane, required: What the keyless demo lane (`SN_DEMO_RPM`) gave away. Counting only. Keyless traffic is free by design and this endpoint changes nothing about that: no quota, no block, no charge. It exists to answer the question the demo lane could not answer before, how much of the premium differentiator (truck dimensions, `hazmat`, ADR `tunnel_code`) is being served for nothing, so the enforcement decision, if it comes, is taken on evidence.
    - `calls` integer, required: Keyless calls served in the window.
    - `clients` DemoLaneClients, required: The bounded per-client view of the keyless lane. In memory only and never persisted: no client address reaches the database (`demo_usage` has no IP column). The table is hard-capped and evicted least-recently-seen-first, so a churn of one-shot demo IPs cannot leak memory, the cost is that it is a snapshot of recent talkers since process start, not a census.
      - `capacity` integer, required: The hard cap.
      - `evicted` integer, required: Clients dropped by eviction; non-zero means the table is full and the list below is a sample, not the whole population.
      - `since` string, required: RFC 3339 time the table started collecting (process start).
      - `top` DemoLaneClient[], required: Busiest clients first, at most [`DEMO_TOP_CLIENTS`].
        - `calls` integer, required: Keyless calls served to it since the process started.
        - `client` string, required: The client address the demo bucket keys on.
        - `first_seen` string, required: RFC 3339 first and last time it was seen.
        - `last_seen` string, required: RFC 3339 time of its most recent keyless call.
        - `premium_calls` integer, required: How many of those were premium-class.
        - `units` integer, required: Billable units they would have drawn if keyed.
      - `tracked` integer, required: Clients currently tracked.
    - `enabled` boolean, required: Whether the keyless lane is currently admitting traffic (`SN_DEMO_RPM > 0`). Historic counts are still reported when it is off.
    - `notional_millipence` integer, required: What those units would have listed at, in internal millipence (1,000 = 1p), priced at the entry band of each class, a NOTIONAL figure for sizing the give-away. Nothing was charged.
    - `premium` integer, required: Premium-class keyless calls in the window. Unlike [`CommercialUsageMix::premium`] this is exact, not a floor: the class is recorded by the same classifier that bills a keyed call, per request, at admission time.
    - `premium_features` DemoFeatureUsage[], required: Premium-feature combinations, busiest first; the `none` bucket is excluded (it is ordinary standard traffic).
      - `calls` integer, required: Keyless calls that engaged exactly this combination.
      - `features` string, required: Canonical feature label from [`crate::demo::DemoFeatures::label`], a comma-joined subset of `truck`, `dimensions`, `hazmat`, `tunnel_code`, `adr`, or `none`.
      - `units` integer, required: Billable units those calls would have drawn if keyed.
    - `premium_units` integer, required: Billable units of the premium-class ones.
    - `rpm_per_ip` integer, required: The configured per-client-IP rate, in requests/minute.
    - `standard` integer, required: Standard-class keyless calls in the window.
    - `top_endpoints` EndpointUsage[], required: Busiest keyless endpoints in the window.
      - `count` integer, required: Metered calls recorded to it this calendar month.
      - `endpoint` string, required: Collapsed endpoint label, e.g. `/route/v1`, `/geocode`, `/tiles`.
    - `units` integer, required: Billable units of every keyless call in the window.
    - `window_days` integer, required: Length of the trailing window these counts cover, in days.
  - `funnel` CommercialFunnel, required: Signup → key → activation → paid funnel, as counts per stage.
    - `activated_identities` integer, required: Identities with at least one key that ever had a successful metered call (`api_keys.first_success_at` set).
    - `activated_keys` integer, required: Keys with `first_success_at` set, the same activation event counted per key rather than per identity.
    - `identities` integer, required: Identities ever created.
    - `median_activation_seconds` integer, nullable: Median time from signup to first successful call, in whole seconds, across every identity that ever activated (not just a recent cohort); `null` until at least one has. Computed by the pure, tested [`crate::activation::activation_stats`].
    - `paid_identities` integer, required: Identities on a plan other than [`FREE_PLAN`].
    - `with_key` integer, required: Identities holding at least one key (revoked keys included).
  - `generated_at` string, required: RFC 3339 timestamp this snapshot was computed at.
  - `prepaid` PrepaidRevenue, required: Revenue signals the database genuinely holds: settled x402 payments, how many identities are linked to a Stripe customer, and the plan distribution. Deliberately **not** Stripe MRR: the gateway stores no subscription amounts, prices or invoices, so any monthly-recurring figure would be fabricated. `stripe_customers` and `plans` are the honest inputs, and the console multiplies plan counts by published list prices under an explicit "estimate" label. Prepaid-rail money for the commercial snapshot. Credits only, the ledger journals credits and not debits, so consumption has no time axis yet and is deliberately absent rather than approximated.
    - `consumed_this_month_pence` integer, required: Prepaid credit spent on calls this calendar month, in pence (`ledger_spend`, migration 0026). Reporting-grade: a crash between a debit and its spend row undercounts, never overcounts.
    - `month` string, required: The calendar month reported (`YYYY-MM`, UTC).
    - `other_credited_pence` integer, required: Operator/manual credits this month (every other reason), in pence.
    - `outstanding_balance_pence` integer, required: Unspent prepaid balance across all identities, in pence.
    - `settlement_failures_24h` integer, required: Per-call x402 settlements that FAILED in the last 24h. Service was already rendered when one of these fails, so anything above zero is revenue quietly leaking and worth a look the same day.
    - `stripe_credited_pence` integer, required: Card top-ups journalled this month (reasons `stripe:…`), in pence.
    - `x402_credited_pence` integer, required: Crypto top-ups journalled this month (reasons `x402:…`), in pence.
  - `retention_proxy` RetentionMonth[], required: Month-on-month retention proxy, oldest month first.
    - `active` integer, required: Identities that made at least one metered call this month.
    - `month` string, required: The calendar month (`YYYY-MM`, UTC).
    - `previous_active` integer, required: Identities active the previous calendar month (the denominator).
    - `retained` integer, required: Identities active this month that were also active the previous calendar month.
    - `retention_rate` number, double, required: `retained / previous_active` in `0.0..=1.0`; `0.0` when nobody was active the previous month.
  - `revenue` CommercialRevenue, required
    - `all_time` SettledRevenue, required: Settled x402 revenue over one window, split by asset.
      - `by_asset` AssetRevenue[], required: Per-(network, asset) totals, biggest earner first.
        - `amount_atomic` string, required: Sum of their `amount_atomic` in the asset's base units (decimal string, u128-range, so summed in Rust, never in SQL).
        - `asset` string, nullable: Asset (token contract / SPL mint); `null` when the settlement row recorded none.
        - `network` string, required: Network the settlements landed on, e.g. `base`.
        - `settlements` integer, required: Successful settlements in this bucket.
      - `settlements` integer, required: Successful settlements in the window, across every asset.
    - `last_30d` SettledRevenue, required: Settled x402 revenue over one window, split by asset.
      - `by_asset` AssetRevenue[], required: Per-(network, asset) totals, biggest earner first.
        - `amount_atomic` string, required: Sum of their `amount_atomic` in the asset's base units (decimal string, u128-range, so summed in Rust, never in SQL).
        - `asset` string, nullable: Asset (token contract / SPL mint); `null` when the settlement row recorded none.
        - `network` string, required: Network the settlements landed on, e.g. `base`.
        - `settlements` integer, required: Successful settlements in this bucket.
      - `settlements` integer, required: Successful settlements in the window, across every asset.
    - `mrr_billed_accounts` integer, required: How many identities the billed MRR is summed over.
    - `mrr_billed_pence` integer, required: Identities carrying a non-empty `stripe_customer_id`. REAL monthly recurring revenue in pence, summed from what Stripe actually charges (`subscription_state`, migration 0027): statuses that still entitle (`active`, `trialing`, `past_due`), yearly intervals normalised /12. Zero with `mrr_billed_accounts == 0` means "no data recorded yet", and the console then falls back to the labelled estimate rather than showing a false zero.
    - `plans` PlanCount[], required: Identities per plan label, biggest bucket first.
      - `identities` integer, required: Identities on that plan.
      - `plan` string, required: The plan label as stored on `identities.plan`; `NULL`/blank is reported as [`FREE_PLAN`]. Never mapped to a price here, the gateway holds no price list, so the console annotates these counts with published pricing and labels the result an estimate.
    - `stripe_customers` integer, required
    - `window_days` integer, required: Length of the trailing window used for `last_30d`, in days.
  - `usage_mix` CommercialUsageMix, required: Standard/premium call mix over the trailing window, plus the busiest endpoints. The class split reuses the overview's endpoint-label rule: `/adr/check` is the premium-by-path endpoint, everything else counts as standard. Truck/ADR calls on mixed endpoints are classified per request body at bill time and are indistinguishable in `usage_counters`, so `premium` is a floor, not an exact billing total.
    - `premium` integer, required: Premium-class calls in the window (a floor; see the type docs).
    - `standard` integer, required: Standard-class calls in the window.
    - `top_endpoints` EndpointUsage[], required: The busiest [`COMMERCIAL_TOP_ENDPOINTS`] endpoints in the window.
      - `count` integer, required: Metered calls recorded to it this calendar month.
      - `endpoint` string, required: Collapsed endpoint label, e.g. `/route/v1`, `/geocode`, `/tiles`.
    - `total` integer, required: `standard + premium`.
    - `window_days` integer, required: Length of the trailing window, in days.

## Other responses

- `401`: Missing or wrong admin token

---

[API](https://skmtc.dev/mapmap/apis/sn-gateway.md) · [All operations](https://skmtc.dev/mapmap/apis/sn-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/mapmap/apis/sn-gateway/revisions/2293be8b4c38?raw)