# Address book

Product: Direct Trade API
Guides follow API reference 0.1.0 and event reference 0.1.0.
Canonical page: https://docs.axiym.io/direct-trade-api/concepts/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.



```mermaid
flowchart TD
  funding["Address book entry"] -->|Deposit| axiym["Axiym account"]
  axiym -->|Withdrawal| receiving["Address book entry"]

  class funding,receiving externalNode
  class axiym accountNode
  classDef externalNode stroke-width:1.5px
  classDef accountNode stroke-width:2px
```



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.



```mermaid
flowchart TD
  register["Add an owned bank account or wallet"] --> review["PENDING_REVIEW"]
  review --> active["ACTIVE"]
  active --> deposit["Use as the source of deposits"]
  active --> withdrawal["Use as the recipient of withdrawals"]

  class register actionNode
  class review reviewNode
  class active activeNode
  class deposit,withdrawal actionNode
  classDef actionNode stroke-width:1.25px
  classDef reviewNode stroke-width:1.5px
  classDef activeNode stroke-width:1.5px
```



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](/direct-trade-api/concepts/depositing-funds)
to learn how incoming payments are credited, or
[Withdrawing Funds](/direct-trade-api/concepts/withdrawing-funds) to learn how
funds leave Axiym.