# Client Account API > Manage accounts, conversions, and withdrawals for clients onboarded with Axiym. Product: Client Account API Guides follow the current API reference (0.3.0) and event reference (0.2.0). Older reference versions are listed separately; the guides are not historical snapshots. Operation references are compact. Follow the linked schemas for field details, or the complete-reference link to retrieve all related definitions in one document. ## Guides and concepts - [Build with the Client Account API](https://docs.sandbox.axiym.io/client-account-api.md): Operate Axiym accounts owned by clients who complete onboarding with Axiym. - [Overview](https://docs.sandbox.axiym.io/client-account-api/concepts/overview.md) - [Clients and onboarding](https://docs.sandbox.axiym.io/client-account-api/concepts/client-scope.md) - [Address book and external accounts](https://docs.sandbox.axiym.io/client-account-api/concepts/address-book.md) - [Axiym accounts and balances](https://docs.sandbox.axiym.io/client-account-api/concepts/accounts-and-balances.md) - [Depositing funds](https://docs.sandbox.axiym.io/client-account-api/concepts/depositing-funds.md) - [Currency conversions](https://docs.sandbox.axiym.io/client-account-api/concepts/currency-conversions.md) - [Withdrawing funds](https://docs.sandbox.axiym.io/client-account-api/concepts/withdrawing-funds.md) - [Notifications and webhooks](https://docs.sandbox.axiym.io/client-account-api/concepts/notifications-and-webhooks.md) - [Terminology](https://docs.sandbox.axiym.io/client-account-api/concepts/terminology.md) - [Getting Started](https://docs.sandbox.axiym.io/client-account-api/integration-guide.md) - [Access and environments](https://docs.sandbox.axiym.io/client-account-api/integration-guide/access-setup.md) - [Client onboarding](https://docs.sandbox.axiym.io/client-account-api/integration-guide/client-onboarding.md): Onboard a client with Axiym before using Client Account API client paths. - [Client context](https://docs.sandbox.axiym.io/client-account-api/integration-guide/client-context.md) - [Sandbox testing](https://docs.sandbox.axiym.io/client-account-api/integration-guide/sandbox-testing.md): Test Client Account API workflows with funded test accounts, wallet testnet transfers, and coordinated bank scenarios. - [Quickstart: Make your first conversion](https://docs.sandbox.axiym.io/client-account-api/integration-guide/quick-start.md) - [Integrate using AI](https://docs.sandbox.axiym.io/client-account-api/integration-guide/integrate-with-ai.md): Use Axiym documentation and an optional integration prompt with your coding agent. - [Add to the address book](https://docs.sandbox.axiym.io/client-account-api/integration-guide/add-to-address-book.md) - [Deposit funds](https://docs.sandbox.axiym.io/client-account-api/integration-guide/deposit-funds.md) - [Execute a conversion](https://docs.sandbox.axiym.io/client-account-api/integration-guide/execute-a-conversion.md) - [Withdraw funds](https://docs.sandbox.axiym.io/client-account-api/integration-guide/withdraw-funds.md) - [Reconcile account activity](https://docs.sandbox.axiym.io/client-account-api/integration-guide/reconcile-activity.md) - [Authentication](https://docs.sandbox.axiym.io/client-account-api/integration-guide/fundamentals/authentication.md): Obtain an OAuth 2.0 access token and authenticate Axiym API requests. - [Common headers](https://docs.sandbox.axiym.io/client-account-api/integration-guide/fundamentals/common-headers.md): Use authentication, tracing, idempotency, and content-type headers consistently. - [Idempotency](https://docs.sandbox.axiym.io/client-account-api/integration-guide/fundamentals/idempotency.md): Retry state-changing requests without creating duplicate operations. - [Pagination and query parameters](https://docs.sandbox.axiym.io/client-account-api/integration-guide/fundamentals/pagination-and-query-parameters.md): Follow cursor-based pages and use list filters without changing resource scope. - [Error handling and retries](https://docs.sandbox.axiym.io/client-account-api/integration-guide/fundamentals/error-handling-and-retries.md): Interpret structured API errors and retry only temporary or ambiguous failures. - [Rate limits](https://docs.sandbox.axiym.io/client-account-api/integration-guide/fundamentals/rate-limits.md): Pace requests and handle throttling using the response headers. - [Data formats and constants](https://docs.sandbox.axiym.io/client-account-api/integration-guide/fundamentals/data-formats-and-constants.md): Store and send identifiers, decimals, currencies, countries, dates, and timestamps correctly. - [Payment Rails](https://docs.sandbox.axiym.io/client-account-api/integration-guide/fundamentals/payment-rails.md): Use account rails correctly across deposits, conversions, and withdrawals. - [Blockchain networks](https://docs.sandbox.axiym.io/client-account-api/integration-guide/fundamentals/blockchain-networks.md): Keep wallet assets, addresses, and networks aligned across Account and Client Account API operations. - [Webhooks Overview](https://docs.sandbox.axiym.io/client-account-api/webhooks/overview.md) - [Events](https://docs.sandbox.axiym.io/client-account-api/webhooks/events.md) - [Webhook Registration and Management](https://docs.sandbox.axiym.io/client-account-api/webhooks/registration-management.md) - [Verifying Webhook Signatures](https://docs.sandbox.axiym.io/client-account-api/webhooks/verifying-signatures.md) ## API reference 0.3.0 (current) [OpenAPI contract](https://docs.sandbox.axiym.io/openapi/client-account-api/0.3.0.yaml) - [Axiym Client Account API](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0.md) - [Get access token](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/auth/oauth/token/post.md): Creates an OAuth 2.0 access token using your client credentials. Request the `ACCOUNT` scope and send the returned token as a bearer token on subsequent Client Account API requests. - [Start client onboarding](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/onboarding/startOnboarding.md): Creates and immediately submits a client onboarding case for compliance review. Document intake is handled through Axiym's compliance KYB flow. Track the case with `GET /onboardings/{clientId}`. - [Get onboarding status](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/onboarding/getOnboardingStatus.md): Returns the current status of one client onboarding case. When the case is `APPROVED`, use the returned `clientId` in Client Account API client paths. - [List clients](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/clients/listClients.md): Returns client records associated with your partnership, including clients that are `ONBOARDING`, `ACTIVE`, or `DISABLED`. Use a returned `clientId` in Client Account API resource paths only when its status is `ACTIVE`. Retrieve rejected onboarding cases through `GET /onboardings/{clientId}`. - [Get client](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/clients/getClient.md): Returns the profile and current Axiym status of one onboarded client. - [List accounts](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/accounts/listAccounts.md): Returns the Axiym accounts belonging to the selected client that your partnership may access. Each account holds a balance in one currency on one payment rail. Use the optional filters to narrow the results by currency or account status. - [Get account](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/accounts/getAccount.md): Returns the current balance, currency, payment rail, and status of one Axiym account belonging to the selected client. - [Get account statement](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/accounts/getAccountStatement.md): Returns the posted credits and debits for one client account, including its opening balance, closing balance, and movement totals. Use the statement to reconcile the client's deposits, conversions, withdrawals, and other ledger movements. The balances follow this equation: `openingBalance + totalCredited - totalDebited = closingBalance` If `from` and `to` are omitted, the statement covers the account's full history. - [Get deposit instructions](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/deposits/getDepositInstructions.md): Returns the receiving details needed to deposit funds into an Axiym account belonging to the selected client. **Before sending funds** Send funds only from a whitelisted external bank account or wallet with status `ACTIVE` in the selected client's address book. Registration is followed by due diligence and compliance checks before activation. **Instruction type** Returns one instruction per transfer scheme the account accepts (`scheme`). Use the instruction for the scheme you send with. - Bank instructions contain the beneficiary, the account number and the receiving bank for the scheme, an intermediary bank when the transfer passes through one, and, when present, an account-specific `reference`. Include the reference on the transfer. - Wallet instructions (`BLOCKCHAIN`) contain the receiving beneficiary name, the wallet address, and the blockchain network to use. - [List deposits](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/deposits/listDeposits.md): Returns incoming payments detected for the selected client's Axiym accounts. Deposits are accepted only from whitelisted external accounts with status `ACTIVE` in the selected client's address book. Use the optional filters to narrow the results by account or deposit status. - [Get deposit](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/deposits/getDeposit.md): Returns one incoming payment for the selected client, including its current status, receiving Axiym account, amount, currency, and available bank or blockchain details. A deposit is credited to the account when its status is `COMPLETED`. - [List conversion pairs](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/conversions/listConversionPairs.md): Returns the conversion directions available to the selected client. Each pair defines the sell currency, buy currency, payment rails, and minimum sell amount. Use `pairId` when creating a conversion for that client. The reverse direction requires a separate pair. - [List conversions](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/conversions/listConversions.md): Returns confirmed conversions created for the selected client. Filter the results by status or `externalReference`. An unconfirmed `PENDING` conversion appears only in the create response and is not included in this list. - [Create conversion](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/conversions/createConversion.md): Creates a conversion quote for the selected client. Provide a permitted `pairId` and the amount to sell. The pair determines the client's sell and buy accounts. The response locks the rate and returns the expected `buyAmount`, fee, and expiry time with status `PENDING`. Confirm the conversion before it expires to begin execution. An unconfirmed conversion does not execute and cannot be retrieved later. - [Get conversion](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/conversions/getConversion.md): Returns one confirmed conversion for the selected client, including its status, sell and buy accounts, amounts, locked rate, and fee. An unconfirmed `PENDING` conversion is available only in the create response. - [Confirm conversion](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/conversions/confirmConversion.md): Accepts the locked quote for a `PENDING` client conversion and begins execution. Confirm before the quote expires. If it has expired, create a new conversion for the client. - [List address book entries](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/address-book/listAddressBookEntries.md): Returns the external bank accounts and wallets registered in the selected client's address book, including their current status. Filter the results by currency or status. An external account is whitelisted for deposits and withdrawals when its status is `ACTIVE`. - [Add a bank account](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/address-book/createBankEntry.md): Registers an external bank account in the selected client's address book for whitelisting. The entry starts in `PENDING_REVIEW` while Axiym performs due diligence and compliance checks. Once approved, its status becomes `ACTIVE` and it can fund deposits and receive withdrawals. The `destination.activated` webhook reports activation. - [Add a wallet address](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/address-book/createWalletEntry.md): Registers an external wallet in the selected client's address book for whitelisting. The entry starts in `PENDING_REVIEW` while Axiym performs due diligence and compliance checks. Once approved, its status becomes `ACTIVE` and it can fund deposits and receive withdrawals. The `destination.activated` webhook reports activation. - [Get an address book entry](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/address-book/getAddressBookEntry.md): Returns an external bank account or wallet registered in the selected client's address book, including its current status and payment details. Its address book identifier is `destinationId`. An external account is whitelisted for deposits and withdrawals when its status is `ACTIVE`. - [List withdrawals](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/withdrawals/listWithdrawals.md): Returns withdrawals created for the selected client. Filter the results by source account, status, or `externalReference`. - [Create withdrawal](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/withdrawals/createWithdrawal.md): Creates a withdrawal from the selected client's Axiym account to a whitelisted external bank account or wallet. **Requirements** - `sourceAccountId` must identify an Axiym account belonging to the selected client. - `destinationId` must identify an external account registered in the selected client's address book. - The source Axiym account and the external account must both be `ACTIVE` and use the same currency. The response includes the withdrawal, source account, and destination details and has status `PENDING_CONFIRMATION`. Creation does not begin execution; confirm the returned `withdrawalId` with `POST /clients/{clientId}/withdrawals/{withdrawalId}/confirm`. - [Confirm withdrawal](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/withdrawals/confirmWithdrawal.md): Confirms a withdrawal in `PENDING_CONFIRMATION` status and begins execution. The request has no body. Use the `withdrawalId` returned by `POST /clients/{clientId}/withdrawals` and provide a new `Idempotency-Key` for this confirmation request. - [Get withdrawal](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/withdrawals/getWithdrawal.md): Returns one withdrawal for the selected client, including its current status, source account, destination, amounts, fee, and any available bank or blockchain details. - [List webhook subscriptions](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/webhook-subscriptions/webhooks/subscriptions/get.md): Returns the active webhook endpoints registered for your partnership. Use pagination to retrieve additional subscriptions when present. - [Create webhook subscription](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/webhook-subscriptions/webhooks/subscriptions/post.md): Registers a publicly reachable HTTPS endpoint to receive webhook notifications available to your partnership. A subscription applies to the endpoint as a whole and does not define per-event filters. Store the returned `subscriptionId` for testing or disabling the subscription. - [Test webhook subscription](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/webhook-subscriptions/webhooks/subscriptions/subscriptionid/tests/post.md): Requests a signed test delivery to the endpoint registered for the specified subscription. Use this to verify endpoint reachability, signature validation, event persistence, and successful `2xx` acknowledgement. A successful API response means the test request was accepted, not that your endpoint processed the delivery successfully. - [Disable webhook subscription](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/webhook-subscriptions/webhooks/subscriptions/subscriptionid/delete.md): Disables the specified webhook subscription. Its endpoint stops receiving new event deliveries, and the subscription is no longer returned when listing active subscriptions. - [Get webhook public key](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/webhook-subscriptions/webhooks/public-keys/publickeyid/get.md): Returns the Ed25519 public key identified by the `X-Key-Id` header on a webhook delivery. Use this key to verify the `X-Signature` value against the raw request body. Cache keys by `publicKeyId` and retrieve a new key when an unfamiliar identifier is received. - [Schemas](https://docs.sandbox.axiym.io/client-account-api/api-reference/0.3.0/schemas.md): Data models used by the Client Account API. ## Event reference 0.2.0 (current) [OpenAPI contract](https://docs.sandbox.axiym.io/openapi/client-account-api/events/0.2.0.yaml) - [Axiym Client Account API Events](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0.md) - [Withdrawal created](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/withdrawal/onWithdrawalCreated.md): Sent once a withdrawal has been confirmed and accepted for execution. - [Withdrawal held](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/withdrawal/onWithdrawalHeld.md): Sent when processing of a withdrawal has been placed temporarily on hold. - [Withdrawal completed](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/withdrawal/onWithdrawalCompleted.md): Sent when a withdrawal has completed successfully. - [Withdrawal canceled](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/withdrawal/onWithdrawalCanceled.md): Sent when a withdrawal has been canceled and will not complete. - [Withdrawal rejected](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/withdrawal/onWithdrawalRejected.md): Sent when a withdrawal has been rejected and will not complete. - [Account credited](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/account/onAccountCredited.md): Sent when a credit has been posted to an account. - [Account debited](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/account/onAccountDebited.md): Sent when a debit has been posted to an account. - [Account activated](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/account/onAccountActivated.md): Sent when an account becomes active and available for supported operations. - [Account suspended](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/account/onAccountSuspended.md): Sent when an account is suspended and temporarily unavailable for supported operations. - [Account closed](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/account/onAccountClosed.md): Sent when an account is permanently closed. - [Address book entry created](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/address-book-entry/onDestinationCreated.md): Sent when an external bank account or wallet is registered in the selected client's address book with status `PENDING_REVIEW`, awaiting due diligence and compliance checks. - [Address book entry activated](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/address-book-entry/onDestinationActivated.md): Sent when due diligence and compliance checks are complete and an external account becomes `ACTIVE`, whitelisted for deposits and withdrawals. - [Address book entry suspended](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/address-book-entry/onDestinationSuspended.md): Sent when a registered external account is suspended and cannot be used for deposits or withdrawals. - [Address book entry closed](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/address-book-entry/onDestinationClosed.md): Sent when a registered external account is permanently closed and can no longer be used for deposits or withdrawals. - [Deposit created](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/deposit/onDepositCreated.md): Sent when an incoming payment has been detected and recorded as a deposit. - [Deposit held](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/deposit/onDepositHeld.md): Sent when processing of a deposit has been placed temporarily on hold. - [Deposit completed](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/deposit/onDepositCompleted.md): Sent when a deposit has completed and the receiving account has been credited. - [Deposit canceled](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/deposit/onDepositCanceled.md): Sent when a deposit has been canceled and will not be credited to the receiving account. - [Deposit rejected](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/deposit/onDepositRejected.md): Sent when a deposit has been rejected and will not be credited to the receiving account. - [Conversion created](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/conversion/onConversionCreated.md): Sent once a conversion has been confirmed and execution has begun. - [Conversion completed](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/conversion/onConversionCompleted.md): Sent when a conversion has completed and the sell-side and buy-side Axiym account movements have been posted. - [Conversion canceled](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/conversion/onConversionCanceled.md): Sent when a conversion has been canceled, expired, or failed and will not complete. - [Client onboarding finished](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/client/onClientOnboardingFinished.md): Deprecated legacy activation event. It is emitted alongside `client.activated` for the same activation moment until legacy integrators migrate. - [Client created](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/client/onClientCreated.md): Sent when Axiym creates a client record for your partnership. - [Client updated](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/client/onClientUpdated.md): Sent when Axiym updates a client record. A disabled or archived update also emits `client.disabled`. - [Client activated](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/client/onClientActivated.md): Sent when an onboarded client becomes available for Client Account API operations, including when a previously disabled client is reactivated. - [Client disabled](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/client/onClientDisabled.md): Sent when an onboarded client can no longer use Client Account API operations. Do not create new Client Account API resources for the client until it is activated again. - [Webhook subscription test](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/webhook-subscription/onSubscriptionTest.md): Sent only when you request a test delivery for a webhook subscription. - [Schemas](https://docs.sandbox.axiym.io/client-account-api/events/0.2.0/schemas.md): Individual event schema definitions.