Accounts, Wallets & Deposit Addresses

Program Architecture introduced three similar-sounding but distinct concepts: Accounts, Wallets, and Deposit Addresses. This page goes deep on each — what they are, what fields they expose, how money moves between them, and the currency/balance conventions that apply across the entire API.

The currency and amount convention

Before anything else: every monetary amount in the Axys API is a decimal-implied integer, denominated in the relevant object's currency. A value of 1000 represents $10.00 in a USD-denominated context, €10.00 in EUR, and so on — the integer represents the amount in the currency's smallest unit (cents, pence, etc.) for two-decimal currencies.

Currency itself is represented as an integer enum, derived from the Program:

This applies to transactionLimit on Cardholders and Cards, ledgerBalance/availableBalance on Card Accounts, amount on transfers, and Wallet balances.

🚧

TransactionsViewResponse.amount and FeesViewResponse.amount/merchantAmount are typed as strings rather than integers in the current specification, with no description clarifying whether they follow the same decimal-implied convention or represent literal decimal amounts (e.g., "10.00"). Treat this as unconfirmed until verified — see Transactions & Fees.

Accounts (Cardholder Account and Card Account)

An Account is an internal ledger — it is never exposed as its own addressable REST resource, and has no accountId. Two kinds exist:

• The Cardholder Account, auto-created on POST /cardholders, which segregates the cardholder's funds at the platform level.
• The Card Account, created for each individual card (PAN). This is what GET /cards/{cardId}/balance returns:

📘

ATM behavior note (from the API specification): the availableBalance returned by this endpoint may differ from what an ATM displays — an ATM may show the lower of availableBalance and the card's transactionLimit. A card with a large available balance but a low per-transaction limit will show the limit at an ATM, not the full balance.

Pending vs. available — the general pattern

The ledgerBalance/availableBalance split follows a consistent "pending vs. complete" pattern across the platform:

• ledgerBalance reflects the full accounting picture, including amounts that are pending, in-process, or on hold (authorization holds for spend; deposits that have cleared an initial confirmation threshold but not yet reached finality).
• availableBalance reflects what's actually spendable right now — amounts that have fully cleared.

This is the same pattern described for digital-asset deposits in Digital-Asset Rails & Custody and for traditional authorization holds in The Card Transaction Lifecycle.

Wallets

A Wallet is an explicitly created, named, fiat-only resource — a sub-ledger separate from any specific Cardholder's Account, typically used for corporate fund pools (see Program Architecture: Corporate use cases).

Creating a wallet

POST /wallets requires only a name:

{ "name": "Acme Corp — Operating Funds" }

The Wallet's currency (walletCurrencyId) is derived from the Program — it isn't specified at creation.

Wallet object fields

Transfers — wallets are always the source

POST /wallets/transfer moves funds from a Wallet to either another Wallet or a Card Account:

❗️

Transfers are one-directional by design. A Wallet can send funds to a Card Account, but there is no corresponding "transfer from card to wallet" operation. If you need to move funds out of a Cardholder's Card Account into a Wallet, that's not currently supported by the documented API — design your fund flows with this constraint in mind.

The response (TransferResponse) includes its own status enum:

🚧

This enum is specific to transfers and is not the same as the transStatus enum used for filtering GET /cards/transactions (1 Pending · 2 Cleared · 3 Completion · 4 Declined · 5 Error — see Pagination, Filtering & Rate Limits). The field name is shared; the value sets are not. The 3 "Partial" status for transfers suggests a transfer can complete for less than the full requested amount — verify this behavior in your sandbox before relying on it.

Deposit Addresses

A Deposit Address is a blockchain address, automatically generated per card, per supported chain, at the moment the card is issued. It appears as the cryptoAddresses array on CardCreateResponse, CardViewMasked, and CardDetailsMasked:

"cryptoAddresses": [
  { "chain": "ethereum", "address": "0x..." },
  { "chain": "bitcoin", "address": "bc1..." },
  { "chain": "solana", "address": "..." }
]

Deposit Addresses are not a balance-holding resource — they have no walletId or balance of their own. They're purely an inbound funnel: digital assets sent here are detected, processed through the confirmation/finality model described in Digital-Asset Rails & Custody, and ultimately reflected in the Card Account's ledgerBalance/availableBalance — never in a Wallet.

📘

If you only remember one thing from this page: "Wallet" always means fiat, and a Deposit Address is never called a "wallet" anywhere in this documentation, precisely to avoid the confusion these similar names would otherwise cause.

How money flows between these objects

flowchart LR
    BANK1["Bank transfer (fiat)"] -->|"register bank account<br/>+ optional trace notification"| CACC["Card Account<br/>(ledgerBalance / availableBalance)"]
    CRYPTO["Digital asset deposit"] -->|"automatic STP"| DA["Deposit Address<br/>(per chain, on the card)"]
    DA --> CACC
    WAL["Wallet<br/>(fiat sub-ledger)"] -->|"POST /wallets/transfer<br/>destinationType=1 (card)"| CACC
    WAL -->|"POST /wallets/transfer<br/>destinationType=0 (wallet)"| WAL2["Another Wallet"]
    BANK2["Bank transfer (fiat)"] -->|"bank-deposit"| WAL

What's next

• Funding & Deposits
• Cards: Virtual vs. Physical
• Transactions & Fees