Wallet

The Inyo Wallet API is a double-entry ledger for holding and moving money across named wallets. It powers B2B use cases like splitting inbound wires across vendor sub-wallets, card-style preauthorization holds with partial capture, and audit-grade fund traceability.

Core Concepts

Wallets

A wallet is a named account you own. Each wallet holds balances in one or more assets (USD, USDC, EUR, MXN). Balances are computed from the ledger — never written directly.

Every wallet is owned by either a company or a user, identified by an owner_ref you supply (your own ID for that entity).

Double-Entry Ledger

Every operation writes a journal with two or more entries. Each entry is either a debit or a credit, and the sum of debits equals the sum of credits, per asset, in every journal. This makes it impossible for money to appear or disappear — a bug can only ever misroute it.

You don't write entries directly. You call the operation endpoints (deposit, hold, capture, void, refund, transfer, FX conversion) and the ledger writes the correct entries atomically.

Balances: posted, held, available

Every wallet balance has three numbers per asset:

Field	Meaning
`posted`	Cumulative signed sum of every entry — what the wallet has actually received minus what it has sent
`held`	Sum of open preauthorizations — money reserved but not yet spent
`available`	`posted − held` — spendable balance

When you preauthorize, held goes up (and posted drops — the preauth moves funds to a hold sub-account). When you capture, funds move from the hold to the destination. When you void, held goes back down and the funds return.

Sources and Lineage

Every dollar in the system traces back to an origin source — a wire, ACH debit, card collection, or stablecoin deposit. When you split a $10k wire across 10 wallets, each credit entry carries a lineageRef pointing at the source.

Later, when a wallet spends money, the debit entries also carry lineageRef — pointing at whichever source(s) the money originally came from. The ledger uses FIFO consumption: the oldest inbound money is spent first.

This gives you audit-grade answers to "where did this specific dollar come from?" — required for AML, tax lots on stablecoins, and chargeback attribution.

Insert-Only

Journals and entries are never updated or deleted — immutability is enforced at the database level. A "reversal" is a compensating journal that references the original via parentJournalId, so operation chains stay traceable: refund → capture → preauth.

Authentication & Conventions

Every endpoint lives under /organizations/{tenant}/ on the wallet API host (https://{FQDN}), authenticated with your tenant API key in the X-API-KEY header.
Every POST requires an Idempotency-Key header — see Idempotency.
All amounts are strings in JSON, decimal with up to 8 places. Never parse amounts as floating-point numbers — you'll lose precision.
id fields on wallets, holds, and journals are UUIDs. Fields like accountId and journalId inside entries are internal numeric identifiers — use the UUIDs for API calls.

Where to Start

Integration Guide — a real B2B scenario end-to-end: wire deposit split across vendor wallets, preauthorization, partial capture, refund, and void
API Reference — every endpoint, error code, and idempotency semantics