---
description: >-
  Inyo Wallet API — a double-entry ledger for multi-wallet money management: deposits with splits, preauthorization holds, captures, refunds, transfers, and FX conversions with full source lineage.
---

# 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](api-reference.md#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](integration-guide.md) — a real B2B scenario end-to-end: wire deposit split across vendor wallets, preauthorization, partial capture, refund, and void
* [API Reference](api-reference.md) — every endpoint, error code, and idempotency semantics