About Wallets

In everyday life, you carry a wallet that holds cash. In the ledger, a wallet holds a balance similar to a bank account — but the concept extends far beyond.

A savings product, a loan, an invoice, a prepaid card, transport ticket, a merchant settlement pool, even a temporary escrow for a single transaction — all of these can be wallets. If something needs to track how much money is in it, it's a wallet.

This is what makes the ledger more than just a database of transactions. Traditional payment switches route messages between systems but don't understand balances. They know where to send a payment, but not how much is available, what rules apply, or what happened after delivery.

The ledger knows all three because every participant, every account, and every business rule is expressed as a wallet — with real balances, real-time limits, and automatic routing built in. It's a payment switch that actually understands money.

Why wallets matter

Automatic balance management

Every time money moves, the ledger updates wallet balances atomically. There is no separate process to reconcile, no batch job that runs overnight, no spreadsheet that someone has to check in the morning.

If a payment completes, both the sender and receiver balances are already correct. If a payment fails, both balances are already rolled back. This is true even when the payment crosses institutional boundaries — a bank's settlement account in the ledger stays in sync with the actual movement in the bank's core system because the ledger coordinates both sides before confirming anything.

For organizations running payment operations, this eliminates an entire category of work. Reconciliation isn't a daily task — it's a continuous process handled by the ledger, saving hundreds of hours of manual effort.

Simplified reporting

Because every financial position lives in a wallet, reporting becomes straightforward. Need to know the total exposure to a specific bank? Query the bank's settlement wallet. Need to see all transactions for a specific customer account? Query the wallet that represents that account. Need a daily summary of all movements across a currency? Query all wallets denominated in that symbol.

There's no need to reconstruct balances from transaction logs or reconcile across multiple systems. The wallet is the balance, and the ledger maintains it continuously.

Business rules as configuration

Wallets aren't just containers — they carry behavior.

A wallet can enforce minimum and maximum balance limits, restrict which currencies it accepts, automatically forward payments to a different destination based on amount or currency, or reject transactions that don't match a specific pattern. These rules are defined as configuration on the wallet itself, not as custom code in a middleware layer.

This means that business logic that traditionally lives scattered across payment gateways, fraud engines, and core banking middleware can be expressed directly in the ledger. Adding a new rule doesn't require a code deployment — it requires updating a wallet's configuration.

Mapping your systems to wallets

One of the most powerful aspects of wallets is that they can represent anything in your existing infrastructure. A bank's core banking system, a mobile money platform, a card processor, a government tax collection agency — each one becomes a wallet in the ledger, connected through a bridge that translates ledger operations into the specific protocol that system understands.

This is where the "payment switch on steroids" idea becomes concrete. A traditional switch has a routing table that maps message types to destinations. The ledger has wallets — and each wallet knows its own balance, its own rules, and its own connection to the outside world. When a payment arrives, the ledger doesn't just route it — it checks available funds, applies business rules, coordinates the debit and credit across both systems atomically, and updates all balances in real time.

Consider a practical example. A fintech company connects to three banks and a mobile money provider. In a traditional architecture, they'd build four separate integrations, maintain four reconciliation processes, and write custom routing logic. With the ledger, each bank and the mobile money provider is a wallet. Payment routing is wallet configuration. Reconciliation is automatic. Adding a fifth bank is creating one more wallet and one more bridge — the existing rules and balances keep working exactly as before.

How addressing works

Every wallet has a handle — its unique identifier in the ledger. Handles follow a structured format:

<schema>:<handle>@<parent>

For example, sav:42424242@mybank.co means savings account 42424242 at the institution mybank.co. The three parts serve different purposes:

• schema categorizes the wallet type — what kind of thing this address represents
• handle is the specific identifier — an account number, phone number, card number, or crypto address
• parent is the institution or system that owns this address, using its full domain name

Why full domains?

The parent always uses a full domain name like mybank.co or yourbank.us — never a short abbreviation. This is a deliberate design choice for three reasons:

Validation. A domain name is something that can be verified. When mybank.co registers as a participant, the ledger can validate that the institution actually controls that domain. Short names like hpb or mybank are ambiguous — two different banks in two different countries could claim the same abbreviation.

Multi-network and cross-border. When a ledger connects banks across countries or payment networks, naming collisions become inevitable with short codes. Domains are globally unique by definition. mybank.co (Colombia) and mybank.us (United States) can coexist in the same ledger without conflict, making cross-border payment routing unambiguous.

Domain features. The ledger uses domains as a grouping mechanism for access control, reporting, and data isolation. A domain like mybank.co can scope which records, policies, and reports belong to that institution — something that only works cleanly when the parent identifier is a proper, validated domain.

Schema examples

The schema is flexible enough to represent any kind of financial endpoint:

Address resolution

The ledger uses this structure for address resolution. When a payment targets sav:42424242@mybank.co, the ledger walks up the hierarchy — first looking for that exact wallet, then sav@mybank.co, then mybank.co — until it finds a registered wallet that can handle the movement. This means a single wallet mybank.co can receive all payments addressed to any account at that bank, and the connected bridge tells the bank's core system which specific account to credit.

This is why you don't need to create millions of wallets for millions of bank accounts. The addressing hierarchy lets you start broad (one wallet per institution) and get more specific only where you need individual balance tracking or special rules.

Native and bridge wallets

Wallets come in two flavors:

Native wallets have their balance fully managed by the ledger. The ledger is the single source of truth. These are ideal for internal accounts — treasury positions, fee collection pools, escrow accounts — where no external system needs to agree on the balance.

Bridge wallets are linked to an external system. Every balance movement requires both the ledger and the external system to agree before it's finalized. If the bank's core system can't complete the credit, the entire payment rolls back — including any debits that already happened on the other side. This two-phase coordination is what makes cross-institutional settlement reliable without a central authority.

Both types look identical from the outside. The same queries, the same reporting, the same business rules apply to both. The only difference is whether the ledger manages the balance alone or in partnership with an external system.

What's next

See About Intents to understand how payments move money between wallets, or Send a Payment to try it hands-on.