# Add to the address book

Product: Client Trade API
Guides follow API reference 0.3.0 and event reference 0.2.0.
Canonical page: https://docs.axiym.io/trade-api/integration-guide/add-to-address-book

Add each owned external bank account or wallet to the client's address book
before using it to send funds into Axiym or receive funds from Axiym. The
account must belong to the client selected by `clientId`.

Each entry returns a `destinationId`. Despite the identifier name, an entry is
required for both deposits and withdrawals.

Every request uses `/clients/{clientId}/address-book`. Add only accounts owned
by that client.

## Testing in sandbox

Use only bank details, wallet addresses, blockchain networks, and test assets
provided or approved for your sandbox environment. Never add production
payment details for a sandbox test.

Confirm with Axiym which ownership checks, review outcomes, and lifecycle
transitions are available in sandbox. See
[Sandbox testing](/trade-api/integration-guide/sandbox-testing).

## 1. Add a bank account or wallet

Add a bank account using the details agreed for your sandbox. Replace the
illustrative bank values below before sending the request.

Bank fields depend on the destination corridor: supply `swiftBic` when
required, and `clearingCode` for a required local routing code. Supply
`clearingSystemCode` where the country has more than one clearing system.
Omit unused optional fields instead of sending empty strings.

```sh
curl --request POST \
  "https://partner-api.sandbox.axiym.io/api/v1/clients/$CLIENT_ID/address-book/bank-accounts" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $REGISTER_IDEMPOTENCY_KEY" \
  --data '{
    "currency": "USD",
    "accountNumber": "0123456789",
    "bank": {
      "bankName": "Bank of America",
      "address": { "country": "US" },
      "swiftBic": "BOFAUS3NXXX"
    }
  }'
```

Or add a wallet address:

```sh
curl --request POST \
  "https://partner-api.sandbox.axiym.io/api/v1/clients/$CLIENT_ID/address-book/wallets" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $REGISTER_IDEMPOTENCY_KEY" \
  --data "{\
    \"currency\": \"$EXTERNAL_ACCOUNT_CURRENCY\",\
    \"walletAddress\": \"$TESTNET_WALLET_ADDRESS\",\
    \"network\": \"$BLOCKCHAIN_NETWORK\"\
  }"
```

Use a different idempotency key for each new entry. Reuse the original key
only when retrying the same request after an ambiguous result.

## 2. Store the entry

Store the returned `destinationId` with:

* the `clientId` that owns it;
* whether it is a bank account or wallet;
* its currency and blockchain network where applicable; and
* its current status.

Do not store `destinationId` as an Axiym `accountId`. The identifiers represent
different resources and are not interchangeable.

## 3. Wait for activation

A new entry starts in `PENDING_REVIEW`. Retrieve it until it becomes `ACTIVE`:

```sh
curl \
  "https://partner-api.sandbox.axiym.io/api/v1/clients/$CLIENT_ID/address-book/$DESTINATION_ID" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN"
```

Use `destination.*` events to react to lifecycle changes, and fetch the entry
when your workflow needs its current status. Only `ACTIVE` entries may be used.
`destination.closed` signals that the entry is permanently retired and can no
longer fund deposits or receive withdrawals.

## 4. Use the entry in the correct direction

* **Deposit:** initiate the bank or blockchain payment from the exact account
  or wallet in the entry. Deposit instructions separately identify where the
  payment must be sent.
* **Withdrawal:** pass the entry's `destinationId` when creating the
  withdrawal.

Keep the address book entry, Axiym account, deposit, or withdrawal in the same
client context throughout the workflow.