Skip to main content
langwatch/agent-billing-demo is a deliberately small agent-platform SaaS: customers sign up, create agents, and chat with them. The platform meters every LLM call and rebills its customers, with zero metering code of its own. It exists so you can see the whole metering and rebilling pattern running, then copy it.
Point your coding agent at the repo as the canonical integration example for gateway provisioning, webhook ingestion, and budgets. Every file is written to be copied from, and the README carries the same contracts these docs document.

​
What it demonstrates

  • Provisioning: customer signup mints one virtual key (the tenant boundary) and attaches a hard cap, a soft cap, and an attributed-user template, four REST calls.
  • The request path: the chat calls the gateway on the OpenAI wire with the user field set. That one field is all the attribution the billing pipeline needs.
  • Billing: meters fed exclusively by LangWatch’s signed webhooks, with signature verification, dedup by envelope id, and settled-row supersession (replace, never sum). If the numbers on screen are right, the pipeline works end to end.
  • Reconciliation: checksum comparison against spend-summaries, cursor diff against spend-events on divergence.
  • Breach UX: the 402 meta’s budget_scope drives two different messages, “your allowance ran out” versus “your workspace’s budget ran out”.
  • Period close: a reset button drives POST /budgets/:id/reset on the manual windows; recorded spend never changes.

​
The app

A React + Tailwind single page app, built by Vite and served by the Express server that also hosts the API and the webhook receiver, all on port 4100. It has a landing page, a sign-up page, a customer dashboard, a developer panel, and a SaaS owner console.

​
Sign-up provisions a real tenant

One POST mints the virtual key and attaches three real budgets to it: The form then redirects into the dashboard with a success toast naming the caps it just created, so the customer sees the outcome instead of a spinner. A workspace name that is already taken comes back as a structured 409 carrying code: "customer_exists" and an offer to open the existing workspace, never a database error.

​
The dashboard is the product

Each signed-in customer creates agents (name, system prompt, model) and chats with them. Chat is streamed through the gateway over Server-Sent Events, on that customer’s virtual key, with the seat’s email in the OpenAI user field. A usage meter at the bottom of the page shows live spend against the real caps. Switching workspace swaps agents, transcripts, meter and event feed together, so nothing is shared between tenants but the code.

​
The app receives its own billing events

The app hosts its receiver in-process at POST /webhooks/langwatch. It verifies the X-LangWatch-Signature HMAC over the raw request bytes, dedups by envelope id, and answers 2xx only once the batch is stored. Ingested events drive the meters and stream to the browser over Server-Sent Events, so a delivered event moves the meter without a page refresh.

​
The owner console

/admin is the SaaS owner’s side of the same data: every customer with their virtual key, caps, spend and request counts, plus the actions a platform operator needs.
  • Close billing period, per customer, resets the manual-window caps only. The month-window seat allowance is left to roll over on its own, because closing the company’s books does not hand every seat a fresh personal allowance, and recorded spend is never mutated.
  • Adjust caps, per customer, calls the budgets update API. Raising a breached cap admits traffic again with the books intact.
  • Webhook receiver health: whether this app’s endpoint is registered, and how many events it has ingested.
  • A live feed of billing events, signed deliveries as they arrive.

​
The developer panel

/developer keeps the raw signed envelopes one click away, expandable as JSON, next to the request-path and webhook-contract snippets that are the whole integration.

​
Breaches read as sentences

A 402 from the gateway surfaces as a friendly UI state, branched on the budget_scope meta:
  • virtual_key: “Your workspace has reached its AI budget for this period.”
  • attributed_user: “You have used up your personal AI allowance for this period.”
The message you tried to send is handed back for a retry.

​
The integration surfaces, twice

Every surface you would copy exists in both languages, self-contained: The app’s own receiver lives at app/src/webhooks.ts and implements the identical contract as the standalone one. Both standalone receivers run side by side against the same LangWatch instance, each registered as its own endpoint with its own secret; every request lands in both ledgers, signed and deduped, which doubles as a demonstration that delivery is consumer-agnostic.

​
Running it

You need a LangWatch instance (local dev, self-hosted, or cloud) with an enterprise license for the webhook surface, and an organization API key carrying the gateway and webhook permissions.
Create a workspace, add an agent, and chat: the usage meter fills from the billing events the gateway delivers to that same process. Optional extras:
The full walkthrough, environment variables, and sequence diagrams live in the repo README.

​
See also