Add to the 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.

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.

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:

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:

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.