# WallMRR — Complete Specification & Technical Reference > WallMRR is a TV dashboard for subscription revenue. It connects to RevenueCat, Stripe, Polar, DataFa.st or Stalkr.ai, normalizes the numbers into one definition of MRR and one display currency, and shows them on any screen with a browser, updating as sales land. It is free for one project. ## 1. Product Overview & Architecture WallMRR turns televisions and secondary displays into ambient, always-on revenue telemetry walls for founders and engineering teams. It connects directly to payment gateways and subscription management platforms, computes normalized recurring metrics, and delivers sub-second sale celebrations to physical screens. ### Core Architectural Invariants - **I1 (Pre-computed snapshots):** Screens and client devices render finished, pre-computed snapshots. TV clients possess no provider knowledge, credentials, or client-side calculation logic. - **I2 (Zero client-side provider calls):** Client requests never cause outbound provider API calls. Device endpoints read strictly from Postgres. - **I3 (Degraded beats broken):** When an upstream provider suffers an outage, the screen preserves the last verified number with an honest stale marker. The screen never displays an error page, spinner, or blank display. - **I4 (Deterministic money):** All monetary figures are stored internally in integer minor units (cents, pence, fils) and converted once into the project display currency using daily reference rates. The exact calculation definition is printed under the number on the display. --- ## 2. Supported Payment Providers & Metric Normalization ### Shipped Gateways - **RevenueCat:** MRR, revenue, subscribers, trials, active users - **Stripe:** MRR, ARR, subscribers, new customers - **Polar:** MRR as Polar computes it, ARR, subscribers, revenue - **DataFa.st:** Live visitors, overview, revenue attribution - **Stalkr:** Brand mentions, sentiment, tracked keywords - **Webhooks:** sale events from anything that can send JSON ### Upcoming Roadmap Gateways - Lemon Squeezy - Paddle ### Normalization & Calculation Rules #### RevenueCat - **Title:** RevenueCat TV dashboard — WallMRR - **Metrics shown:** Monthly recurring revenue (mrr), Revenue, last 28 days (revenue_period), Active subscribers (active_subscriptions), Active trials (active_trials), New customers, last 28 days (new_customers), Active users, last 28 days (mau) - **Calculation Definition:** MRR on the wall is RevenueCat's own monthly recurring revenue for the project, converted once into your display currency and marked as converted when it was. Trials excluded, as RevenueCat excludes them. The definition is printed under the number on the TV. - **Key & Scopes:** Paste a RevenueCat secret API key with read access to your project. WallMRR reads the project overview; it never writes to RevenueCat. - **Roadmap / Not Yet:** - Numbers update by sync — every five minutes on Free, faster on Pro — not by RevenueCat webhooks yet. - Sale celebrations arrive through the WallMRR webhook URL; ARR, churn and time series from RevenueCat are next. - One connection per provider — a second account of the same provider is refused. Free walls take one data source; Pro and Studio connect them all, and revenue from two billing providers is added together on the wall. #### Stripe - **Title:** Stripe TV dashboard — WallMRR - **Metrics shown:** Monthly recurring revenue (mrr), Annual recurring revenue (arr), Active subscribers (active_subscriptions), New customers, last 28 days (new_customers), Revenue, last 28 days (revenue_period) - **Calculation Definition:** MRR on the wall is the sum of your active and past-due Stripe subscriptions normalized to a month: annual and other intervals divided down, amount-off and percent-off coupons applied, every currency converted once into your display currency and marked as converted. Trials excluded. The definition is printed under the number on the TV. - **Key & Scopes:** Paste a restricted Stripe API key with read access to subscriptions, customers and charges. WallMRR only reads; it cannot create a charge or touch a customer. - **Roadmap / Not Yet:** - Churn is next. - Sale celebrations arrive through the WallMRR webhook URL; reading Stripe webhooks directly is next. - One connection per provider — a second account of the same provider is refused. Free walls take one data source; Pro and Studio connect them all, and revenue from two billing providers is added together on the wall. #### Polar - **Title:** Polar TV dashboard — WallMRR - **Metrics shown:** Monthly recurring revenue (mrr), Annual recurring revenue (arr), Active subscribers (active_subscriptions), Revenue, last 28 days (revenue_period) - **Calculation Definition:** MRR on the wall is Polar's own monthly recurring revenue: every ongoing subscription's net amount normalized to a month, yearly plans divided by twelve, discounts applied, tax excluded, past-due subscriptions counted until they end. Trials excluded, as Polar excludes them. Revenue over 28 days is the order subtotal before tax and Polar fees, as Polar reports it. Both are shown in your wall's display currency (USD today). The definition is printed under the number on the TV. - **Key & Scopes:** Create an organization access token in Polar with only the metrics:read and organizations:read scopes and paste it here. WallMRR reads your metrics; it never writes to Polar and never sees a customer. - **Roadmap / Not Yet:** - Trials and new customers are not on the wall: Polar's metrics API has no such figure, and WallMRR does not guess. - An organization that bills in a currency other than USD shows subscriber counts only, until WallMRR has confirmed which currency Polar reports its metrics in. - Numbers update by sync — every five minutes on Free, faster on Pro — not by Polar webhooks yet. - Sale celebrations arrive through the WallMRR webhook URL; reading Polar webhooks directly is next. - One connection per provider — a second account of the same provider is refused. Free walls take one data source; Pro and Studio connect them all, and revenue from two billing providers is added together on the wall. #### DataFa.st - **Title:** DataFa.st TV dashboard — WallMRR - **Metrics shown:** Attributed revenue, last 28 days (attributed_revenue), Live visitors (live_visitors), Visitors, last 28 days (visitors), Pageviews, last 28 days (pageviews), Sessions, last 28 days (sessions), Bounce rate (bounce_rate), Conversion rate (conversion_rate) - **Calculation Definition:** Attributed revenue is the 28-day revenue DataFa.st attributes to your traffic, normalized into your display currency. It is the same money your billing provider reports, so it is shown on its own and never added to your revenue or MRR — those come from Stripe, Polar or RevenueCat, trials excluded. Live visitors and 28-day traffic stats are read directly from DataFa.st. The definition is printed under the number on the TV. - **Key & Scopes:** Paste a DataFa.st website API key (df_...) or account token (dft_...). WallMRR reads your analytics overview; it never writes to DataFa.st. - **Roadmap / Not Yet:** - Numbers update by sync — every five minutes on Free, faster on Pro — not by DataFa.st webhooks yet. - Sale celebrations arrive through the WallMRR webhook URL; direct goal tracking and breakdown charts are next. - One connection per provider — a second account of the same provider is refused. Free walls take one data source; Pro and Studio connect them all, and revenue from two billing providers is added together on the wall. #### Stalkr - **Title:** Stalkr TV dashboard — WallMRR - **Metrics shown:** Mentions, last 30 days (mentions_period), Mentions today (mentions_today), Positive sentiment % (positive_sentiment_pct), Tracked keywords (tracked_keywords), Sentiment score (sentiment_score) - **Calculation Definition:** Mentions and sentiment on the wall are Stalkr's 30-day social listening analytics normalized across connected social networks. Trials excluded, as Stalkr monitors brand mentions rather than recurring billing subscriptions. The definition is printed under the number on the TV. - **Key & Scopes:** Paste a Stalkr API key (stalkr_sk_...) from your developer dashboard. Optionally provide a project ID to monitor a specific project. WallMRR reads your mentions and analytics snapshot; it never writes to Stalkr. - **Roadmap / Not Yet:** - Numbers update by sync — every five minutes on Free, faster on Pro — not by Stalkr webhooks yet. - Alert celebrations arrive through the WallMRR webhook URL; raw mention streams and author drill-downs are next. - One connection per provider — a second account of the same provider is refused. Free walls take one data source; Pro and Studio connect them all, and revenue from two billing providers is added together on the wall. --- ## 3. Pricing & Feature Matrix Billed securely on the web through Polar. Never priced per seat. ### Tier: Free ($0/forever) - Description: Perfect for your first project. - Features: - 1 project, 1 paired screen - 1 data source - Public shareable wall (branded) - Updates every 5 minutes - 7 days of history ### Tier: Pro ($12/mo / $119/yr) - Description: For a founder with a few products. - Features: - 3 projects, 2 paired screens - All data sources - Instant sale moment from Stripe, RevenueCat, Polar, or your webhook URL — confetti and a chime - 13 months of history - All themes, custom layouts, your logo on the wall, no WallMRR branding - MCP access — Claude, Cursor, your own agents ### Tier: Studio ($29/mo / $290/yr) - Description: For a portfolio, or a small team with a wall. - Features: - Unlimited projects, 5 paired screens - Portfolio total across every project — coming soon - Everything in Pro - Public API — coming soon - Priority support ### Early Supporter Lifetime Deal (Public Beta Special) - Price: $249 one-time payment. - Terms: Full Pro tier entitlements forever for early adopters (3 projects, 2 paired TV screens, instant sale moments from Stripe, RevenueCat, Polar, or your webhook URL, all themes, no watermarks). Limited to first 100 supporters. --- ## 4. REST API Reference The public API (API keys, part of Studio) is coming soon. These are the endpoints the WallMRR dashboard uses today, authenticated with a signed-in session; for agents, the MCP server below works now. ### Endpoints - **GET /v1/dashboard/projects**: List all configured projects, active themes, and connection statuses. - **GET /v1/dashboard/projects/{projectId}/snapshot**: The pre-computed snapshot a paired screen renders: MRR, ARR, subscribers and each metric's day-over-day delta, in integer minor units, with each metric's source and freshness. - **PUT /v1/dashboard/projects/{projectId}/layout**: Update the active screen layout mode (Monolith or Grid), active color theme, and enabled metric tiles. - **GET /v1/tv/snapshot**: Device token authenticated endpoint returning the pre-computed snapshot for display hardware. - **POST /v1/tv/pair/start**: Called by the TV to get an ephemeral six-character pairing code. - **POST /v1/tv/pair/claim**: Session-authenticated; claims a six-character code for one of the founder's projects. --- ## 5. Model Context Protocol (MCP) Server WallMRR provides an official Model Context Protocol (MCP) server allowing Claude, Cursor, and autonomous AI agents to interact with paired displays. Tool calls are included in the Pro and Studio plans: - **wallmrr_metrics_get**: Retrieve real-time subscription telemetry (MRR, ARR, active subscribers, daily delta). - **wallmrr_metric_push**: Push custom revenue metrics or offline adjustments directly to your project wall. - **wallmrr_event_emit**: Trigger screen animations (confetti explosions, audio chimes, celebratory banners) for major milestones or enterprise sales. - **wallmrr_projects_list**: List all account projects and paired screens. - **wallmrr_goal_set**: Update active revenue milestones or monthly targets displayed on the TV wall. - **wallmrr_screen_message**: Display temporary ambient banner notifications across paired TV screens. --- ## 6. Hardware Kiosk Deployment & TV Screen Health ### Zero-App Browser Display - Open `https://wallmrr.com/tv` on any browser (LG WebOS, Samsung Tizen, Amazon Fire TV Stick, Google TV). - Pair with your six-character code at `https://wallmrr.com/pair`. ### Dedicated $35 Raspberry Pi Kiosk Setup - Configure Raspberry Pi OS in kiosk mode using Chromium with flags: `--kiosk --noerrdialogs --disable-infobars --check-for-update-interval=31536000 https://wallmrr.com/tv` - Auto-reboot cron job and hardware acceleration enabled for smooth animations. ### OLED Panel Burn-in Protection Math (D6 Specification) - Global coordinate micro-shift: translates the entire viewport coordinate plane by ±8px / ±6px over a 240-second four-corner cycle (57-second hold, 3-second move). - 20-minute circadian brightness cycle: subtle 2% luminance breathing preventing sub-pixel phosphor exhaustion on 24/7 displays. --- ## 7. Field Guides & Articles ### Why your MRR belongs on a TV screen, not in a browser tab (September 6, 2026 · 4 min read) - Slug: /blog/why-your-mrr-belongs-on-a-tv-screen - Excerpt: Dashboard fatigue kills focus. Having your metrics rendered on an ambient, physical screen turns passive anxiety into relentless momentum. ### How We Built WallMRR: Next.js 15, Go, PostgreSQL, and Low-Power Hardware (September 7, 2026 · 6 min read) - Slug: /blog/how-we-built-wallmrr - Excerpt: A peek under the hood: six-character pairing codes, device tokens, sub-second polling, burn-in prevention, and why we chose Go for real-time telemetry. ### Calculating True MRR Across Stripe, Polar, and RevenueCat (September 8, 2026 · 5 min read) - Slug: /blog/calculating-true-mrr-across-multiple-gateways - Excerpt: Why naive summing breaks down: normalized subscriptions, minor units, foreign exchange rates, trial exclusions, and handling webhook idempotency. --- ## 8. Frequently Asked Questions ### Q: What is WallMRR? WallMRR is a TV dashboard for subscription revenue. It connects to RevenueCat, Stripe, Polar, DataFa.st or Stalkr.ai, normalizes the numbers into one definition of MRR and one display currency, and shows them on any screen with a browser, updating as sales land. It is free for one project. ### Q: Do I need a TV app? Not today. The wall is a web page: open wallmrr.com on the TV's browser, or cast a tab from your laptop. Native Android TV and Apple TV apps are in development. ### Q: Which sources work right now? RevenueCat, Stripe, Polar, DataFa.st and Stalkr, plus a webhook URL any service can send a sale to. Lemon Squeezy and Paddle are next. ### Q: Is my Stripe key safe? Each key is encrypted at rest with a key of its own, is never returned by the API, and never reaches the TV. The screen only ever receives finished numbers. Where your provider offers a restricted, read-only key, use one. ### Q: How do you calculate MRR? Normalized monthly recurring subscription revenue: annual plans divided by twelve, active and past-due subscriptions counted, trials excluded. That definition is printed under the number, and one display currency is used for everything on the wall. ### Q: What happens when a provider goes down? The last known numbers stay on the screen with a stale marker. The wall never shows an error screen, a spinner or a blank. ### Q: Can I share my wall without sharing exact numbers? Yes. A public wall can show exact amounts, amounts rounded down to two figures, or trends only. The badge says which provider the numbers come from and when they last updated. ### Q: What does Free include? One project, one source, one paired screen, a branded public wall, and updates every five minutes. It stays free. --- ## Canonical Links - Website: https://wallmrr.com/ - Pricing: https://wallmrr.com/pricing - Blog: https://wallmrr.com/blog - Documentation: https://wallmrr.com/docs - Hardware Guides: https://wallmrr.com/learn - MCP Server Guide: https://wallmrr.com/mcp - REST API Reference: https://wallmrr.com/api - TV Browser Client: https://wallmrr.com/tv - Screen Pairing: https://wallmrr.com/pair