# Clients and onboarding

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/client-scope

The Client Trade API is a **Partner API**. Your access token identifies the
partnership, while `clientId` in the request path identifies the onboarded
client whose balances and resources you operate.

## How onboarding works

Onboard a client with Axiym before using Client Trade API client paths. You can do
this in either way:

* **API onboarding** — create and immediately submit a case with [Start client
  onboarding](/trade-api/api-reference/0.3.0/onboarding/startOnboarding), then
  either retrieve its review state with [Get onboarding
  status](/trade-api/api-reference/0.3.0/onboarding/getOnboardingStatus) or
  handle the `client.activated` webhook event.
* **Manual onboarding** — work with Axiym to complete the same KYB review
  outside your integration.

Both routes result in an Axiym-issued `clientId`, which you use in
`/clients/{clientId}/...` paths. Retain it alongside your own client reference.
Your `partnerClientId` identifies the client within the partnership. A new
onboarding request using an existing `partnerClientId` returns the existing
case.

## Roles and responsibilities

* The **partner** integrates with Axiym and retains its relationship with the
  represented client.
* The **represented client** completes Axiym KYB onboarding and owns the Axiym
  accounts, address book entries, deposits, conversions, and
  withdrawals operated through its `clientId` paths.
* **Axiym** completes the onboarding review and makes the client's accounts,
  permitted conversion pairs, and other capabilities available after
  activation.

Onboarding for the Client Trade API requires KYB review. It does not include the financial due
diligence and underwriting required for PNSL payment funding.

## Resources for an onboarded client

| Resource             | Path example                                            |
| -------------------- | ------------------------------------------------------- |
| Onboarding case      | `POST /onboardings`, then `GET /onboardings/{clientId}` |
| Clients              | `GET /clients`, `GET /clients/{clientId}`               |
| Accounts             | `GET /clients/{clientId}/accounts`                      |
| Address book entries | `GET /clients/{clientId}/address-book`                  |
| Deposits             | `GET /clients/{clientId}/deposits`                      |
| Conversion pairs     | `GET /clients/{clientId}/conversion-pairs`              |
| Conversions          | `POST /clients/{clientId}/conversions`                  |
| Withdrawals          | `POST /clients/{clientId}/withdrawals`                  |

`clientId` is an Axiym-issued identifier for a client associated with your
partnership. The Client Trade API uses it to resolve the client and enforce resource
ownership. Client operations begin only after onboarding is complete.

The client list includes records in `ONBOARDING`, `ACTIVE`, and `DISABLED`
states. Only an `ACTIVE` client can use Client Trade API resource paths. A rejected
application remains available through its onboarding case rather than the
client list.

The `client.activated` event signals that a client can use Client Trade API resource
paths. Its compact payload is for routing and correlation; retrieve the
onboarding case for the authoritative result. `client.onboarding-finished` is
a deprecated legacy activation event, emitted alongside `client.activated`
during migration. Use client paths only once the client is `ACTIVE`.

## Integration resources

OAuth credentials, webhook subscriptions, and signing keys belong to the
partnership. They do not use a client-prefixed path.

A partnership-level webhook subscription receives events for client-owned
Client Trade API resources. Use the event `clientId` to route activity to the correct
client before retrieving the authoritative resource through its client path.

## Permission comes from client resources

A client relationship does not grant every Client Trade capability. Discover the
effective permissions for each client:

* the account list shows balances available to the integration;
* address book entries show approved funding sources and withdrawal
  recipients; and
* conversion pairs show permitted sell-to-buy directions and payment rails.

## Keep ownership consistent

Every identifier used in an operation must belong to the same `clientId`.

* A deposit must originate from an external account registered for that client.
* A conversion must use a `pairId` returned for that client.
* A withdrawal must use an Axiym account and `destinationId` belonging to that
  client.

Do not combine identifiers from different clients. A not-found response can
indicate a client mismatch as well as an unknown identifier.

## Authentication and retries

Use the same partner access token for every represented client. When retrying a
state-changing operation, keep the `clientId`, endpoint, request body, and
`Idempotency-Key` unchanged.