Address book
Each client's address book is the register of external bank accounts and
wallets that client owns. Each entry is one registered bank account or
wallet. Only ACTIVE entries can fund deposits or receive withdrawals.
The address book establishes the approved external boundary for moving the client's money:
- deposits must originate from an address book entry; and
- withdrawals can be sent only to an address book entry.
Third-party accounts are not supported in either direction.
The two entry nodes represent the same registered resource type; an entry can
be used in either direction. An address book entry does not hold an Axiym
balance. The corresponding Axiym account is the balance-holding resource
identified by accountId.
Ownership follows the client
The client selected by /clients/{clientId} owns the address book and every
Axiym resource it interacts with. An entry belonging to one client cannot fund
or receive withdrawals for another client.
API terminology
| Concept | API representation |
|---|---|
| Address book | The client's collection, exposed under /clients/{clientId}/address-book. |
| Address book entry | One registered bank account (POST .../address-book/bank-accounts) or wallet address (POST .../address-book/wallets). |
| Entry identifier | destinationId. |
The identifier is named destinationId after its most common use: it is the
value you pass as the destination when creating a withdrawal. It identifies
the address book entry itself, which also establishes the permitted origin of
deposits.
Deposits do not pass destinationId. Send funds from an ACTIVE entry using
the receiving details returned in the Axiym account's deposit instructions.
Add entries before moving funds
Adding an entry creates a reusable record of the owned bank account or wallet. It does not itself move money.
Add the entry before initiating a deposit or withdrawal. Do not use an entry that is pending review, suspended, or closed.
Entry types
Bank account
Identified by its currency, account number, bank name, and bank country, with SWIFT/BIC where required. A deposit must be sent from this account, and a withdrawal can return funds to it.
Wallet address
Identified by its currency, wallet address, and blockchain network. A wallet deposit must originate from this wallet on the specified network, and a withdrawal can send funds back to it.
Entry lifecycle
| Status | Meaning |
|---|---|
PENDING_REVIEW | Axiym is reviewing the entry details. |
ACTIVE | The entry is available for supported deposits and withdrawals. |
SUSPENDED | The entry is unavailable for use. |
CLOSED | The entry has been permanently retired. |
Use destination.* webhook events or retrieve the entry to observe status
changes. destination.closed signals that the entry has been permanently
retired and can no longer be used for deposits or withdrawals.
How deposits use the address book
The address book entry identifies where the incoming funds are allowed to come from. Deposit instructions identify where those funds must be sent to credit a particular Axiym account.
For a bank deposit, initiate the transfer from the active registered bank account and include the reference returned in the deposit instructions. The reference matches the deposit to the receiving Axiym account. For a wallet deposit, send from the active registered wallet to the returned wallet address over the specified network; the receiving address identifies the Axiym account.
You do not create the deposit through the Client Trade API. Axiym detects the incoming payment and exposes the resulting deposit for tracking and reconciliation.
How withdrawals use the address book
When creating a withdrawal, pass the entry's destinationId. The entry must
be active, belong to the same client as the source Axiym account, and use the
same currency.
Do not pass a bank account number, wallet address, or Axiym accountId in
place of destinationId.
Continue with Depositing Funds to learn how incoming payments are credited, or Withdrawing Funds to learn how funds leave Axiym.