Skip to content

Illustrative data

v0.3.0-alpha · experimental

Know your margin.Not just your tokens.

AgentMargin attributes AI inference cost and revenue to the same customer, so you can see who's profitable, who isn't, and where the cost is still unknown.

Star on GitHub
Illustrative chart: Customer A +$17.00, Customer B −$13.00 (cost above the $29 revenue line), Customer C unknown
  • MIT License
  • TypeScript
  • PostgreSQL
  • Metadata-only
  • CI: E2E + secret scan

01 · The problem

Token counts aren't margins.

Most model dashboards tell you how many tokens you spent. They don't answer the question that decides your pricing: which customer is profitable?

AgentMargin brings usage and revenue records together for the same customer, then separates the cost it knows from the cost it doesn't.

Illustrative AI contribution per customer
CustomerRevenueAI costContribution
Customer A$29.00$12.00$17.00
Customer B$29.00$42.00−$13.00

contribution = revenue − tracked AI cost

Illustrative. AI contribution = revenue − tracked AI inference cost. Not gross or net profit.

02 · How it works

From completed request to contribution per customer.

  1. 01

    Request completes

    Your app finishes an OpenAI call as usual. AgentMargin is a post-call helper, not a proxy or automatic capture.

  2. 02

    SDK records usage

    One call maps the completed result to a usage event: model, token counts, response ID. Prompts and outputs never leave your app.

  3. 03

    Local API → PostgreSQL

    The authenticated API on 127.0.0.1 stores workspace-scoped, idempotent records. Retrying the same response is a no-op.

  4. 04

    Contribution by customer

    Record revenue for the same customer and /v1/analytics returns contribution, or holds it back when cost is unknown.

03 · Architecture

Five layers. All of them yours.

Everything runs on your machine. Usage and revenue meet in one local workspace.

  1. Your app

  2. AgentMargin SDK

  3. Local API (127.0.0.1)

  4. PostgreSQL

    Workspace-scoped, idempotent records in integer USD microdollars.

  5. Dashboard

04 · What works today

Built for numbers you can trust.

Cost engine

Versioned model prices with input, cached and output token rates, computed in integer microdollars.

Trustworthy coverage

Reported, estimated and unknown cost, kept apart. Incomplete data means no final margin.

Customer attribution

Usage and revenue land on the same customer. Workspace-scoped and idempotent.

05 · Plugs into your stack

Lives in your app. Runs on your machine.

OpenAI helpers

Map a completed Responses or Chat Completions result to an event in one call.

Workspace pricing

Append-only price versions with UTC dates and a full audit trail.

Local dashboard

Compact dark customer economics, cost comparison, coverage and a pricing editor.

Local API + TypeScript SDK

Authenticated endpoints for events, revenue, analytics and workspace model pricing, bound to 127.0.0.1.

  • Bearer API keys, workspace-scoped
  • Binds to 127.0.0.1 by default
  • Source-first SDK · not on npm yet

When AI cost is unknown

A missing price is not a $0 expense.

If a model price is unknown, AgentMargin says so and holds back the final margin instead of showing you a comforting zero.

06 · Developers

One call per request.

  • TypeScript SDK

    Source-first client for events, revenue and analytics. Not published to npm yet.

  • Metadata only

    Model, token counts and response ID. No prompts, no generated text.

  • Trusted customer ID

    Resolve the customer from server-side auth, never from browser input.

  • Next.js App Router recipe

    A route-handler sketch that tracks usage after the OpenAI call returns.

Read the docsNext.js recipe →
// app/api/chat/route.ts
import OpenAI from "openai";
// source-first SDK: link the local workspace package (not on npm yet)
import { AgentMarginClient } from "@makinohq/agentmargin";

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY! });
const margin = new AgentMarginClient({
  endpoint: process.env.AGENTMARGIN_ENDPOINT ?? "http://127.0.0.1:8787",
  apiKey: process.env.AGENTMARGIN_API_KEY!,
});

const response = await openai.responses.create({ model, input, store: false });

// usage metadata only: no prompt, no generated text
await margin.trackOpenAIResponse(response, trustedCustomerId);
// GET /v1/analytics · fictional customer
Customer B cus_bLoss
Revenue
$29.00
Tracked AI cost
$42.00
Contribution
−$13.00

margin −44.83% · 0 unknown-cost events

07 · Accuracy & security

Precise by default. Local by design.

Storage
USD microdollars: 1 USD = 1,000,000 micros
Zero cost
Valid when the provider reports it
Bind
127.0.0.1 by default
Cached tokens
A subset of input tokens, never double-counted
Missing price
Never zero. It stays unknown.
Data
Usage metadata only

08 · Quickstart

Fictional customers. Real dashboard.

Docker or OrbStack plus Node 22.18+. The demo seeds three fictional customers. No OpenAI account or real customer data required.

Demo guide ↗

Stop: npm run demo:stop · Reset (deletes demo data): npm run demo:reset

npm run demo
Build dashboardReact · local builddone
PostgreSQL readyDocker · 127.0.0.1done
Seed 3 fictional customersno real datadone
Dashboard is live127.0.0.1:8787/dashboardOpen

Docker or OrbStack · Node 22.18+ · no OpenAI account needed

Open source · MIT · v0.3.0-alpha

Building with AI? Know which customers pay for it.

Practical feedback matters more than stars. Tell us what data you have and what you wish you knew.

Share a use caseStar on GitHub