Wallets

Overview

This guide implements a single-currency wallet ledger with three account roles:

• a platform reserve that funds customer top-ups;
• customer wallets that cannot spend more than their posted credits; and
• merchant wallets that receive purchases and fund refunds.

The examples use ledger 840 for USD and store amounts in cents. Replace the ledger, codes, and IDs with values from your own governed registry. Do not reuse the example IDs in more than one database.

Parix provides the managed TigerBeetle ledger and gateway. It does not move money through a card processor or bank, authenticate customers, or replace your settlement and general-ledger systems.

Architecture and ownership

A wallet write crosses several systems. Keep the ownership boundary explicit:

Store personal data, card or bank details, and display names outside TigerBeetle. Map them to opaque, stable account IDs in your application database. Persist a transfer ID with the business event before the first write so every retry addresses the same ledger event.

The Parix client path is HTTP through the gateway:

server application -> Parix API -> authenticated private gateway -> managed TigerBeetle

Applications do not receive replica addresses and do not connect with the native TigerBeetle protocol.

Ledger model

Ledger

Never transfer directly across ledgers. Currency conversion is an application decision represented by separate, reconciled legs in their respective ledgers.

Account codes

The no-overdraft account flag is the ledger-enforced control. Application balance checks are useful for user experience, but they are not a substitute for this constraint under concurrent writes.

Transfer codes

Keep the purchase-to-refund relationship in your application database. A refund gets its own stable transfer ID; it does not edit or reuse the purchase transfer.

Invariants

Before you begin

1. Choose the correct plan. Developer and Dedicated Single Node are non-production plans. Use a Production or Enterprise plan for production workloads. Review Plans and limits before selecting topology, region, quotas, backup posture, or support.
2. Create a database and wait until its dashboard status is Ready. Record its database UUID; CLI and API paths use the UUID, not the display name.
3. For dashboard and CLI work, sign in as an authorized organization member. For a server application, generate a database-scoped API key and store it only in server-side secret storage.
4. Establish a registry for ledgers, account codes, transfer codes, and stable ID derivation. Review it with engineering and finance before the first production write.
5. Decide which external event makes a top-up final. Do not credit a customer merely because a client reported success.
6. Define reconciliation and compensating-transfer procedures before launch.

@parix/tigerbeetle-node is the published Node.js client for TigerBeetle-shaped operations on the Parix HTTPS gateway. It does not open a native TigerBeetle connection. Pin a package version approved for your environment, configure { baseUrl, apiKey, databaseId } with a database-scoped API key, keep the client behind an application boundary, and validate behavior before production traffic. Its configuration is { baseUrl, apiKey, databaseId }.

Every public create or lookup request is a bare JSON array containing between 1 and 8190 items. Shared Developer quotas can impose a lower effective limit. In raw HTTP JSON, encode IDs, amounts, timestamps, and other bigint-width values as decimal strings to avoid JavaScript precision loss.

Dashboard walkthrough

Live-write warning: The Query explorer runs against the selected live database. Create accounts and Create transfers write immediately and cannot be undone. Use a non-production database, verify the selected organization and database, and record every ID before selecting Run.

1. Open the database and confirm Ready, the expected plan, and the database UUID on Dashboard.
2. Open Query and select Create accounts.
3. Clear Generate random ID when you need a reproducible ID. Enter the reserve ID, ledger 840, code 100, and flags bitfield 8, then select Run once.
4. Repeat for the customer and merchant IDs with codes 110 and 120, setting flags bitfield 10 on both constrained accounts.
5. Confirm that each successful create returns zero result rows. A nonempty create-result array is a rejection to investigate, not success.
6. Select Create transfers and create the top-up with the recorded reserve and customer IDs, amount in cents, ledger 840, code 1000, flags 0, and a stable transfer ID.
7. Create a purchase from customer to merchant with code 1010. Create a refund only as a separate merchant-to-customer transfer with code 1020.
8. Select Get account transfers, enter the customer account ID, include debit and credit history, and review the immutable movement list.
9. Select Query accounts or Query transfers for broader inspection. On Shared Developer, always select ledger 840; shared queries require a ledger.

The screenshot shows the single-account Create accounts form. It does not show a completed write or the three wallet accounts; enter and verify each planned account separately.

The dashboard is appropriate for controlled smoke tests and investigation. It is not an application integration surface and its signed-in session is not a production service credential.

CLI walkthrough

The commands in this section use the latest published parix CLI syntax. The CLI is an operator and development surface authenticated by browser OAuth; do not embed its stored OAuth session in a production service.

Install it globally, verify the version, and sign in:

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

parix --version should report the installed package version for these examples. Use the database UUID as the positional <database-id> in every parix tb command.

Create the accounts

Save the following reviewed bare array as wallet-accounts.json. The explicit flags are an advanced field, so a file is clearer and safer than a long flag-driven command.

[
  {
    "id": "81000000000000000001",
    "debits_pending": "0",
    "debits_posted": "0",
    "credits_pending": "0",
    "credits_posted": "0",
    "user_data_128": "0",
    "user_data_64": "0",
    "user_data_32": 0,
    "reserved": 0,
    "ledger": 840,
    "code": 100,
    "flags": 8,
    "timestamp": "0"
  },
  {
    "id": "81000000000000000002",
    "debits_pending": "0",
    "debits_posted": "0",
    "credits_pending": "0",
    "credits_posted": "0",
    "user_data_128": "0",
    "user_data_64": "0",
    "user_data_32": 0,
    "reserved": 0,
    "ledger": 840,
    "code": 110,
    "flags": 10,
    "timestamp": "0"
  },
  {
    "id": "81000000000000000003",
    "debits_pending": "0",
    "debits_posted": "0",
    "credits_pending": "0",
    "credits_posted": "0",
    "user_data_128": "0",
    "user_data_64": "0",
    "user_data_32": 0,
    "reserved": 0,
    "ledger": 840,
    "code": 120,
    "flags": 10,
    "timestamp": "0"
  }
]

Submit the file once:

parix tb create-accounts <database-id> --file ./wallet-accounts.json --json

A successful create has an empty responsePayload ([]). A conflict is a nonempty tbResults array associated with zero-based input indexes; inspect every returned result before proceeding.

Top up, purchase, and refund

Save this one-event bare array as wallet-top-up.json:

[
  {
    "id": "82000000000000000001",
    "debit_account_id": "81000000000000000001",
    "credit_account_id": "81000000000000000002",
    "amount": "10000",
    "pending_id": "0",
    "user_data_128": "0",
    "user_data_64": "0",
    "user_data_32": 0,
    "timeout": 0,
    "ledger": 840,
    "code": 1000,
    "flags": 0,
    "timestamp": "0"
  }
]

Run the top-up, then use stable IDs for the purchase and refund:

parix tb create-transfers <database-id> --file ./wallet-top-up.json --json

parix tb create-transfers <database-id> \
  --id 82000000000000000002 \
  --from 81000000000000000002 \
  --to 81000000000000000003 \
  --amount 2500 \
  --ledger 840 \
  --code 1010 \
  --json

parix tb create-transfers <database-id> \
  --id 82000000000000000003 \
  --from 81000000000000000003 \
  --to 81000000000000000002 \
  --amount 500 \
  --ledger 840 \
  --code 1020 \
  --json

These examples leave user_data_* at zero. The transfer id is the idempotency key; optional user_data_* is only needed when you will query by an external “who/what” correlation. See Optional user_data fields.

Do not run the refund until your application has validated the original purchase and remaining refundable amount. If a create command loses its HTTP response, look up the original ID before retrying:

parix tb lookup-transfers <database-id> --id 82000000000000000002 --json

If the lookup finds the intended transfer, treat the original write as committed. If it returns no match and the failure is retryable, resubmit the identical transfer with the identical ID.

Inspect history and ledger-scoped results:

parix tb get-account-transfers <database-id> \
  --account-id 81000000000000000002 \
  --limit 100 \
  --flag debits \
  --flag credits \
  --json

parix tb query-transfers <database-id> \
  --ledger 840 \
  --limit 100 \
  --json

The --ledger 840 filter is mandatory for shared queries and is a good production habit for every plan.

Node.js implementation

The adapter uses TigerBeetle-shaped records and bigint values over the Parix HTTP gateway. Install a pinned package version before use:

npm install @parix/tigerbeetle-node

The following implementation creates complete account and transfer objects, treats nonempty create-result arrays as item conflicts (and reconciles idempotent success via exact lookup), retains stable IDs, checks an ambiguous write by lookup before one retry, scopes the shared query by ledger, and always destroys the client.

import {
  AccountFilterFlags,
  AccountFlags,
  CreateTransferError,
  QueryFilterFlags,
  TransferFlags,
  createClient,
  type Account,
  type Client,
  type CreateAccountResult,
  type CreateTransferResult,
  type Transfer,
} from '@parix/tigerbeetle-node';

const LEDGER = 840;

const IDS = {
  reserve: 81000000000000000001n,
  customer: 81000000000000000002n,
  merchant: 81000000000000000003n,
  topUp: 82000000000000000001n,
  purchase: 82000000000000000002n,
  refund: 82000000000000000003n,
} as const;

class CreateRejectedError extends Error {}

function account(id: bigint, code: number, constrained: boolean): Account {
  return {
    id,
    debits_pending: 0n,
    debits_posted: 0n,
    credits_pending: 0n,
    credits_posted: 0n,
    user_data_128: 0n,
    user_data_64: 0n,
    user_data_32: 0,
    reserved: 0,
    ledger: LEDGER,
    code,
    flags: AccountFlags.history | (constrained ? AccountFlags.debits_must_not_exceed_credits : AccountFlags.none),
    timestamp: 0n,
  };
}

function transfer(id: bigint, debitAccountId: bigint, creditAccountId: bigint, amount: bigint, code: number): Transfer {
  return {
    id,
    debit_account_id: debitAccountId,
    credit_account_id: creditAccountId,
    amount,
    pending_id: 0n,
    user_data_128: 0n,
    user_data_64: 0n,
    user_data_32: 0,
    timeout: 0,
    ledger: LEDGER,
    code,
    flags: TransferFlags.none,
    timestamp: 0n,
  };
}

function assertCreateSucceeded(
  operation: 'createAccounts' | 'createTransfers',
  results: CreateAccountResult[] | CreateTransferResult[],
): void {
  if (results.length === 0) return;
  const capacityDecline = results.some(
    (item) => item.result === CreateTransferError.exceeds_credits,
  );
  throw new CreateRejectedError(
    `${operation} rejected${capacityDecline ? ' (capacity)' : ''}: ${JSON.stringify(results)}`,
  );
}

function statusOf(error: unknown): number | undefined {
  if (!error || typeof error !== 'object' || !('status' in error)) return undefined;
  return typeof error.status === 'number' ? error.status : undefined;
}

function isAmbiguousWrite(error: unknown): boolean {
  if (error instanceof CreateRejectedError) return false;
  const status = statusOf(error);
  return status === undefined || status >= 500;
}

function sameAccount(actual: Account, intended: Account): boolean {
  return (
    actual.id === intended.id &&
    actual.user_data_128 === intended.user_data_128 &&
    actual.user_data_64 === intended.user_data_64 &&
    actual.user_data_32 === intended.user_data_32 &&
    actual.reserved === intended.reserved &&
    actual.ledger === intended.ledger &&
    actual.code === intended.code &&
    actual.flags === intended.flags
  );
}

function assertSameTransfer(actual: Transfer, intended: Transfer): void {
  const matches =
    actual.id === intended.id &&
    actual.debit_account_id === intended.debit_account_id &&
    actual.credit_account_id === intended.credit_account_id &&
    actual.amount === intended.amount &&
    actual.pending_id === intended.pending_id &&
    actual.user_data_128 === intended.user_data_128 &&
    actual.user_data_64 === intended.user_data_64 &&
    actual.user_data_32 === intended.user_data_32 &&
    actual.timeout === intended.timeout &&
    actual.ledger === intended.ledger &&
    actual.code === intended.code &&
    actual.flags === intended.flags;

  if (!matches) throw new Error(`Transfer ID ${intended.id} belongs to another event`);
}

async function accountsAlreadyExist(client: Client, intended: Account[]): Promise<boolean> {
  const found = await client.lookupAccounts(intended.map((item) => item.id));
  if (found.length === 0) return false;

  const intendedById = new Map(intended.map((item) => [item.id, item]));
  if (
    found.length !== intended.length ||
    !found.every((item) => {
      const expected = intendedById.get(item.id);
      return expected !== undefined && sameAccount(item, expected);
    })
  ) {
    throw new Error('Wallet account IDs are only partially present or belong to different accounts');
  }

  return true;
}

async function ensureAccounts(client: Client, intended: Account[]): Promise<void> {
  if (await accountsAlreadyExist(client, intended)) return;

  let results: CreateAccountResult[] | CreateTransferResult[];
  try {
    results = await client.createAccounts(intended);
  } catch (error) {
    if (!isAmbiguousWrite(error)) throw error;
    if (await accountsAlreadyExist(client, intended)) return;
    throw error;
  }

  if (await accountsAlreadyExist(client, intended)) return;
  if (results.length === 0) {
    throw new Error('Account write was not confirmed by lookup; do not advance or change the payload');
  }
  assertCreateSucceeded('createAccounts', results);
}

async function transferAlreadyExists(client: Client, intended: Transfer): Promise<boolean> {
  const [found] = await client.lookupTransfers([intended.id]);
  if (!found) return false;
  assertSameTransfer(found, intended);
  return true;
}

async function createTransferWithOneAmbiguousRetry(client: Client, intended: Transfer): Promise<void> {
  // Every durable retry starts with lookup, including recovery after a process
  // stopped after commit but before it persisted the response.
  if (await transferAlreadyExists(client, intended)) return;

  for (let attempt = 0; attempt < 2; attempt += 1) {
    let results: CreateAccountResult[] | CreateTransferResult[];
    try {
      results = await client.createTransfers([intended]);
    } catch (error) {
      if (!isAmbiguousWrite(error)) throw error;

      if (await transferAlreadyExists(client, intended)) return;

      if (attempt === 1) throw error;
      // Retry only the identical object with the identical, already-persisted ID.
      continue;
    }

    if (await transferAlreadyExists(client, intended)) return;
    if (results.length === 0) {
      throw new Error('Transfer write was not confirmed by lookup; do not advance or change the payload');
    }
    assertCreateSucceeded('createTransfers', results);
  }
}

function mustGetEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing ${name}`);
  return value;
}

async function main(): Promise<void> {
  const client = createClient({
    baseUrl: mustGetEnv('PARIX_BASE_URL'),
    apiKey: mustGetEnv('PARIX_API_KEY'),
    databaseId: mustGetEnv('PARIX_DATABASE_ID'),
  });

  try {
    const accounts = [
      account(IDS.reserve, 100, false),
      account(IDS.customer, 110, true),
      account(IDS.merchant, 120, true),
    ];
    await ensureAccounts(client, accounts);

    await createTransferWithOneAmbiguousRetry(client, transfer(IDS.topUp, IDS.reserve, IDS.customer, 10000n, 1000));
    await createTransferWithOneAmbiguousRetry(client, transfer(IDS.purchase, IDS.customer, IDS.merchant, 2500n, 1010));
    await createTransferWithOneAmbiguousRetry(client, transfer(IDS.refund, IDS.merchant, IDS.customer, 500n, 1020));

    const customerHistory = await client.getAccountTransfers({
      account_id: IDS.customer,
      user_data_128: 0n,
      user_data_64: 0n,
      user_data_32: 0,
      code: 0,
      timestamp_min: 0n,
      timestamp_max: 0n,
      limit: 100,
      flags: AccountFilterFlags.debits | AccountFilterFlags.credits,
    });

    const ledgerTransfers = await client.queryTransfers({
      user_data_128: 0n,
      user_data_64: 0n,
      user_data_32: 0,
      ledger: LEDGER,
      code: 0,
      timestamp_min: 0n,
      timestamp_max: 0n,
      limit: 100,
      flags: QueryFilterFlags.none,
    });

    console.log({ customerHistory, ledgerTransfers });
  } finally {
    client.destroy();
  }
}

void main();

In a real service, allocate and persist the IDs before entering the retry loop, provision accounts separately from the payment path, and place retry work in a durable queue or outbox. The fixed IDs above make the retry boundary visible; they are not a production ID-generation scheme.

Failure and retry handling

Create success and create conflict have deliberately different shapes: a successful create_accounts or create_transfers returns []; rejected items produce a result array. The Node adapter returns TigerBeetle conflict results from createAccounts() or createTransfers() instead of throwing, so an unchecked nonempty array is a lost failure.

There is no request-level idempotency key for TigerBeetle operations. The account or transfer ID is the idempotency boundary. For a multi-item batch, retain the original ordering until every result is reconciled. Only a deliberately constructed linked chain within one create_transfers call succeeds or fails atomically; ordinary batch neighbors can have independent outcomes.

The current gateway can return only the first ten create conflicts. When a failed batch has more conflict possibilities, an input omitted from tbResults is not proven successful. Look up its stable ID or use smaller batches until every input has a confirmed outcome.

Test scenarios

Run these scenarios in an isolated non-production database and assert ledger records as well as API status:

Production operations

• Run production wallets only on a Production or Enterprise plan. Dedicated Single Node provides isolation but is still a non-production, non-HA posture.
• Keep API keys in server-side secret storage, bind them to the required database where possible, rotate them, and never log them. The CLI's local OAuth session is for humans, not services.
• Maintain reviewed registries for ledger, account, and transfer codes. Treat semantic changes as versioned migrations, not ad hoc number reuse.
• Use an inbox/outbox or equivalent durable workflow so the stable transfer ID and external provider reference survive process crashes.
• Reconcile reserve movements to processor or bank settlement, customer and merchant control totals to application records, and every refund to its purchase authorization. Investigate differences through a governed suspense or adjustment process.
• Monitor database health, request failures, shared quota/rate pressure, latency, and no-overdraft rejections. Separate expected business declines from platform errors.
• Enable and exercise backups and recovery where the selected production plan and provider support them. A backup does not replace external settlement reconciliation.
• Keep batch sizes within the public maximum of 8190 and the selected plan's lower limits. Use bounded batches whose individual business events can be traced by stable ID.
• Never assume a ledger write and an external card, bank, notification, or general-ledger action are atomic. Design compensation and recovery for every boundary.
• Preserve immutable transfer IDs and non-sensitive correlation IDs in structured logs. Keep PII and payment credentials out of TigerBeetle records and operational logs.

Related documentation

• Create a database
• API keys
• Dashboard
• TigerBeetle operations
• Parix CLI TigerBeetle reference
• Gateway boundary
• Plans and limits
• Metrics
• Logs
• Backups and restore
• TigerBeetle compatibility