# Getting Started

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

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

## Recommended path

### 1. Prepare access

Complete [Access and environments](/trade-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](/trade-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 Trade API business operations.

### 3. Establish client context

Read [Client context](/trade-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](/trade-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](/trade-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](/trade-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](/trade-api/integration-guide/add-to-address-book) | Register an owned bank account or wallet for use as a deposit source and withdrawal recipient.                         |
| [Deposit funds](/trade-api/integration-guide/deposit-funds)                 | Send funds from an address book entry, identify the resulting deposit, and confirm the Axiym account credit.           |
| [Execute a conversion](/trade-api/integration-guide/execute-a-conversion)   | Select a permitted pair, create a locked quote, confirm it, and track execution.                                       |
| [Withdraw funds](/trade-api/integration-guide/withdraw-funds)               | Create and confirm a withdrawal from an Axiym account to an active address book entry.                                 |
| [Reconcile activity](/trade-api/integration-guide/reconcile-activity)       | Join API resources to account statement entries and verify period balances.                                            |

Register the external account and wait until its address book entry is `ACTIVE`
before testing a deposit or withdrawal. The workflow sequence uses the represented client's
`/clients/{clientId}` paths.

### 7. Apply the shared conventions

The fundamentals apply across Client Trade API operations:

* [Authentication](/trade-api/integration-guide/fundamentals/authentication)
* [Common Headers](/trade-api/integration-guide/fundamentals/common-headers)
* [Idempotency](/trade-api/integration-guide/fundamentals/idempotency)
* [Pagination and List Filters](/trade-api/integration-guide/fundamentals/pagination-and-query-parameters)
* [Error Handling and Retries](/trade-api/integration-guide/fundamentals/error-handling-and-retries)
* [Rate Limits](/trade-api/integration-guide/fundamentals/rate-limits)
* [Data Formats and Constants](/trade-api/integration-guide/fundamentals/data-formats-and-constants)
* [Payment Rails](/trade-api/integration-guide/fundamentals/payment-rails)
* [Blockchain Networks](/trade-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, address book entry, 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.