Clients and onboarding

The 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 Trade API client paths. You can do this in either way:

• API onboarding — create a case with Start client onboarding, then either retrieve its review state with Get onboarding status 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 must be unique within the partnership. A duplicate API onboarding request returns 409 Conflict; retrieve the existing case instead.

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 Trade accounts, registered external accounts, 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.

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

Resources for an onboarded client

clientId is an Axiym-issued identifier for a client associated with your partnership. The 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 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 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 if the final status 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 Trade 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 Trade capability. Discover the effective permissions for each client:

• the account list shows balances available to the integration;
• registered external accounts 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.