Quick start
Needs Docker with Compose v2 and openssl. Runs the released image
(linux/amd64 and linux/arm64) with Postgres (pgvector) and Redis; no clone,
no build.
mkdir inite-billing && cd inite-billing
curl -fsSLO https://raw.githubusercontent.com/inite-ai/inite-billing-service/main/docker-compose.quickstart.yml
cat > .env <<EOF
BILLING_VERSION=1.4
POSTGRES_PASSWORD=$(openssl rand -hex 24)
JWT_SECRET=$(openssl rand -hex 48)
KEY_SEAL_SECRET=$(openssl rand -base64 32)
EOF
docker compose -f docker-compose.quickstart.yml up -d --wait
curl http://localhost:3000/health/ready
open http://localhost:3000/api # Swagger (xdg-open on Linux)
The container applies its migrations on boot. BILLING_VERSION takes X.Y
(newest patch of that release) or vX.Y.Z; :latest follows the main-branch
deploy, not a release. In this development setup billing checks HS256
tokens against JWT_SECRET and the issuer in JWT_ISSUER (default
http://localhost:3002, the
auth quick start);
give both .env files the same JWT_SECRET to sign in through it. Production
verifies RS256 against the JWKS at AUTH_SERVICE_URL. Add ANTHROPIC_API_KEY
to .env for the assistant.
Working on the code instead: Run from source.
Why not Lago, Stripe Billing or Kill Bill?
- Stripe Billing needs nothing to run, and it does tax (Stripe Tax),
invoice documents and revenue recognition. INITE Billing does none of those:
its invoice is a record per paid order with the provider's receipt link.
Stripe Billing only charges through Stripe; here Stripe is one adapter
beside crypto (ETH/SOL/TON/TRON), Apple and Google in-app purchases, ONE and
Lava, all driving the same order state machine.
- Lago is also open source and AGPL, and is built for high-volume usage
events and invoicing on top of them. It hands payment collection to Stripe,
Adyen or GoCardless. INITE Billing collects payment through its own rail
adapters, and grants entitlements and credits from the same state change.
Its metering is a credit ledger (per-model-tier rates, windowed quotas, one
consume call), not an event-aggregation pipeline.
- Kill Bill has run in production for over a decade, with a plugin system
for payment gateways and a full invoicing engine. INITE Billing is a newer
NestJS/TypeScript service with a smaller surface, and less history behind it.
- AI agents as payers. Every checkout session also answers x402, so an
agent with a USDC wallet on Base pays by itself; people can let their agents
spend from an INITE wallet within limits they approve with a passkey. See
AI agents and money.
- Retention work in the same service. Affiliates with NET-15 payouts,
promo codes, LLM-written dunning and win-back outreach, and an admin
assistant with confirm-before-execute actions.
Part of the INITE Triad: INITE Auth
issues the tokens that Billing and
INITE Brain verify; the
contract between them is
the Triad contract.
Run all three with one compose file:
inite-ai/inite-triad.
Why INITE Billing
Most billing stacks make you choose: a SaaS gateway that owns your money flow
(Stripe Billing, Chargebee) or a bare payments library that leaves
subscriptions, entitlements and dunning to you. INITE Billing is a single
self-hostable service that ships the entire money lifecycle — catalog,
checkout, subscriptions, credits, entitlements, affiliate program, retention
automation — behind one payment-agnostic state machine, with the payment
provider reduced to a pluggable adapter.
- Rail-agnostic by design — Stripe, ONE, Lava, Apple IAP, Google Play
RTDN, and native multi-chain crypto (ETH/SOL/TON/TRON) implement one
PaymentRailAdapter interface; the orchestrator state machine
(created → open → paid → refunded/failed/expired) doesn't know which rail paid.
- AI-first, not AI-bolted-on — an embedded Claude assistant with
role-gated tools and a confirm-before-execute action layer; LLM-generated
dunning / win-back / abandoned-checkout outreach; semantic catalog search
(pgvector); next-best-offer recommendations; AI funnel insights for admins.
See docs/ai-features.md.
- AI agents pay, both ways — every checkout also accepts x402, so an
agent with a wallet pays in USDC on Base by itself; and people get an
INITE wallet (their own USDC under their passkey) from which their AI
agents pay any x402 site within limits they approve. See
AI agents and money.
- Built to meter AI products — credits are not a flat bucket: a metered
feature registry with per-model-tier rates (tokens/requests/generations),
windowed quotas with soft-cap warnings, and a backwards-compatible
service-to-service
consume API.
- Platform hub — INITE modules (club/events/education/health/shop/studio/
estate) call it machine-to-machine with per-service API keys; domain events
fan out via a transactional outbox to per-service webhooks.
- Complete revenue toolkit — multi-level affiliate program with NET-15
payouts, promo codes, conversion funnel tracking with churn detection,
heuristic payment-risk scoring, full admin UI (19 pages) + user dashboard
in Next.js, EN/RU localized.
- Operable and audited — append-only migrations, IDOR-hardened endpoints,
webhook signature verification, SSRF-guarded outbox, idempotency at every
boundary, secret scanning and CodeQL in CI. See SECURITY.md.
AI agents and money
Get paid by agents (x402). With the crypto rail taking USDC on Base and
Turnkey set up in admin → Crypto, every checkout session also returns an
x402Url. An agent asks it, gets 402 with the terms, signs a USDC transfer
for the invoice, and billing settles the order like any crypto payment.
Guide: docs/x402.md.
Let people's agents pay (INITE wallet).
- A person opens a wallet in their INITE account with a passkey. It is a
Turnkey wallet whose only key is that passkey; billing cannot move the money.
- They top it up with USDC on Base, or by PIX (converted and delivered as
USDC), and withdraw with the passkey.
- An AI agent connects to
/mcp/wallet with an INITE Auth token
(wallet:pay, issued for this resource, naming the agent in act).
- The person approves the agent and its limits with the wallet passkey. That
makes the agent a Turnkey user whose policy caps each payment.
- The agent's
pay tool fetches a URL and, on 402, pays within its
per-payment, daily and monthly limits.
Agents with a wallet of their own. An agent registers with INITE Auth by
itself (its own P-256 key, client_credentials) and gets a did:web identity.
It opens its own wallet at POST /v1/agent-wallet: the Turnkey owner is the
agent's key, so only the agent can spend. Anyone funds the address with USDC on
Base. To pay, billing prepares the Turnkey request for an x402 URL and the agent
stamps it with its key (/v1/agent-wallet/payments, then /confirm). An agent
that can't keep a key registers with a client secret, and INITE keeps the wallet
key for it: paying is then one call. Agents use the same wallet over MCP
(/mcp/wallet: wallet, pay, pay_confirm, withdraw), and hand a person
/fund/<address> to top it up (QR, PIX). In ChatGPT and other MCP Apps clients
the wallet tools show as a card with the balance, a QR and a Top up button.
Let sites charge the wallet in one step. A person allows a site once, with
limits, on one page in INITE ID. After that the site calls
POST /v1/checkout/sessions/:id/pay-from-wallet and the order is paid from the
wallet; the first time, it gets an approveUrl to send the person to.
Guides: billing.inite.ai/docs/wallet ·
docs/wallet.md.
Run from source
git clone [email protected]:inite-ai/inite-billing-service.git
cd inite-billing-service
npm install
cp env.example .env # fill in secrets (ANTHROPIC_API_KEY for the assistant)
docker compose up -d postgres redis
npm run prisma:migrate # apply schema (pgvector image required)
npm run db:seed # optional: demo catalog (service + products + prices)
npm run start:dev # backend on :3000, Swagger at /api
cd frontend && npm install && npm run dev # UI on :3001
Verify:
curl http://localhost:3000/health
open http://localhost:3000/api # Swagger
Full walkthrough (test DB, docker profiles, troubleshooting):
docs/getting-started.md.
What ships in the box
| Surface | What you get |
|---|
| Catalog & checkout | Products/prices per service, 2-phase checkout (session → pay), promo codes, idempotency keys |
| Payments | 6 rail adapters, provider-credential storage in DB, webhook validation (amount/currency), BullMQ processing |
| Subscriptions | Trials, grace periods, renewal/expiry crons, lifecycle webhooks (billing.subscription.*) |
| Credits & metering | Ledger (grant/consume/reset/refund), metered feature registry, model-tier rates, windowed quotas, usage analytics |
| Entitlements | Access rights granted on payment, revoked on refund/expiry, queryable per user |
| AI assistant | Claude chat (AI SDK v7 streaming) with 19 tools (14 read + 5 confirm-gated actions), tool telemetry, 👍/👎 feedback, eval harness |
| Retention automation | Funnel event tracking, abandoned-checkout / dunning (day 0-2-5) / win-back / trial-ending outreach: LLM-personalized email + in-app, EN/RU |
| Notifications | Resend email (delivery webhooks, unsubscribe, suppression) + in-app notification center with preferences |
| Affiliates | Multi-level referral program, configurable commission levels, NET-15 payouts, payout providers |
| Risk | Velocity / outlier / failed-burst heuristics, monitor-only by default, admin review queue |
| Admin UI | 19 pages: funnel kanban + AI insights, outreach stats, metering, risk review, catalog/orders/subscriptions/credits CRUD |
Documentation
Full rendered docs — with diagrams and integration guides — at
billing.inite.ai/docs.
Guides: Sell your first subscription ·
Meter AI usage with credits ·
Gate access with entitlements ·
Receive billing events ·
Go to production ·
Agents pay: x402 and the INITE wallet
Reference (mirrored in-repo):
| Doc | What's inside |
|---|
| docs/getting-started.md | Local setup, env variables, migrations, running tests |
| docs/architecture.md | Module map, payment state machine, event flows, data model |
| docs/api.md | Full REST surface, auth (JWT / service API keys), examples |
| docs/ai-features.md | Assistant, action layer, outreach, metering, RAG, risk, insights |
| docs/x402.md | Getting paid by AI agents over x402: setup in admin, limits, errors |
| docs/wallet.md | INITE wallet: who holds what, top-up, withdrawal, agents and their limits |
| docs/operations.md | Deploy, feature flags & rollout order, adding a payment rail |
| SECURITY.md | Threat ledger, known limitations, vulnerability reporting |
| CONTRIBUTING.md | Hard bars for PRs, conventions, release flow |
| AGENTS.md | Rules, zones, gates and module map for AI coding agents (and humans) |
Contributing
Contribute with an AI agent
The Codespace comes up with Node 22, Postgres (pgvector), Redis, dependencies
installed and migrations applied. Open the repo in your agent and say
/contribute (Claude Code), or "read AGENTS.md and help me add …" (Cursor,
Codex, Copilot, Gemini CLI, Windsurf). AGENTS.md holds the rules,
the risky zones, and the exact CI gates the agent runs before opening a PR.
Only want to propose something? /spec-idea, or the Product idea issue
form. Looking for a first task: good first issue.
By hand
PRs land on main only through pull requests — CI (build-test) is a
required check, titles follow Conventional Commits (release-please cuts
versions and the changelog from them). Read CONTRIBUTING.md
for the hard bars: tests for money paths, exact Decimal arithmetic,
backwards-compatible public contracts, append-only migrations.
License
AGPL-3.0. Part of the INITE ecosystem — see also
inite-auth-service (identity)
and inite-brain-service (memory).
