Hardcount docs

New here? Run the quick start, then read How it works.

Try it

1. Quick start: start Hardcount on your computer with git, Docker and a bash shell, run the demo, and see one month of token usage become an invoice, its PDF and a margin report.
2. What’s in the box: every feature, with what it does for you.
3. How Hardcount compares with four open-source billing engines, with sources, and why Hardcount exists.
4. Roadmap: what is being built now, next and later, and what Hardcount will not build. Every change, by date: CHANGELOG.
5. Versioning before 1.0: what a release can break, and where each breaking change is written down.

Understand it

1. How Hardcount works: one picture and six steps, from a usage event to a paid invoice.
2. Glossary: the words you will meet, plain meaning first.
3. How much traffic Hardcount handles: what was measured, and where one Postgres stops being enough.
4. Card payment failure handling: declines, ambiguous results, crashes mid-charge, duplicate webhooks, refunds, and the known gaps.

Connect your product

1. Send usage and get your first invoice: create a customer, send token usage with curl or LiteLLM, and open the invoice. Start here.
2. AI pricing reference: the models each recipe prices, pricing your own model, prepaid credit, and margin.
3. API surface: the core routes. The full reference is API endpoints.
4. API keys: get a key, send it, test and live mode, and rotation.
5. Webhooks: events, signatures, and retries.
6. Stop usage when credit runs out: poll a prepaid customer’s live credit balance and gate in your own code.
7. LiteLLM integration: send token usage from a LiteLLM proxy with a few lines of proxy config.

Run it for real

1. Self-host: what you need and how the pieces fit.
2. Production on one VM: install with Docker Compose, then HTTPS, email, Stripe, nightly backups and a go-live checklist.
3. High availability: run two or more copies behind a load balancer, with health checks, shutdown and rolling upgrades.
4. Postgres requirements, email setup, backups and tax calculation.
5. When something breaks: the operations runbook. Find what you see, then follow its steps.

Engineering

1. How Hardcount is engineered: the rules, with the proof for each.
2. Measured runs: correctness under failure and sustained throughput.

---

Changing Hardcount itself? Contributor docs, design notes and records are in docs/dev/.