Skip to main content
langwatch/agent-billing-demo is a small agent-platform SaaS: customers sign up, create agents and chat with them. The platform meters every LLM call and rebills its customers through the LangWatch AI Gateway, with no metering code of its own. Run it to see the metering and rebilling pattern end to end, then copy the parts you need.
Point your coding agent at the repo as the reference example for gateway provisioning, webhook ingestion and budgets. The README carries the same contracts these docs describe.

​
What it demonstrates

  • Provisioning: customer sign-up creates one virtual key per tenant and attaches a hard cap, a soft cap and a per-end-user budget, in four REST calls.
  • The request path: the chat calls the gateway with the OpenAI SDK and the user field set. That field is the only attribution the billing pipeline needs.
  • Billing: meters fed only by the signed webhooks, with signature verification, dedup by envelope id, and replacement of a settled event by the completed one that follows it.
  • Reconciliation: checksum comparison against spend-summaries, cursor diff against spend-events on divergence.
  • Breach handling: error.meta.budget_scope on the 402 selects one of two messages, for the end user’s own allowance or for the workspace budget.
  • 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 opens the dashboard with a message that names the caps it created. A workspace name that is already taken comes back as a 409 with code: "customer_exists" and an offer to open the existing workspace.

​
The dashboard

Each signed-in customer creates agents (name, system prompt, model) and chats with them. The chat streams 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 caps. Switching workspace swaps agents, transcripts, meter and event feed together. The demo sends the email so the identity is readable while you watch the events arrive. In your own application send a stable pseudonymous id instead: the gateway stores the value as sent, and keeps spend events for 13 months.

​
The app receives its own billing events

The app hosts its receiver at POST /webhooks/langwatch. It verifies the X-LangWatch-Signature HMAC over the raw request bytes, dedups by envelope id, and answers 2xx 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 rolls over on its own. Recorded spend never changes.
  • 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 shows the raw signed envelopes as JSON, next to the request-path and webhook-contract snippets that make up the integration.

​
Breach messages

A 402 from the gateway shows one of two messages, selected by error.meta.budget_scope:
  • 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 stays in the input for a retry.

​
The integration files, in both languages

Every file you would copy exists in TypeScript and in Python: The app’s own receiver is app/src/webhooks.ts and implements the same contract as the standalone ones. Both standalone receivers run side by side against the same LangWatch instance, each registered as its own endpoint with its own secret, so every request lands in both ledgers.

​
Running it

You need a LangWatch instance (self-hosted or Cloud) on an Enterprise plan for the webhook endpoints, and an organization API key with the gateway and webhook permissions. See RBAC.
Create a workspace, add an agent and chat: the usage meter fills from the billing events the gateway delivers to that process. Optional:
The full walkthrough, environment variables and sequence diagrams are in the repo README.
Also check: Metering and rebilling for the cookbook this demo implements, Billing and spend events for the event payload, and Webhooks for endpoints, signatures and retries.
Last modified on September 6, 2026