Use Cases

These manuals show how to model ten product categories on Parix and TigerBeetle. They assume the same technical foundation: provision a Parix database, choose an access surface, send supported operations through the Parix gateway, and keep non-ledger responsibilities in the systems designed for them.

The examples are modeling patterns, not application schemas. Keep identity, catalog, compliance, pricing, and customer-facing workflow data in your application. Use Parix for balances, transfers, limits, and durable value-movement history.

Choose a use case

1. Wallets: maintain customer balances, top-ups, transfers, withdrawals, and settlement accounts.
2. Metering: record usage, enforce allowances, and produce a durable source for billing aggregation.
3. Marketplaces: coordinate seller balances, platform fees, holds, refunds, and payouts.
4. Gaming: protect virtual currencies, rewards, purchases, trades, sources, and sinks.
5. Subscriptions: track recurring entitlements, usage, credits, adjustments, and invoice-ready events.
6. Neobank / BaaS: operate customer, omnibus, settlement, and suspense balances with card-style pending authorization, post, and void behind regulated product workflows.
7. Currency Exchange: execute atomic multi-currency conversions while keeping quotes, rates, spreads, and external hedging explicit.
8. Coupon and Rewards System: issue, redeem, expire, reverse, and reconcile coupons and loyalty points without double-spend or duplicate awards.
9. AI Credits: enforce model-weighted credit burn and weekly and rolling-window limits with pending reservations and exact usage deductions.
10. Lending & Credit Lines: issue revolving facilities, reserve drawdowns, and track principal, interest, fees, repayments, and write-offs.

Choose an access surface

All four surfaces ultimately use the Parix control plane or the same public TigerBeetle gateway. Choose by workflow rather than by database plan.

Dashboard workflow

Use the Dashboard to complete the human setup path:

1. Create a database and wait until it is Ready.
2. Copy the immutable database ID. API routes require the ID, not the display name.
3. Generate a Specific database API key unless the workload intentionally manages multiple databases.
4. Run a read in the Query explorer before issuing an intentional write.

Keep the complete API key in server-side secret storage. The Dashboard shows it only once, and a database-scoped key remains a read/write credential for its bound database.

Published Parix CLI

Install the published CLI globally, then sign in with OAuth:

npm install -g @parix/cli@latest
parix --version
parix auth login

The latest CLI provides auth, api, database, and tb command groups. It is intended for developer and operator workflows that can use a local user session. Use an API key with the raw gateway or an application adapter for unattended service code.

See the Parix CLI documentation for environment selection and exact command options.

Published Node adapter

The @parix/tigerbeetle-node package adapts the gateway response to TigerBeetle-style TypeScript types and bigint values. Install a pinned version from npm. Its client requires all three connection values:

import { createClient } from '@parix/tigerbeetle-node';

const client = createClient({
  baseUrl: 'https://parix.io',
  apiKey: process.env.PARIX_API_KEY!,
  databaseId: process.env.PARIX_DATABASE_ID!,
});

Use a Specific database key for apiKey when the process needs only one database. Pin a reviewed package version, keep the adapter behind a small application boundary, and validate the approved version in your environment before production traffic.

The adapter exposes createAccounts, createTransfers, lookupAccounts, lookupTransfers, getAccountTransfers, getAccountBalances, queryAccounts, and queryTransfers. These methods return result arrays directly and translate integer strings in gateway responses into the corresponding bigint fields.

Create methods return sparse { index, result } arrays: empty means no item conflicts. On write conflicts that include tbResults, the adapter unwraps HTTP 409 into that same array shape rather than throwing. Other HTTP failures throw. The adapter does not expose the raw gateway envelope field persisted, so durable workflows must confirm every write with an exact post-write lookup of stable IDs and immutable fields before advancing application state.

Authoritative gateway contract

The raw HTTPS endpoint is the authority beneath the CLI, the Node adapter, and direct integrations:

POST /api/v1/databases/{databaseId}/tb/{operation}

Parix supports exactly eight TigerBeetle operations on this route:

Applications do not connect directly to TigerBeetle replicas, provider hosts, or diagnostic target addresses on any self-service plan. Read Gateway for authentication, response-envelope, error, and retry details. Treat the live /api/v1/openapi.json document as authoritative for current request schemas; the generated interactive API reference is a convenience view and may lag the live route until its bundle is regenerated.

Preserve IDs and integer precision

Choose a stable account ID for each durable account and a stable transfer ID for each business event. Store or deterministically derive those IDs before sending a write. If an HTTP outcome is ambiguous, retry or look up the event with the same ID; generating a replacement ID can turn one business event into two transfers.

Optional user_data fields

TigerBeetle’s user_data_128, user_data_64, and user_data_32 fields are optional secondary identifiers. Leave them at zero when you do not need them. The transfer or account id is the idempotency key; user_data_* is not a substitute for a stable ID.

Per TigerBeetle’s data modeling guidance, each field is application-defined and indexed for point and range queries. A common way to think about them:

Use a shared non-zero user_data_* value only when you will query a group of related records together (for example every leg of one FX quote). Only non-zero values are usable as query filters. Store PII, secrets, and full business documents in your application database; put only opaque, non-secret correlations in the ledger. CLI flags --user-data-128, --user-data-64, and --user-data-32 map to these fields—omit a flag when the value is zero.

At the raw JSON boundary, represent values that can exceed JavaScript's safe integer range as quoted decimal strings. This includes TigerBeetle IDs, amounts, balance counters, user-data integers, and timestamps:

{
  "id": "1701411834604692317316873037158841057",
  "amount": "1000000"
}

Do not first convert these values to a JavaScript number. The Node adapter accepts TigerBeetle bigint fields and performs this JSON conversion for its callers.

Interpret result arrays

The raw gateway returns an envelope; responsePayload is the TigerBeetle result to consume. Read operations return arrays of matching records. Successful create operations use TigerBeetle's per-item result convention: an empty result array means every item in the batch was accepted. When TigerBeetle rejects one or more write items, the raw gateway returns HTTP 409 with a tbResults array. Preserve the original batch order so each result index can be mapped back to its source item.

Wide integer fields in responses (id, amounts, balances, user_data_128, user_data_64, timestamp, and other u64/u128 values) are decimal strings, matching the request form. Do not parse them with JavaScript Number — values can exceed Number.MAX_SAFE_INTEGER. Compare and store them as strings or bigint.

The Node adapter returns read and write result arrays directly, including tbResults extracted from a write conflict (HTTP 409 is unwrapped into that array when present). The CLI prints a human-readable execution summary by default and the full gateway response with --json. JSON output is decorated by the terminal logger, so do not treat it as clean stdout for direct jq pipelines. The CLI sets a non-zero process exit code on HTTP 4xx/5xx; still read detail and tbResults from the body.

The current gateway can expose only the first ten create-conflict entries. After any nonempty conflict response, an input omitted from tbResults is not proven successful. Use stable-ID lookups or smaller bounded batches until every submitted item has a confirmed outcome.

For a write, also require the raw response's persisted value to be true. Do not record a response from a non-persistent gateway mode as a committed ledger mutation.

Linked-chain retries

When you resubmit a linked multi-leg batch that already committed, TigerBeetle may report exists (or a related exists code) on the first leg and linked_event_failed on later legs. That mixed tbResults list is not proof of a partial commit. Look up every stable transfer ID and compare the immutable fields. Do not require every index to report exists before treating a linked retry as safe.

Shared-plan query filters

On Developer and other shared plans, query_accounts and query_transfers require a ledger filter. Multi-ledger products (for example currency exchange) must run one query per ledger or use lookup_* with known IDs.

Respect plan boundaries

The gateway and eight-operation surface are common across plans, but capacity and operational features are not:

• Developer is a shared, quota-limited environment for learning, prototypes, and SDK testing. It is not production placement.
• Dedicated Single Node provides isolated development or staging capacity without production high availability.
• Production HA, Production 6, and contract-defined Enterprise plans are the production families. A production plan does not by itself create an unconditional SLA; that requires a separate written agreement.
• No self-service plan exposes the raw TigerBeetle protocol. Applications continue to use the Parix HTTPS gateway.

Batch-size, rate, event, account, transfer, pending-transfer, and feature limits are plan-dependent and can change through catalog configuration. Review Plans and limits and the active create catalog rather than hard-coding entitlement values in application logic.

Apply the foundation to a manual

Start with the category closest to your product. Treat its account and transfer names as a modeling vocabulary, not a schema to copy unchanged. Define your own ledgers, codes, balance constraints, stable ID mapping, reconciliation rules, and failure policy before production traffic.

Then complete Create a database, Connect to a database, and TigerBeetle operations.