# Direct Trade API

> Operate balances, deposits, currency conversions, and withdrawals in your organization's account context.

Product: Direct Trade API

Guides follow the current API reference (0.1.0) and event reference (0.1.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 Direct Trade API](https://docs.axiym.io/direct-trade-api.md): Operate your organization's Axiym accounts for your own activity or as part of services you provide to clients.
- [Overview](https://docs.axiym.io/direct-trade-api/concepts/overview.md)
- [Address book](https://docs.axiym.io/direct-trade-api/concepts/address-book.md)
- [Axiym accounts and balances](https://docs.axiym.io/direct-trade-api/concepts/accounts-and-balances.md)
- [Depositing funds](https://docs.axiym.io/direct-trade-api/concepts/depositing-funds.md)
- [Currency conversions](https://docs.axiym.io/direct-trade-api/concepts/currency-conversions.md)
- [Withdrawing funds](https://docs.axiym.io/direct-trade-api/concepts/withdrawing-funds.md)
- [Notifications and webhooks](https://docs.axiym.io/direct-trade-api/concepts/notifications-and-webhooks.md)
- [Terminology](https://docs.axiym.io/direct-trade-api/concepts/terminology.md)
- [Getting Started](https://docs.axiym.io/direct-trade-api/integration-guide.md)
- [Access and environments](https://docs.axiym.io/direct-trade-api/integration-guide/access-setup.md)
- [Sandbox testing](https://docs.axiym.io/direct-trade-api/integration-guide/sandbox-testing.md): Test Direct Trade API workflows with funded test accounts, wallet testnet transfers, and coordinated bank scenarios.
- [Quickstart: Make your first conversion](https://docs.axiym.io/direct-trade-api/integration-guide/quick-start.md)
- [Integrate using AI](https://docs.axiym.io/direct-trade-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.axiym.io/direct-trade-api/integration-guide/add-to-address-book.md)
- [Deposit funds](https://docs.axiym.io/direct-trade-api/integration-guide/deposit-funds.md)
- [Execute a conversion](https://docs.axiym.io/direct-trade-api/integration-guide/execute-a-conversion.md)
- [Withdraw funds](https://docs.axiym.io/direct-trade-api/integration-guide/withdraw-funds.md)
- [Reconcile account activity](https://docs.axiym.io/direct-trade-api/integration-guide/reconcile-activity.md)
- [Authentication](https://docs.axiym.io/direct-trade-api/integration-guide/fundamentals/authentication.md): Obtain an OAuth 2.0 access token and authenticate Axiym API requests.
- [Common headers](https://docs.axiym.io/direct-trade-api/integration-guide/fundamentals/common-headers.md): Use authentication, tracing, idempotency, and content-type headers consistently.
- [Idempotency](https://docs.axiym.io/direct-trade-api/integration-guide/fundamentals/idempotency.md): Retry state-changing requests without creating duplicate operations.
- [Pagination and query parameters](https://docs.axiym.io/direct-trade-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.axiym.io/direct-trade-api/integration-guide/fundamentals/error-handling-and-retries.md): Interpret structured API errors and retry only temporary or ambiguous failures.
- [Rate limits](https://docs.axiym.io/direct-trade-api/integration-guide/fundamentals/rate-limits.md): Pace requests and handle throttling using the response headers.
- [Data formats and constants](https://docs.axiym.io/direct-trade-api/integration-guide/fundamentals/data-formats-and-constants.md): Store and send identifiers, decimals, currencies, countries, dates, and timestamps correctly.
- [Payment Rails](https://docs.axiym.io/direct-trade-api/integration-guide/fundamentals/payment-rails.md): Use account rails correctly across deposits, conversions, and withdrawals.
- [Blockchain networks](https://docs.axiym.io/direct-trade-api/integration-guide/fundamentals/blockchain-networks.md): Keep wallet assets, addresses, and networks aligned across Trade API operations.
- [Webhooks Overview](https://docs.axiym.io/direct-trade-api/webhooks/overview.md)
- [Events](https://docs.axiym.io/direct-trade-api/webhooks/events.md)
- [Webhook Registration and Management](https://docs.axiym.io/direct-trade-api/webhooks/registration-management.md)
- [Verifying Webhook Signatures](https://docs.axiym.io/direct-trade-api/webhooks/verifying-signatures.md)

## API reference 0.1.0 (current)

[OpenAPI contract](https://docs.axiym.io/openapi/direct-trade-api/0.1.0.yaml)

- [Axiym Direct Trade API](https://docs.axiym.io/direct-trade-api/api-reference/0.1.0.md)
- [Get access token](https://docs.axiym.io/direct-trade-api/api-reference/0.1.0/auth/oauth/token/post.md): Creates an OAuth 2.0 access token using your client credentials. Request the `TRADE` scope and send the returned token as a bearer token on subsequent Direct Trade API requests.
- [List accounts](https://docs.axiym.io/direct-trade-api/api-reference/0.1.0/accounts/listAccounts.md): Returns your company's Axiym accounts. 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.axiym.io/direct-trade-api/api-reference/0.1.0/accounts/getAccount.md): Returns the current balance, currency, payment rail, and status of one of your Axiym accounts.
- [Get account statement](https://docs.axiym.io/direct-trade-api/api-reference/0.1.0/accounts/getAccountStatement.md): Returns the posted credits and debits for one of your accounts, including its opening balance, closing balance, and movement totals. Use the statement to reconcile your 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.axiym.io/direct-trade-api/api-reference/0.1.0/deposits/getDepositInstructions.md): Returns the receiving details needed to deposit funds into one of your Axiym accounts. **Before sending funds** Send funds only from an `ACTIVE` entry in your address book. Third-party accounts cannot be used. **Instruction type** - Bank instructions contain the receiving-bank details and, when present, an account-specific `reference`. Include the reference on the transfer. - Wallet instructions contain the wallet address and blockchain network to use.
- [List deposits](https://docs.axiym.io/direct-trade-api/api-reference/0.1.0/deposits/listDeposits.md): Returns incoming payments detected for your Axiym accounts. Deposits are accepted only from `ACTIVE` entries in your address book. Use the optional filters to narrow the results by account or deposit status.
- [Get deposit](https://docs.axiym.io/direct-trade-api/api-reference/0.1.0/deposits/getDeposit.md): Returns one incoming payment, including its current status, credited account, amount, currency, and available bank or blockchain details.
- [List conversion pairs](https://docs.axiym.io/direct-trade-api/api-reference/0.1.0/conversions/listConversionPairs.md): Returns the conversion directions available to you. Each pair defines the sell currency, buy currency, payment rails, and minimum sell amount. Use `pairId` when creating a conversion. The reverse direction requires a separate pair.
- [List conversions](https://docs.axiym.io/direct-trade-api/api-reference/0.1.0/conversions/listConversions.md): Returns the confirmed conversions you created. 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.axiym.io/direct-trade-api/api-reference/0.1.0/conversions/createConversion.md): Creates a conversion quote. Provide a permitted `pairId` and the amount to sell. The pair determines the 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.axiym.io/direct-trade-api/api-reference/0.1.0/conversions/getConversion.md): Returns one confirmed conversion, 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.axiym.io/direct-trade-api/api-reference/0.1.0/conversions/confirmConversion.md): Accepts the locked quote for a `PENDING` conversion and begins execution. Confirm before the quote expires. If it has expired, create a new conversion.
- [List address book entries](https://docs.axiym.io/direct-trade-api/api-reference/0.1.0/address-book/listAddressBookEntries.md): Returns the entries in your address book: the external bank accounts and wallets you have registered. Filter the results by currency or status. An `ACTIVE` account may fund your deposits and receive your withdrawals.
- [Add a bank account](https://docs.axiym.io/direct-trade-api/api-reference/0.1.0/address-book/createBankEntry.md): Adds an external bank account you own to the address book. Third-party accounts are not allowed. The account starts in `PENDING_REVIEW`. After it becomes `ACTIVE`, it may fund your deposits and receive your withdrawals. The `destination.activated` webhook reports this change.
- [Add a wallet address](https://docs.axiym.io/direct-trade-api/api-reference/0.1.0/address-book/createWalletEntry.md): Adds an external wallet you own to the address book. Third-party wallets are not allowed. The wallet starts in `PENDING_REVIEW`. After it becomes `ACTIVE`, it may fund your deposits and receive your withdrawals. The `destination.activated` webhook reports this change.
- [Get an address book entry](https://docs.axiym.io/direct-trade-api/api-reference/0.1.0/address-book/getAddressBookEntry.md): Returns one address book entry, including its current status and payment details. An `ACTIVE` account may fund your deposits and receive your withdrawals. Its identifier is returned as `destinationId`.
- [List withdrawals](https://docs.axiym.io/direct-trade-api/api-reference/0.1.0/withdrawals/listWithdrawals.md): Returns the withdrawals you created. Filter the results by source account, status, or `externalReference`.
- [Create withdrawal](https://docs.axiym.io/direct-trade-api/api-reference/0.1.0/withdrawals/createWithdrawal.md): Creates a withdrawal from your Axiym account to one of your address book entries. **Requirements** - `sourceAccountId` and `destinationId` must belong to your company. - Both accounts must be `ACTIVE` and use the same currency. - Third-party external accounts are not allowed. 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 /withdrawals/{withdrawalId}/confirm`.
- [Confirm withdrawal](https://docs.axiym.io/direct-trade-api/api-reference/0.1.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 /withdrawals` and provide a new `Idempotency-Key` for this confirmation request.
- [Get withdrawal](https://docs.axiym.io/direct-trade-api/api-reference/0.1.0/withdrawals/getWithdrawal.md): Returns one withdrawal, including its current status, source account, destination, amounts, fee, and any available bank or blockchain details.
- [List webhook subscriptions](https://docs.axiym.io/direct-trade-api/api-reference/0.1.0/webhook-subscriptions/webhooks/subscriptions/get.md): Returns the active webhook endpoints registered for your company. Use pagination to retrieve additional subscriptions when present.
- [Create webhook subscription](https://docs.axiym.io/direct-trade-api/api-reference/0.1.0/webhook-subscriptions/webhooks/subscriptions/post.md): Registers a publicly reachable HTTPS endpoint to receive webhook notifications available to your company. 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.axiym.io/direct-trade-api/api-reference/0.1.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.axiym.io/direct-trade-api/api-reference/0.1.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.axiym.io/direct-trade-api/api-reference/0.1.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.axiym.io/direct-trade-api/api-reference/0.1.0/schemas.md): Data models used by the Direct Trade API.

## Event reference 0.1.0 (current)

[OpenAPI contract](https://docs.axiym.io/openapi/direct-trade-api/events/0.1.0.yaml)

- [Axiym Direct Trade API Events](https://docs.axiym.io/direct-trade-api/events/0.1.0.md)
- [Withdrawal created](https://docs.axiym.io/direct-trade-api/events/0.1.0/withdrawal/onWithdrawalCreated.md): Sent once a withdrawal has been confirmed and accepted for execution.
- [Withdrawal held](https://docs.axiym.io/direct-trade-api/events/0.1.0/withdrawal/onWithdrawalHeld.md): Sent when processing of a withdrawal has been placed temporarily on hold.
- [Withdrawal completed](https://docs.axiym.io/direct-trade-api/events/0.1.0/withdrawal/onWithdrawalCompleted.md): Sent when a withdrawal has completed successfully.
- [Withdrawal canceled](https://docs.axiym.io/direct-trade-api/events/0.1.0/withdrawal/onWithdrawalCanceled.md): Sent when a withdrawal has been canceled and will not complete.
- [Withdrawal rejected](https://docs.axiym.io/direct-trade-api/events/0.1.0/withdrawal/onWithdrawalRejected.md): Sent when a withdrawal has been rejected and will not complete.
- [Account credited](https://docs.axiym.io/direct-trade-api/events/0.1.0/account/onAccountCredited.md): Sent when a credit has been posted to an account.
- [Account debited](https://docs.axiym.io/direct-trade-api/events/0.1.0/account/onAccountDebited.md): Sent when a debit has been posted to an account.
- [Account activated](https://docs.axiym.io/direct-trade-api/events/0.1.0/account/onAccountActivated.md): Sent when an account becomes active and available for supported operations.
- [Account suspended](https://docs.axiym.io/direct-trade-api/events/0.1.0/account/onAccountSuspended.md): Sent when an account is suspended and temporarily unavailable for supported operations.
- [Account closed](https://docs.axiym.io/direct-trade-api/events/0.1.0/account/onAccountClosed.md): Sent when an account is permanently closed.
- [Address book entry created](https://docs.axiym.io/direct-trade-api/events/0.1.0/address-book-entry/onDestinationCreated.md): Sent when an owned external bank account or wallet has been added to the address book and is awaiting review.
- [Address book entry activated](https://docs.axiym.io/direct-trade-api/events/0.1.0/address-book-entry/onDestinationActivated.md): Sent when an address book entry is approved and becomes available as a permitted deposit source and withdrawal recipient.
- [Address book entry suspended](https://docs.axiym.io/direct-trade-api/events/0.1.0/address-book-entry/onDestinationSuspended.md): Sent when an address book entry is suspended and cannot be used for deposits or withdrawals.
- [Address book entry closed](https://docs.axiym.io/direct-trade-api/events/0.1.0/address-book-entry/onDestinationClosed.md): Sent when an address book entry is permanently closed and can no longer be used for deposits or withdrawals.
- [Deposit created](https://docs.axiym.io/direct-trade-api/events/0.1.0/deposit/onDepositCreated.md): Sent when an incoming payment has been detected and recorded as a deposit.
- [Deposit held](https://docs.axiym.io/direct-trade-api/events/0.1.0/deposit/onDepositHeld.md): Sent when processing of a deposit has been placed temporarily on hold.
- [Deposit completed](https://docs.axiym.io/direct-trade-api/events/0.1.0/deposit/onDepositCompleted.md): Sent when a deposit has completed and the receiving account has been credited.
- [Deposit canceled](https://docs.axiym.io/direct-trade-api/events/0.1.0/deposit/onDepositCanceled.md): Sent when a deposit has been canceled and will not be credited to the receiving account.
- [Deposit rejected](https://docs.axiym.io/direct-trade-api/events/0.1.0/deposit/onDepositRejected.md): Sent when a deposit has been rejected and will not be credited to the receiving account.
- [Conversion created](https://docs.axiym.io/direct-trade-api/events/0.1.0/conversion/onConversionCreated.md): Sent once a conversion has been confirmed and execution has begun.
- [Conversion completed](https://docs.axiym.io/direct-trade-api/events/0.1.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.axiym.io/direct-trade-api/events/0.1.0/conversion/onConversionCanceled.md): Sent when a conversion has been canceled, expired, or failed and will not complete.
- [Webhook subscription test](https://docs.axiym.io/direct-trade-api/events/0.1.0/webhook-subscription/onSubscriptionTest.md): Sent only when you request a test delivery for a webhook subscription.

- [Schemas](https://docs.axiym.io/direct-trade-api/events/0.1.0/schemas.md): Individual event schema definitions.