Address book
Your address book is the register of external bank accounts and wallets
your company 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 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.
This ownership rule still applies when you use Direct Trade as part of a service for your clients. A client’s bank account or wallet does not become an address book entry owned by your organization.
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.
API terminology
| Concept | API representation |
|---|---|
| Address book | The collection exposed under /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 Direct 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 and use the same currency as the source Axiym account.
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.