# Axiym accounts and balances

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/concepts/accounts-and-balances

An **Axiym account** is the balance-holding resource at the center of the Client
Trade API. It represents funds held with Axiym in one currency and connected to one
payment rail.

It is not an external bank account or wallet. Those are registered separately
as [address book entries](/trade-api/concepts/address-book)
and establish where deposits may originate and withdrawals may be sent.

Within one client's resources, there is at most
one account for each currency and payment-rail combination. This lets a
conversion pair identify its sell and buy sides by currency and payment rail;
the API resolves the corresponding account identifiers when the conversion is
created.

For example, a client might have:

| Account            | Currency | Payment rail       | Purpose                                                                                     |
| ------------------ | -------- | ------------------ | ------------------------------------------------------------------------------------------- |
| USD Axiym account  | USD      | Bank rail          | Hold USD received by Axiym, sell USD in permitted conversions, and fund USD withdrawals.    |
| USDT Axiym account | USDT     | Blockchain network | Hold USDT received by Axiym, sell USDT in permitted conversions, and fund USDT withdrawals. |

The API identifies each account with an `accountId`. Use this identifier when
retrieving deposit instructions, statements, and other account-specific
resources.

## Axiym accounts and address book entries

These resources serve different roles and their identifiers are not
interchangeable.

|                    | Axiym account                                  | Address book entry                                    |
| ------------------ | ---------------------------------------------- | ----------------------------------------------------- |
| Where it exists    | With Axiym                                     | At an external bank or on a blockchain network        |
| What it represents | A balance held with Axiym                      | An owned bank account or wallet registered with Axiym |
| Identifier         | `accountId`                                    | `destinationId`                                       |
| Deposits           | Receives the resulting account credit          | Must be the origin of the incoming payment            |
| Withdrawals        | Supplies the balance through `sourceAccountId` | Receives the outgoing payment through `destinationId` |

Deposit instructions belong to an Axiym account. They tell you where to send
funds to credit that account; they do not replace registration of the external
account from which the payment originates.

## What an account tells you

An account contains:

| Field          | Meaning                                                           |
| -------------- | ----------------------------------------------------------------- |
| `accountId`    | The stable identifier for the balance held with Axiym.            |
| `currency`     | The currency held by the account.                                 |
| `paymentRails` | The bank rail or blockchain network on which the account settles. |
| `balance`      | The current amount held with Axiym in the account's currency.     |
| `status`       | Whether the account is active, suspended, or closed.              |

Amounts are returned as decimal strings. Treat the API value as a decimal
amount rather than converting it to a binary floating-point number.

## How balances change

An account balance changes when a ledger movement is posted:

* a completed deposit credits an account;
* a posted withdrawal debit reduces an account's balance;
* a completed conversion debits its `sellAccount` and credits its `buyAccount`;
  or
* an operational adjustment posts directly to the ledger.

Use the current `balance` when you need the amount currently held with Axiym.
Use the account statement when you need to explain how that balance changed.

## Account statements

An account statement provides opening and closing balances, totals for credits
and debits, and the individual ledger entries for a period.

The totals reconcile as follows:

```text
opening balance + total credited - total debited = closing balance
```

Each entry has a direction (`CREDIT` or `DEBIT`), a positive amount, and the
balance after the movement. When the entry relates to a deposit, conversion,
or withdrawal, it also contains the type and identifier of that resource.

This lets you move from a balance difference to the business operation that
caused it.

## Account status

| Status      | Meaning                                            |
| ----------- | -------------------------------------------------- |
| `ACTIVE`    | The account is available for permitted operations. |
| `SUSPENDED` | Use of the account is temporarily restricted.      |
| `CLOSED`    | The account has been permanently retired.          |

Do not assume that having an account grants access to every currency
conversion. The available directions are defined separately by
[conversion pairs](/trade-api/concepts/currency-conversions).

## Related concepts

* [Address Book](/trade-api/concepts/address-book)
  explains which owned bank accounts and wallets can send funds into Axiym or
  receive funds from Axiym.
* [Depositing Funds](/trade-api/concepts/depositing-funds) explains how to
  retrieve payment details and identify incoming deposits.
* [Currency Conversions](/trade-api/concepts/currency-conversions) explains
  how value moves between two Axiym accounts.
* [Withdrawing Funds](/trade-api/concepts/withdrawing-funds)
  explains how value leaves an account.