# Getting Started

Product: Client Account API
Guides follow API reference 0.3.0 and event reference 0.2.0.
Canonical page: https://docs.sandbox.axiym.io/client-account-api/integration-guide

Use this guide to build and operate a Client Account API integration. It assumes you
already understand Axiym accounts, registered external accounts, deposits,
conversions, withdrawals, and client resources as described in
[Concepts & Workflows](/client-account-api/concepts/overview).

Your credentials identify your partnership; `clientId` selects the client
whose Axiym accounts and API resources you operate. External bank accounts
and wallets must be registered in that client’s address book and whitelisted
before they can fund deposits or receive withdrawals.

## Recommended path

### 1. Prepare access

Complete [Access and environments](/client-account-api/integration-guide/access-setup)
to obtain sandbox credentials, provide your egress addresses, and confirm the
Axiym accounts, conversion pairs, and external-account test fixtures available
for testing.

### 2. Onboard the client

Complete [Client onboarding](/client-account-api/integration-guide/client-onboarding).
A client may be onboarded through an API flow or manually with Axiym. In both
cases, retain the Axiym-issued `clientId` and wait until the client is `ACTIVE`
before starting Client Account API business operations.

### 3. Establish client context

Read [Client context](/client-account-api/integration-guide/client-context). Every
business-resource request uses `/clients/{clientId}` and every identifier in a
workflow must belong to that client.

### 4. Understand sandbox testing

Read [Sandbox testing](/client-account-api/integration-guide/sandbox-testing) before
testing payment workflows. It explains test balances, wallet transfers on
testnet, and bank deposit and withdrawal scenarios coordinated with Axiym.

### 5. Complete the quickstart

[Make your first conversion](/client-account-api/integration-guide/quick-start) takes
you from authentication to a confirmed conversion. It is the shortest way to
validate credentials, Axiym account access, permissions, idempotency, and the
quote-and-confirm workflow.

### 6. Implement the workflows you need

| Guide                                                                                | Use it to                                                                                                              |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| [Client onboarding](/client-account-api/integration-guide/client-onboarding)         | Retain the Axiym-issued `clientId`, complete KYB onboarding by API or manually, and wait until the client is `ACTIVE`. |
| [Add to the address book](/client-account-api/integration-guide/add-to-address-book) | Register an external bank account or wallet for whitelisting as a deposit source and withdrawal destination.           |
| [Deposit funds](/client-account-api/integration-guide/deposit-funds)                 | Send funds from a whitelisted external account, identify the resulting deposit, and confirm the Axiym account credit.  |
| [Execute a conversion](/client-account-api/integration-guide/execute-a-conversion)   | Select a permitted pair, create a locked quote, confirm it, and track execution.                                       |
| [Withdraw funds](/client-account-api/integration-guide/withdraw-funds)               | Create and confirm a withdrawal from an Axiym account to an active, whitelisted external account.                      |
| [Reconcile activity](/client-account-api/integration-guide/reconcile-activity)       | Join API resources to account statement entries and verify period balances.                                            |

Register the external account or wallet and wait until its status is `ACTIVE`
before testing a deposit or withdrawal. Activation follows Axiym’s due diligence
and compliance checks; confirm the review process available in sandbox. Keep
the workflow within the selected client’s `/clients/{clientId}` paths.

### 7. Apply the shared conventions

The fundamentals apply across Client Account API operations:

* [Authentication](/client-account-api/integration-guide/fundamentals/authentication)
* [Common Headers](/client-account-api/integration-guide/fundamentals/common-headers)
* [Idempotency](/client-account-api/integration-guide/fundamentals/idempotency)
* [Pagination and List Filters](/client-account-api/integration-guide/fundamentals/pagination-and-query-parameters)
* [Error Handling and Retries](/client-account-api/integration-guide/fundamentals/error-handling-and-retries)
* [Rate Limits](/client-account-api/integration-guide/fundamentals/rate-limits)
* [Data Formats and Constants](/client-account-api/integration-guide/fundamentals/data-formats-and-constants)
* [Payment Rails](/client-account-api/integration-guide/fundamentals/payment-rails)
* [Blockchain Networks](/client-account-api/integration-guide/fundamentals/blockchain-networks)

## Definition of a production-ready integration

Before moving production funds, your integration should be able to:

* obtain new access tokens before expiry without exposing client secrets;
* attach request IDs and idempotency keys correctly;
* preserve `clientId` with every client-owned resource;
* track client onboarding and client availability through polling or webhooks;
* handle asynchronous deposit, conversion, external-account, and
  withdrawal states;
* distinguish simulated sandbox bank activity from real external settlement;
* retry only requests that are safe to retry;
* follow cursor pagination until `hasNextPage` is false; and
* reconcile completed operations against Axiym account statements and the
  corresponding treasury or payment records in your system.