openapi: 3.1.0 info: title: Axiym Account API version: 0.3.0 description: |- Use the Account API to view Axiym accounts, registered address book entries, and account activity; retrieve deposit instructions and track deposits; create and confirm withdrawals; and receive webhook notifications. The access token identifies the organization that owns every account, address book entry, deposit, withdrawal, and webhook subscription. ## Deposit flow 1. Retrieve the receiving details with `GET /accounts/{accountId}/deposit-instructions`. 2. Send the funds from an `ACTIVE` address book entry using those details. 3. Track the incoming payment with `GET /deposits` and `GET /deposits/{depositId}` or deposit webhooks. ## Withdrawal flow 1. Select an `ACTIVE` source account and an `ACTIVE` address book entry in the same currency. 2. Create the withdrawal with `POST /withdrawals`. The response returns its `withdrawalId` in `PENDING_CONFIRMATION` status. 3. Confirm that identifier with `POST /withdrawals/{withdrawalId}/confirm` to begin execution. 4. Track the outcome with `GET /withdrawals/{withdrawalId}` or withdrawal webhooks. servers: - url: https://partner-api.sandbox.axiym.io/api/v1 description: Sandbox - url: https://partner-api.axiym.io/api/v1 description: Production security: - Default: [] tags: - name: Auth description: OAuth 2.0 client credentials authentication. - name: Accounts description: Axiym accounts, balances, and posted ledger activity. - name: Address Book description: Registered external bank accounts and wallet addresses you own — the permitted deposit sources and withdrawal destinations. - name: Deposits description: Incoming funds credited to your Axiym accounts. - name: Withdrawals description: Outgoing payments from Axiym accounts to registered address book entries. - name: Webhook Subscriptions description: Webhook subscription management and webhook public keys. paths: /oauth/token: post: summary: Get access token description: |- Exchange your OAuth client credentials for an Account API access token. Send the returned token as `Authorization: Bearer ` on subsequent requests. Request the `ACCOUNT` scope. deprecated: false tags: - Auth parameters: - $ref: "#/components/parameters/RequestId" requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: client_id: type: string examples: - eb81336d-378a-4ab8-8c0e-a2f39ac0e87a example: eb81336d-378a-4ab8-8c0e-a2f39ac0e87a client_secret: type: string examples: - >- d5a9df2f93dba5f3def1e1d7585f476f054fe955a02e6b152f3145adce49c6ffc94be6ea7a2d7385f111f17541c1fe0239e8902b33e41fed7610098995081d3e59b2fe7ae2877dcbcdcd04c14cdfa298e85a079066d0b1e0eaaa978110ba300c7e8341b68c0d9a8deb03122f4504e6317b53b473c5917e4ae073422241f59120 example: >- d5a9df2f93dba5f3def1e1d7585f476f054fe955a02e6b152f3145adce49c6ffc94be6ea7a2d7385f111f17541c1fe0239e8902b33e41fed7610098995081d3e59b2fe7ae2877dcbcdcd04c14cdfa298e85a079066d0b1e0eaaa978110ba300c7e8341b68c0d9a8deb03122f4504e6317b53b473c5917e4ae073422241f59120 grant_type: type: string examples: - client_credentials example: client_credentials scope: type: string enum: - ACCOUNT examples: - ACCOUNT example: ACCOUNT example: client_id: eb81336d-378a-4ab8-8c0e-a2f39ac0e87a client_secret: >- d5a9df2f93dba5f3def1e1d7585f476f054fe955a02e6b152f3145adce49c6ffc94be6ea7a2d7385f111f17541c1fe0239e8902b33e41fed7610098995081d3e59b2fe7ae2877dcbcdcd04c14cdfa298e85a079066d0b1e0eaaa978110ba300c7e8341b68c0d9a8deb03122f4504e6317b53b473c5917e4ae073422241f59120 grant_type: client_credentials scope: ACCOUNT required: true responses: "201": description: "" content: application/json: schema: type: object properties: token_type: type: string expires_in: type: integer access_token: type: string scope: type: string required: - token_type - expires_in - access_token - scope headers: {} "400": $ref: "#/components/responses/BadRequest" description: "" "401": $ref: "#/components/responses/Unauthorized" description: "" "500": $ref: "#/components/responses/InternalError" description: "" security: [] /accounts: get: tags: - Accounts summary: List accounts operationId: listAccounts description: |- Returns the Axiym accounts available to your organization. Each account holds a balance in one currency. Use the optional filters to narrow the result by currency or account status. parameters: - $ref: "#/components/parameters/RequestId" - name: first in: query description: Maximum number of items to return (page size). required: false schema: type: integer default: 10 maximum: 100 examples: - 10 - name: after in: query description: Cursor for the next page, from the previous response's pageInfo.endCursor. required: false schema: type: string examples: - eyJvZmZzZXQiOjI1fQ== - name: currency in: query schema: $ref: "#/components/schemas/Currency" examples: - USD description: Filter by currency. - name: status in: query schema: $ref: "#/components/schemas/AccountStatus" examples: - ACTIVE description: Filter by status. responses: "200": description: Accounts. content: application/json: schema: type: object required: - nodes - pageInfo properties: nodes: type: array items: $ref: "#/components/schemas/Account" pageInfo: $ref: "#/components/schemas/PageInfo" examples: Accounts: summary: Bank and wallet accounts value: nodes: - accountId: 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e currency: USD paymentRails: ZENUS_BANK balance: "48250.00" status: ACTIVE - accountId: 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a currency: USDT paymentRails: TRON balance: "12500.00" status: ACTIVE pageInfo: hasNextPage: false "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" /accounts/{accountId}: get: tags: - Accounts summary: Get account operationId: getAccount description: Returns the current balance, currency, payment rail, and status of one Axiym account. parameters: - $ref: "#/components/parameters/AccountId" - $ref: "#/components/parameters/RequestId" responses: "200": description: Account. content: application/json: schema: $ref: "#/components/schemas/Account" examples: Bank account: summary: Bank account value: accountId: 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e currency: USD paymentRails: ZENUS_BANK balance: "48250.00" status: ACTIVE Wallet account: summary: Wallet account value: accountId: 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a currency: USDT paymentRails: TRON balance: "12500.00" status: ACTIVE "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" /accounts/{accountId}/statement: get: tags: - Accounts summary: Get account statement operationId: getAccountStatement description: |- Returns posted credits and debits for one account, including opening and closing balances, movement totals, and entries in posting order. **Reconciliation** `openingBalance + totalCredited - totalDebited = closingBalance` Each entry also carries its running balance. Without `from` and `to`, the statement covers the account's full history. parameters: - $ref: "#/components/parameters/AccountId" - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/First" - $ref: "#/components/parameters/After" - name: from in: query required: false description: >- First calendar day of the period (UTC), inclusive. The period bounds apply to the posting time of the movement. schema: type: string format: date examples: - "2026-06-01" - name: to in: query required: false description: >- Last calendar day of the period (UTC), inclusive. Adjacent statements chain without gaps: June `to=2026-06-30` is followed by July `from=2026-07-01`. schema: type: string format: date examples: - "2026-06-30" - name: type in: query required: false description: Filter by credit or debit direction. schema: $ref: "#/components/schemas/StatementEntryType" examples: - DEBIT responses: "200": description: Account statement for the period. content: application/json: schema: type: object required: - openingBalance - closingBalance - totalCredited - totalDebited - nodes - pageInfo properties: openingBalance: allOf: - $ref: "#/components/schemas/Decimal" description: Balance as of the start of the period (`from`). examples: - "47750.00" closingBalance: allOf: - $ref: "#/components/schemas/Decimal" description: Balance as of the end of the period (`to`). examples: - "48250.00" totalCredited: allOf: - $ref: "#/components/schemas/Decimal" description: Sum of credits within the period. examples: - "1005.00" totalDebited: allOf: - $ref: "#/components/schemas/Decimal" description: Sum of debits within the period. examples: - "505.00" nodes: type: array items: $ref: "#/components/schemas/StatementEntry" pageInfo: $ref: "#/components/schemas/PageInfo" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" /accounts/{accountId}/deposit-instructions: get: tags: - Deposits summary: Get deposit instructions operationId: getDepositInstructions description: |- 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. parameters: - $ref: "#/components/parameters/AccountId" - $ref: "#/components/parameters/RequestId" responses: "200": description: Deposit instructions for the account. content: application/json: schema: $ref: "#/components/schemas/DepositInstruction" examples: Bank transfer: summary: Bank transfer value: beneficiaryName: Axi Labs AG accountNumber: "1050004921" swiftBic: ZEITPRSJXXX bankName: Zenus Bank International Inc. reference: RF11 0004 4901 01 Wallet transfer: summary: Wallet transfer value: walletAddress: TWd2yzw5yFc5W8Tq6CuNZcVJgfmLnBcT4Q network: TRON "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" /deposits: get: tags: - Deposits summary: List deposits operationId: listDeposits parameters: - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/First" - $ref: "#/components/parameters/After" - name: accountId in: query description: Filter by account. schema: type: string format: uuid examples: - 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a - name: status in: query schema: $ref: "#/components/schemas/DepositStatus" examples: - COMPLETED description: Filter by status. responses: "200": description: Page of deposits. content: application/json: schema: type: object required: - nodes - pageInfo properties: nodes: type: array items: $ref: "#/components/schemas/Deposit" pageInfo: $ref: "#/components/schemas/PageInfo" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" description: |- 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. /deposits/{depositId}: get: tags: - Deposits summary: Get deposit description: Returns one incoming payment, including its current status, credited account, amount, currency, and available bank or blockchain details. operationId: getDeposit parameters: - $ref: "#/components/parameters/DepositId" - $ref: "#/components/parameters/RequestId" responses: "200": description: Deposit. content: application/json: schema: $ref: "#/components/schemas/Deposit" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" /address-book: get: tags: - Address Book summary: List address book entries operationId: listAddressBookEntries description: |- Returns registered external bank accounts and wallet addresses available as withdrawal destinations. Only an `ACTIVE` entry can receive a withdrawal. Use the optional filters to narrow the result by currency or status. parameters: - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/First" - $ref: "#/components/parameters/After" - name: currency in: query schema: $ref: "#/components/schemas/Currency" examples: - USD description: Filter by currency. - name: status in: query schema: $ref: "#/components/schemas/DestinationStatus" examples: - ACTIVE description: Filter by status. responses: "200": description: Page of your address book entries. content: application/json: schema: type: object required: - nodes - pageInfo properties: nodes: type: array items: $ref: "#/components/schemas/AddressBookEntry" pageInfo: $ref: "#/components/schemas/PageInfo" examples: Address book entries: summary: A bank account and a wallet address value: nodes: - destinationId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 status: ACTIVE currency: USD accountNumber: "0123456789" bank: bankName: Bank of America address: city: New York country: US swiftBic: BOFAUS3NXXX createdAt: "2026-06-12T14:05:00Z" - destinationId: e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c status: ACTIVE currency: USDT walletAddress: TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL network: TRON createdAt: "2026-06-12T14:05:00Z" pageInfo: hasNextPage: false "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" /address-book/{destinationId}: get: tags: - Address Book summary: Get an address book entry operationId: getAddressBookEntry description: |- Returns one registered external bank account or wallet address, including its payment details and current status. Use its `destinationId` when creating a withdrawal after the entry is `ACTIVE`. parameters: - $ref: "#/components/parameters/DestinationId" - $ref: "#/components/parameters/RequestId" responses: "200": description: Address book entry. content: application/json: schema: $ref: "#/components/schemas/AddressBookEntry" examples: Bank account: summary: Bank account value: destinationId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 status: ACTIVE currency: USD accountNumber: "0123456789" bank: bankName: Bank of America address: city: New York country: US swiftBic: BOFAUS3NXXX createdAt: "2026-06-12T14:05:00Z" Wallet address: summary: Wallet address value: destinationId: e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c status: ACTIVE currency: USDT walletAddress: TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL network: TRON createdAt: "2026-06-12T14:05:00Z" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" /withdrawals: get: tags: - Withdrawals x-axiym-navigation-order: 10 summary: List withdrawals operationId: listWithdrawals description: |- Returns withdrawals created from your Axiym accounts, including their current execution status. Use the optional filters to narrow the result by source account, status, or `externalReference`. parameters: - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/First" - $ref: "#/components/parameters/After" - name: accountId in: query description: Filter by account. schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 - name: status in: query schema: $ref: "#/components/schemas/WithdrawalStatus" examples: - PENDING description: Filter by status. - name: externalReference in: query description: Filter by your external reference. schema: type: string examples: - wd-2026-0714-01 responses: "200": description: Page of withdrawals. content: application/json: schema: type: object required: - nodes - pageInfo properties: nodes: type: array items: $ref: "#/components/schemas/Withdrawal" pageInfo: $ref: "#/components/schemas/PageInfo" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" post: tags: - Withdrawals x-axiym-navigation-order: 20 summary: Create withdrawal operationId: createWithdrawal description: |- Creates an outgoing withdrawal from `sourceAccountId` to the address book entry selected by `destinationId`. **Requirements** - The source account and destination must be `ACTIVE`. - They must use the same currency. - `destinationId` must identify a registered address book entry. The response contains the resolved source and destination details and has status `PENDING_CONFIRMATION`. Creation does not begin execution; confirm the returned `withdrawalId` with `POST /withdrawals/{withdrawalId}/confirm`. parameters: - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/WithdrawalRequest" examples: Wallet: summary: Wallet value: sourceAccountId: 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a sourceAmount: amount: "500.00" currency: USDT destinationId: e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c reference: Treasury sweep externalReference: wd-2026-0714-01 Bank: summary: Bank value: sourceAccountId: 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e sourceAmount: amount: "12500.00" currency: USD destinationId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 reference: Invoice INV-20416 externalReference: wd-2026-0714-02 responses: "201": description: Withdrawal created and awaiting confirmation. content: application/json: schema: $ref: "#/components/schemas/Withdrawal" examples: Wallet: summary: Wallet value: withdrawalId: 9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e status: PENDING_CONFIRMATION sourceAccount: accountId: 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a currency: USDT paymentRails: TRON sourceAmount: amount: "500.00" currency: USDT destinationAmount: amount: "500.00" currency: USDT fee: amount: "0.00" currency: USDT destination: destinationId: e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c currency: USDT walletAddress: TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL network: TRON code: AXI00000418 reference: Treasury sweep externalReference: wd-2026-0714-01 createdAt: "2026-07-14T20:06:50Z" Bank: summary: Bank value: withdrawalId: 1e7c5a3b-8d2f-4b6e-9a0c-3d5f7b9e1c2a status: PENDING_CONFIRMATION sourceAccount: accountId: 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e currency: USD paymentRails: ZENUS_BANK sourceAmount: amount: "12500.00" currency: USD destinationAmount: amount: "12500.00" currency: USD fee: amount: "0.00" currency: USD destination: destinationId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 currency: USD accountNumber: "0123456789" bank: bankName: Bank of America address: city: New York country: US swiftBic: BOFAUS3NXXX code: AXI00000419 reference: Invoice INV-20416 externalReference: wd-2026-0714-02 createdAt: "2026-07-14T20:06:50Z" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" /withdrawals/{withdrawalId}: get: tags: - Withdrawals x-axiym-navigation-order: 40 summary: Get withdrawal operationId: getWithdrawal description: |- Returns the current state of one withdrawal, including its source account, destination, amounts, fee, and any completed wallet transaction hash. Use this as the authoritative status after creation or confirmation and when processing withdrawal webhooks. parameters: - $ref: "#/components/parameters/WithdrawalId" - $ref: "#/components/parameters/RequestId" responses: "200": description: Withdrawal. content: application/json: schema: $ref: "#/components/schemas/Withdrawal" examples: Wallet (completed): summary: Wallet (completed) value: withdrawalId: 9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e status: COMPLETED sourceAccount: accountId: 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a currency: USDT paymentRails: TRON sourceAmount: amount: "500.00" currency: USDT destinationAmount: amount: "500.00" currency: USDT fee: amount: "0.00" currency: USDT destination: destinationId: e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c currency: USDT walletAddress: TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL network: TRON code: AXI00000418 transactionHash: "9f8e7d6c5b4a39281706f5e4d3c2b1a0998877665544332211ffeeddccbbaa00" reference: Treasury sweep externalReference: wd-2026-0714-01 createdAt: "2026-07-14T20:06:50Z" Bank (completed): summary: Bank (completed) value: withdrawalId: 1e7c5a3b-8d2f-4b6e-9a0c-3d5f7b9e1c2a status: COMPLETED sourceAccount: accountId: 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e currency: USD paymentRails: ZENUS_BANK sourceAmount: amount: "12500.00" currency: USD destinationAmount: amount: "12500.00" currency: USD fee: amount: "0.00" currency: USD destination: destinationId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 currency: USD accountNumber: "0123456789" bank: bankName: Bank of America address: city: New York country: US swiftBic: BOFAUS3NXXX code: AXI00000419 reference: Invoice INV-20416 externalReference: wd-2026-0714-02 createdAt: "2026-07-14T20:06:50Z" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" /withdrawals/{withdrawalId}/confirm: post: tags: - Withdrawals x-axiym-navigation-order: 30 summary: Confirm withdrawal operationId: confirmWithdrawal description: |- 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. parameters: - $ref: "#/components/parameters/WithdrawalId" - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/IdempotencyKey" responses: "200": description: Withdrawal confirmed and queued for execution. content: application/json: schema: $ref: "#/components/schemas/Withdrawal" examples: Confirmed bank withdrawal: summary: Confirmed bank withdrawal value: withdrawalId: 1e7c5a3b-8d2f-4b6e-9a0c-3d5f7b9e1c2a status: PENDING sourceAccount: accountId: 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e currency: USD paymentRails: ZENUS_BANK sourceAmount: amount: "12500.00" currency: USD destinationAmount: amount: "12500.00" currency: USD fee: amount: "0.00" currency: USD destination: destinationId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 currency: USD accountNumber: "0123456789" bank: bankName: Bank of America address: city: New York country: US swiftBic: BOFAUS3NXXX code: AXI00000419 reference: Invoice INV-20416 externalReference: wd-2026-0714-02 createdAt: "2026-07-14T20:06:50Z" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" /webhooks/subscriptions: get: summary: List webhook subscriptions description: Returns the webhook subscriptions registered by your organization. deprecated: false tags: - Webhook Subscriptions parameters: - $ref: "#/components/parameters/RequestId" - name: first in: query description: Maximum number of items to return (page size). required: false schema: type: integer default: 10 maximum: 100 examples: - 20 - name: after in: query description: Cursor for the next page, from the previous response's pageInfo.endCursor. required: false schema: type: string examples: - eyJvZmZzZXQiOjI1fQ== responses: "200": description: "" content: application/json: schema: type: object properties: nodes: type: array items: $ref: "#/components/schemas/Subscription" pageInfo: $ref: "#/components/schemas/PageInfo" required: - nodes - pageInfo headers: {} "400": $ref: "#/components/responses/BadRequest" description: "" "401": $ref: "#/components/responses/Unauthorized" description: "" "403": $ref: "#/components/responses/Forbidden" description: Forbidden "422": $ref: "#/components/responses/InvalidParams" description: "" "500": $ref: "#/components/responses/InternalError" description: "" security: - Default: [] post: summary: Create webhook subscription description: |- Registers an HTTPS endpoint to receive account, address book, and withdrawal notifications. Your endpoint must be publicly reachable and return a `2XX` response to the webhook `POST` request. deprecated: false tags: - Webhook Subscriptions parameters: - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/IdempotencyKey" requestBody: content: application/json: schema: type: object properties: endpoint: type: string title: "" description: >- URL of the endpoint to subscribe to notifications. Must be publicly accessible, use HTTPS, and respond with a 2XX status to a POST request. required: - endpoint responses: "201": description: "" content: application/json: schema: $ref: "#/components/schemas/Subscription" headers: {} "400": $ref: "#/components/responses/BadRequest" description: "" "401": $ref: "#/components/responses/Unauthorized" description: "" "403": $ref: "#/components/responses/Forbidden" description: Forbidden "422": $ref: "#/components/responses/InvalidParams" description: "" "500": $ref: "#/components/responses/InternalError" description: "" security: - Default: [] /webhooks/subscriptions/{subscriptionId}/tests: post: summary: Test webhook subscription description: Sends a test notification to one registered webhook endpoint. deprecated: false tags: - Webhook Subscriptions parameters: - name: subscriptionId in: path description: Subscription identifier (UUID). required: true schema: type: string examples: - "" - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/IdempotencyKey" responses: "201": description: "" content: application/json: schema: $ref: "#/components/schemas/RequestStatus" headers: {} "400": $ref: "#/components/responses/BadRequest" description: "" "401": $ref: "#/components/responses/Unauthorized" description: "" "403": $ref: "#/components/responses/Forbidden" description: Forbidden "404": $ref: "#/components/responses/NotFound" description: "" "422": $ref: "#/components/responses/InvalidParams" description: "" "500": $ref: "#/components/responses/InternalError" description: "" security: - Default: [] /webhooks/subscriptions/{subscriptionId}: delete: summary: Disable webhook subscription description: Disables one webhook subscription so it no longer receives notifications. deprecated: false tags: - Webhook Subscriptions parameters: - name: subscriptionId in: path description: Subscription identifier (UUID). required: true schema: type: string format: uuid examples: - "" - $ref: "#/components/parameters/RequestId" responses: "200": description: "" content: application/json: schema: $ref: "#/components/schemas/Subscription" headers: {} "400": $ref: "#/components/responses/BadRequest" description: "" "401": $ref: "#/components/responses/Unauthorized" description: "" "403": $ref: "#/components/responses/Forbidden" description: Forbidden "404": $ref: "#/components/responses/NotFound" description: "" "422": $ref: "#/components/responses/InvalidParams" description: "" "500": $ref: "#/components/responses/InternalError" description: "" security: - Default: [] /webhooks/public-keys/{publicKeyId}: get: summary: Get webhook public key description: Returns a public key used to verify webhook signatures. deprecated: false tags: - Webhook Subscriptions parameters: - name: publicKeyId in: path description: Public key identifier (UUID). required: true schema: type: string examples: - "" - $ref: "#/components/parameters/RequestId" responses: "200": description: "" content: application/json: schema: $ref: "#/components/schemas/PublicKey" headers: {} "400": $ref: "#/components/responses/BadRequest" description: "" "401": $ref: "#/components/responses/Unauthorized" description: "" "403": $ref: "#/components/responses/Forbidden" description: Forbidden "404": $ref: "#/components/responses/NotFound" description: "" "422": $ref: "#/components/responses/InvalidParams" description: "" "500": $ref: "#/components/responses/InternalError" description: "" security: - Default: [] components: securitySchemes: Default: type: http scheme: bearer bearerFormat: JWT parameters: RequestId: name: X-Request-Id in: header required: false description: |- Optional client-generated request identifier (UUID recommended) for end-to-end tracing. Axiym echoes it in the `X-Request-Id` response header and records it in logs. Quote it when contacting support. If omitted, Axiym generates one. schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 AccountId: name: accountId in: path required: true schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 description: Account identifier (UUID). First: name: first in: query description: Maximum number of items to return (page size). schema: type: integer minimum: 1 maximum: 100 default: 20 examples: - 20 After: name: after in: query description: Cursor for the next page, from the previous response's pageInfo.endCursor. schema: type: string examples: - eyJvZmZzZXQiOjI1fQ== IdempotencyKey: name: Idempotency-Key in: header required: true description: |- Unique client-generated key for safely retrying a funds-moving request. A UUID is recommended, but any unique string is accepted. Repeating the same request with the same key returns the original result instead of creating a duplicate withdrawal or confirmation. schema: type: string maxLength: 255 examples: - a1b2c3d4-e5f6-7890-abcd-ef1234567890 DestinationId: name: destinationId in: path required: true schema: type: string format: uuid examples: - e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c description: Address book entry identifier (UUID). DepositId: name: depositId in: path required: true schema: type: string format: uuid examples: - 4c8e2b6a-1d9f-4e3b-a7c5-2f0a8d6b4e1c description: Deposit identifier (UUID). WithdrawalId: name: withdrawalId in: path required: true schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 description: Withdrawal identifier (UUID). schemas: Currency: type: string description: Currency code — ISO 4217 (e.g. USD, EUR) or a supported digital currency (USDT, USDC). examples: - USD AccountStatus: type: string enum: - ACTIVE - SUSPENDED - CLOSED examples: - ACTIVE Account: type: object description: An account holding a currency balance. required: - accountId - currency - paymentRails - balance - status properties: accountId: type: string format: uuid description: Account identifier (UUID). examples: - 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e currency: $ref: "#/components/schemas/Currency" description: Account currency. examples: - USD paymentRails: $ref: "#/components/schemas/PaymentRailsCode" description: Rail the account settles on. examples: - ZENUS_BANK balance: allOf: - $ref: "#/components/schemas/Decimal" description: Current balance. examples: - "48250.00" status: $ref: "#/components/schemas/AccountStatus" description: Account status. examples: - ACTIVE PaymentRailsCode: type: string description: Payment rail code the account settles on (e.g. `ZENUS_BANK`, `TRON`). examples: - ZENUS_BANK AccountRef: type: object description: Compact account reference. Fetch the account via `GET /accounts/{accountId}` for the current balance and status; deposit instructions serve its payment details. required: - accountId - currency - paymentRails properties: accountId: type: string format: uuid description: Account identifier (UUID). examples: - 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e currency: $ref: "#/components/schemas/Currency" description: Account currency. examples: - USD paymentRails: $ref: "#/components/schemas/PaymentRailsCode" description: Rail the account settles on. examples: - ZENUS_BANK StatementEntryType: type: string description: Direction of movement on the account. enum: - CREDIT - DEBIT examples: - DEBIT StatementEntry: type: object description: |- A posted ledger movement on an account. Entries are returned in posting order and include the running balance, so consecutive entries reconcile against each other. required: - entryId - accountId - type - amount - currency - balanceAfter - occurredAt properties: entryId: type: string format: uuid description: Ledger entry identifier (UUID). examples: - 7f9a2d1c-8b31-4f59-9e2f-1d63c4a27b12 accountId: type: string format: uuid description: Account identifier (UUID). examples: - 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a type: $ref: "#/components/schemas/StatementEntryType" description: Credit or debit direction. examples: - DEBIT amount: allOf: - $ref: "#/components/schemas/Decimal" description: Positive movement amount in the account currency; direction is in `type`. examples: - "500.00" currency: $ref: "#/components/schemas/Currency" description: Account currency. examples: - USDT balanceBefore: allOf: - $ref: "#/components/schemas/Decimal" description: Running balance before this movement. examples: - "12500.00" balanceAfter: allOf: - $ref: "#/components/schemas/Decimal" description: Running balance after this movement. examples: - "12000.00" relatedResourceType: type: string description: >- Type of the linked money movement; absent for ledger adjustments with no linked resource. enum: - DEPOSIT - WITHDRAWAL - CONVERSION - PAYOUT examples: - WITHDRAWAL relatedResourceId: type: string format: uuid description: Identifier of the linked resource, where present. examples: - 9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e occurredAt: type: string format: date-time description: When the movement occurred. Formatted in ISO 8601. examples: - "2026-07-14T20:07:31Z" Bank: type: object description: |- Destination bank details. Present on bank destinations only. The bank address country selects the applicable payout corridor rules. Supply `swiftBic`, `clearingCode`, or `clearingSystemCode` when that corridor requires them. additionalProperties: false required: - bankName - address properties: bankName: type: string minLength: 1 description: Bank name. examples: - Bank of America address: $ref: "#/components/schemas/BankAddress" swiftBic: type: string pattern: ^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$ description: ISO 9362 SWIFT/BIC, when required for the corridor. examples: - BOFAUS3NXXX clearingCode: type: string description: Local clearing or routing code, when required for the corridor. examples: - "026009593" clearingSystemCode: type: string description: Clearing system the code belongs to. Axiym derives it from the bank country; supply it where a country has more than one system. examples: - USABA BankAddress: type: object description: |- Postal address of the destination bank. `country` is always required because it selects the applicable corridor rules. Supply the remaining address fields when the corridor or a correspondent requires them. additionalProperties: false required: - country properties: streetName: type: string buildingNumber: type: string city: type: string examples: - New York region: type: string postalCode: type: string country: $ref: "#/components/schemas/CountryCode" CountryCode: type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. examples: - US DepositStatus: type: string description: | `PENDING` awaits crediting. `HELD` is temporarily on hold. `COMPLETED` was credited to the account. `CANCELED` or `REJECTED` was not completed; see `reasonCode`. enum: - PENDING - HELD - COMPLETED - CANCELED - REJECTED examples: - COMPLETED Deposit: type: object required: - depositId - account - amount - status - createdAt properties: depositId: type: string format: uuid description: Deposit identifier (UUID). examples: - 4c8e2b6a-1d9f-4e3b-a7c5-2f0a8d6b4e1c account: allOf: - $ref: "#/components/schemas/AccountRef" description: The account the deposit credits, embedded as a compact reference. amount: allOf: - $ref: "#/components/schemas/Money" description: Amount credited to the account. fee: allOf: - $ref: "#/components/schemas/Money" description: Fee charged, when any. status: $ref: "#/components/schemas/DepositStatus" description: Deposit status. examples: - COMPLETED remitterName: type: string description: Name of the sender, as reported by the sending bank or network. examples: - Globex Corporation code: type: string description: System-assigned payment code, shown on the payment. examples: - AXI00000417 transactionHash: type: string description: The transaction hash on the network. Present for wallet deposits. examples: - "1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f809" reasonCode: type: string description: "Present when `status` is `CANCELED` or `REJECTED` — the reason as reported by the bank, the network, or Axiym operations. Example: `SENDER_SCREENING_FAILED`." createdAt: type: string format: date-time description: Creation timestamp. Formatted in ISO 8601. examples: - 2026-06-14T18:02:11Z DepositInstruction: description: Axiym's receiving details for the account; the shape matches the account type. oneOf: - $ref: "#/components/schemas/BankDepositInstruction" - $ref: "#/components/schemas/WalletDepositInstruction" BankDepositInstruction: type: object title: Bank transfer required: - beneficiaryName - accountNumber - swiftBic - bankName properties: beneficiaryName: type: string description: Name of the receiving party to put on the transfer. examples: - Axi Labs AG accountNumber: type: string description: Receiving bank account number. examples: - "1050004921" swiftBic: type: string description: SWIFT/BIC code of the receiving bank. examples: - ZEITPRSJXXX bankName: type: string description: Receiving bank name. examples: - Zenus Bank International Inc. reference: type: string description: ISO 11649 creditor reference (`RF` + check digits) assigned by Axiym, formatted in groups of four. Present when the account is funded through a shared receiving account; include it on the transfer so the deposit is matched automatically (matching ignores the spaces). Absent when the receiving account number alone identifies the Axiym account. examples: - RF11 0004 4901 01 WalletDepositInstruction: type: object title: Wallet transfer required: - walletAddress - network properties: walletAddress: type: string description: Deposit address of the account; deposits are matched by the address itself. examples: - TWd2yzw5yFc5W8Tq6CuNZcVJgfmLnBcT4Q network: $ref: "#/components/schemas/Network" description: Network of the wallet address. examples: - TRON DepositEventData: type: object description: A compact notification for routing and correlation. Retrieve the deposit from `GET /deposits/{depositId}` when you need its amount, transaction hash, or current state. required: - depositId - status properties: depositId: type: string format: uuid description: Deposit identifier (UUID). examples: - 4c8e2b6a-1d9f-4e3b-a7c5-2f0a8d6b4e1c status: $ref: "#/components/schemas/DepositStatus" description: Deposit status at the time the event was emitted. examples: - COMPLETED reasonCode: type: string description: "Present on `deposit.canceled` / `deposit.rejected` — the reason as reported by the bank, the network, or Axiym operations. Example: `SENDER_SCREENING_FAILED`." DestinationStatus: type: string description: |- - `PENDING_REVIEW` — awaiting review. - `ACTIVE` — available for withdrawals. - `SUSPENDED` — temporarily unavailable. - `CLOSED` — permanently retired. enum: - PENDING_REVIEW - ACTIVE - SUSPENDED - CLOSED examples: - ACTIVE AddressBookEntry: description: |- A registered external bank account or wallet address in the address book, with its status and creation date. - A bank destination contains `accountNumber` and `bank`. - A wallet destination contains `walletAddress` and `network`. The two field sets never appear together. oneOf: - $ref: "#/components/schemas/BankAddressBookEntry" - $ref: "#/components/schemas/WalletAddressBookEntry" BankAddressBookEntry: type: object title: Bank account required: - destinationId - status - currency - accountNumber - bank properties: destinationId: type: string format: uuid description: Address book entry identifier (UUID). examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 status: $ref: "#/components/schemas/DestinationStatus" description: Address book entry status. examples: - ACTIVE currency: $ref: "#/components/schemas/Currency" description: Currency the destination is paid in. examples: - USD accountNumber: type: string description: Bank account number. examples: - "0123456789" bank: $ref: "#/components/schemas/Bank" description: Destination bank details. createdAt: type: string format: date-time description: Creation timestamp. Formatted in ISO 8601. examples: - "2026-06-12T14:05:00Z" WalletAddressBookEntry: type: object title: Wallet address required: - destinationId - status - currency - walletAddress - network properties: destinationId: type: string format: uuid description: Address book entry identifier (UUID). examples: - e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c status: $ref: "#/components/schemas/DestinationStatus" description: Address book entry status. examples: - ACTIVE currency: $ref: "#/components/schemas/Currency" description: Currency the destination is paid in. examples: - USDT walletAddress: type: string description: Destination wallet address; static and reusable. examples: - TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL network: $ref: "#/components/schemas/Network" description: Network of the wallet address. examples: - TRON createdAt: type: string format: date-time description: Creation timestamp. Formatted in ISO 8601. examples: - "2026-06-12T14:05:00Z" Destination: description: |- Where the funds are delivered, as recorded on the operation at creation time. This is a snapshot: it carries the account or wallet details and, when the destination was taken from the address book, its `destinationId`. It does not carry the address book entry's status or creation date; read the address book entry for its current state. - A bank destination contains `accountNumber` and `bank`. - A wallet destination contains `walletAddress` and `network`. The two field sets never appear together. oneOf: - $ref: "#/components/schemas/BankDestination" - $ref: "#/components/schemas/WalletDestination" BankDestination: type: object title: Bank account required: - currency - accountNumber - bank properties: destinationId: type: string format: uuid description: Address book entry the destination was taken from, when applicable. examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 currency: $ref: "#/components/schemas/Currency" description: Currency delivered to the destination. examples: - USD accountNumber: type: string description: Bank account number or IBAN. examples: - "0123456789" bank: $ref: "#/components/schemas/Bank" description: Destination bank details. WalletDestination: type: object title: Wallet address required: - currency - walletAddress - network properties: destinationId: type: string format: uuid description: Address book entry the destination was taken from, when applicable. examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 currency: $ref: "#/components/schemas/Currency" description: Currency delivered to the destination. examples: - USDT walletAddress: type: string description: Wallet address on the given network. examples: - TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL network: $ref: "#/components/schemas/Network" description: Network of the wallet address. examples: - TRON PageInfo: type: object properties: hasNextPage: type: boolean description: When paginating forwards, are there more items? examples: - true endCursor: type: string description: When paginating forwards, the cursor to continue. examples: - eyJvZmZzZXQiOjI1fQ== required: - hasNextPage WithdrawalStatus: type: string description: |- - `PENDING_CONFIRMATION` — created and awaiting confirmation. - `PENDING` — confirmed and awaiting execution. - `HELD` — temporarily on hold; no action is needed. - `COMPLETED` — completed successfully. - `CANCELED` or `REJECTED` — not completed; see `reasonCode` when present. enum: - PENDING_CONFIRMATION - PENDING - HELD - COMPLETED - CANCELED - REJECTED examples: - PENDING Withdrawal: type: object required: - withdrawalId - sourceAccount - sourceAmount - destinationAmount - fee - destination - status - createdAt properties: withdrawalId: type: string format: uuid description: Withdrawal identifier (UUID). examples: - 9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e sourceAccount: allOf: - $ref: "#/components/schemas/AccountRef" description: The source account, embedded as a compact reference. sourceAmount: allOf: - $ref: "#/components/schemas/Money" description: Amount debited from the source account, in the source account currency. destinationAmount: allOf: - $ref: "#/components/schemas/Money" description: Amount delivered to the destination, in the destination currency. Equals `sourceAmount` less `fee`. fee: allOf: - $ref: "#/components/schemas/Money" description: Total deducted from `sourceAmount` before delivery, in the source account currency. Zero when no fee applies. destination: allOf: - $ref: "#/components/schemas/Destination" description: Snapshot of the destination selected by `destinationId` at creation time. status: $ref: "#/components/schemas/WithdrawalStatus" description: Withdrawal status. examples: - COMPLETED code: type: string description: System-assigned payment code, shown on the payment. examples: - AXI00000418 reference: type: string description: Text shown to the recipient, as submitted. examples: - Treasury sweep supportingDocuments: type: array items: $ref: "#/components/schemas/SupportingDocument" description: Documents accepted with the payment. File content is not returned. externalReference: $ref: "#/components/schemas/ExternalReference" description: Your reference for correlation, echoed back on related objects. examples: - wd-2026-0714-01 transactionHash: type: string description: >- The transaction hash on the network. Present for wallet withdrawals once the withdrawal is `COMPLETED`. examples: - "9f8e7d6c5b4a39281706f5e4d3c2b1a0998877665544332211ffeeddccbbaa00" reasonCode: type: string description: >- Present when `status` is `CANCELED` or `REJECTED` — the cancellation/rejection reason as reported by the bank, the network, or Axiym operations. Example: `INSUFFICIENT_BENEFICIARY_DETAILS`. createdAt: type: string format: date-time description: Creation timestamp. Formatted in ISO 8601. examples: - "2026-07-14T20:06:50Z" WithdrawalRequest: type: object description: |- An outgoing payment from `sourceAccountId` to `destinationId`. `sourceAmount` is debited from the source account in its currency. The destination must be an `ACTIVE` address book entry in the same currency. Creation returns a withdrawal awaiting confirmation; it does not begin execution. additionalProperties: false required: - sourceAccountId - sourceAmount - destinationId properties: sourceAccountId: type: string format: uuid description: Source account identifier (UUID). examples: - 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a sourceAmount: allOf: - $ref: "#/components/schemas/Money" description: Amount to debit from the source account. Its currency must be the source account currency. destinationId: type: string format: uuid description: Identifier of the address book entry to pay. It must be `ACTIVE` and in the source Axiym account's currency. examples: - e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c reference: type: string maxLength: 140 description: Text shown to the recipient, typically the invoice number. examples: - Invoice INV-20416 supportingDocuments: type: array maxItems: 10 items: $ref: "#/components/schemas/SupportingDocumentInput" description: Documents supporting the payment, such as an invoice. Required where the destination corridor requires evidence. externalReference: $ref: "#/components/schemas/ExternalReference" description: Your reference for correlation, echoed back on related objects. examples: - wd-2026-0714-01 SupportingDocumentType: type: string description: Axiym classification of evidence supplied with a payout. enum: - PASSPORT - NATIONAL_ID - DRIVER_LICENSE - RESIDENCE_PERMIT - PROOF_OF_ADDRESS - UTILITY_BILL - BANK_STATEMENT - TAX_CERTIFICATE - CERTIFICATE_OF_INCORPORATION - REGISTRY_EXTRACT - ARTICLES_OF_ASSOCIATION - SHAREHOLDER_REGISTER - DIRECTOR_REGISTER - UBO_DECLARATION - POWER_OF_ATTORNEY - BOARD_RESOLUTION - REGULATORY_LICENSE - BUSINESS_LICENSE - FINANCIAL_STATEMENT - AUDIT_REPORT - SOURCE_OF_FUNDS - INVOICE - CONTRACT - PURCHASE_ORDER - PAYROLL_FILE - LOAN_AGREEMENT - SHIPPING_DOCUMENT - CUSTOMS_DECLARATION - OTHER examples: - INVOICE SupportingDocumentInput: type: object description: "A document supporting the payment, such as an invoice or contract. One item is one file of up to 10 MB in PDF, JPEG or PNG format; supply the file content as base64." additionalProperties: false required: - documentType - data - name properties: documentType: $ref: "#/components/schemas/SupportingDocumentType" data: type: string contentEncoding: base64 description: Complete file encoded as base64 from its raw bytes. Do not include a data-URL prefix. name: type: string minLength: 1 maxLength: 255 description: File name, including the extension. examples: - INV-20416.pdf SupportingDocument: type: object description: Metadata of a document accepted with the payment. File content is not returned. additionalProperties: false required: - documentType - fileId - name - contentType - size properties: documentType: $ref: "#/components/schemas/SupportingDocumentType" fileId: type: string format: uuid description: Identifier of the stored file. name: type: string description: File name supplied with the document. contentType: type: string description: MIME type detected from the file content. examples: - application/pdf size: type: integer description: File size in bytes. WithdrawalEventData: type: object description: |- Compact webhook payload for routing and correlation. Webhooks are notifications, not state transfer. Fetch `GET /withdrawals/{withdrawalId}` for the authoritative amounts, fee, destination, and transaction hash. required: - withdrawalId - status properties: withdrawalId: type: string format: uuid description: Withdrawal identifier (UUID). examples: - 9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e status: $ref: "#/components/schemas/WithdrawalStatus" description: Withdrawal status at the time the event was emitted. examples: - COMPLETED externalReference: $ref: "#/components/schemas/ExternalReference" description: Your reference submitted on creation, where present. examples: - wd-2026-0714-01 reasonCode: type: string description: >- Present on `withdrawal.canceled` / `withdrawal.rejected` — the reason as reported by the bank, the network, or Axiym operations. Example: `INSUFFICIENT_BENEFICIARY_DETAILS`. AccountMovementEventData: type: object description: |- A posted ledger movement on an account. Movements are immutable facts, so the event contains the amount but not the current balance. Fetch `GET /accounts/{accountId}` for that balance. required: - accountId - amount - currency - occurredAt properties: accountId: type: string format: uuid description: Account identifier (UUID). examples: - 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a amount: allOf: - $ref: "#/components/schemas/Decimal" description: Positive movement amount in the account currency; direction is in the event type. examples: - "500.00" currency: $ref: "#/components/schemas/Currency" description: Account currency. examples: - USDT relatedResourceType: type: string description: >- Type of the linked money movement; absent for movements with no linked API resource. enum: - DEPOSIT - WITHDRAWAL - CONVERSION - PAYOUT examples: - WITHDRAWAL relatedResourceId: type: string format: uuid description: Identifier of the linked resource, where present. examples: - 9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e occurredAt: type: string format: date-time description: When the movement occurred. Formatted in ISO 8601. examples: - "2026-07-14T20:07:31Z" AccountStatusEventData: type: object description: Account lifecycle notification. required: - accountId - status properties: accountId: type: string format: uuid description: Account identifier (UUID). examples: - 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a status: $ref: "#/components/schemas/AccountStatus" description: Account status at the time the event was emitted. examples: - SUSPENDED DestinationEventData: type: object description: Address book entry lifecycle notification. required: - destinationId - status properties: destinationId: type: string format: uuid description: Address book entry identifier (UUID). examples: - e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c status: $ref: "#/components/schemas/DestinationStatus" description: Address book entry status at the time the event was emitted. examples: - ACTIVE Event: type: object description: Webhook event envelope delivered to your registered endpoint. required: - id - timestamp - data properties: id: type: string format: uuid description: Event ID. Use this for de-duplication. examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 timestamp: type: string format: date-time description: Event timestamp. Formatted in ISO 8601. examples: - "2026-07-14T20:08:00Z" type: type: string description: Event type. examples: - withdrawal.completed data: type: object properties: {} description: Event data. Subscription: type: object properties: subscriptionId: type: string description: Subscription identifier (UUID). format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 endpoint: type: string description: >- URL of the endpoint to subscribe to notifications. Must be publicly accessible, use HTTPS, and respond with a 2XX status to a POST request. title: "" format: uri examples: - https://api.acme.example/webhooks required: - subscriptionId - endpoint RequestStatus: type: object properties: status: type: string description: Request status. examples: - OK default: OK enum: - OK required: - status PublicKey: type: object properties: publicKeyId: type: string description: Public key identifier (UUID). format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 active: type: boolean description: Indicates whether the key is active examples: - true algorithm: type: string description: Encryption algorithm examples: - ED25519 publicKey: type: string description: Public Key examples: - string createdAt: type: string format: date-time description: Creation timestamp. Formatted in ISO 8601. examples: - "2026-07-14T20:08:00Z" required: - publicKeyId - algorithm - publicKey - createdAt - active Money: type: object description: Monetary amount and its currency. additionalProperties: false required: - amount - currency properties: amount: $ref: "#/components/schemas/Decimal" currency: $ref: "#/components/schemas/Currency" Decimal: type: string description: Decimal number serialized as a string to preserve precision. Amounts sent to Axiym are positive and carry at most 8 decimal places. examples: - "1000.00" ExternalReference: type: string maxLength: 255 description: |- Optional identifier for correlating the resource with your system. Axiym returns it on reads and webhook events. It does not make retries safe; use `Idempotency-Key` to deduplicate retries. examples: - wd-2026-0714-01 ValidationFieldErrors: description: |- Recursive validation-error structure. - A leaf field contains an array of `ValidationError` records. - A nested object is keyed by field name. - A list is keyed by array index. oneOf: - type: array items: $ref: "#/components/schemas/ValidationError" - type: object additionalProperties: $ref: "#/components/schemas/ValidationFieldErrors" properties: {} Network: type: string description: Wallet network. enum: - TRON - AVALANCHE examples: - TRON ValidationError: type: object description: Single validation error from the `validator` crate. properties: code: type: string description: >- Validation rule code (e.g. 'length', 'email', 'invalid_currency', 'disbursement_account_required'). examples: - length message: type: - string - "null" description: Human-readable message. examples: - string params: type: object description: >- Rule-specific parameters. Always includes `value` (the offending input). Additional keys depend on the rule (e.g. `min`, `max` for length). properties: value: description: The submitted value that failed validation. examples: - string required: - code - params responses: BadRequest: description: "" content: application/json: schema: type: object properties: code: type: integer description: HTTP status code, duplicated in the body. message: type: string description: Human-readable message describing the error. errors: type: - object - "null" properties: message: type: string description: Additional error details; null when there are none. required: - code - message - errors examples: Malformed JSON body: summary: Malformed JSON body value: code: 400 message: Bad Request errors: message: "Failed to parse the request body as JSON: expected value at line 1 column 5" Generic: summary: Generic value: code: 400 message: Invalid cursor errors: null headers: X-Request-Id: description: >- Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request. schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unauthorized: description: "" content: application/json: schema: type: object properties: code: type: integer description: HTTP status code, duplicated in the body. message: type: string description: Human-readable message describing the error. errors: type: - object - "null" description: Additional error details; null when there are none. required: - code - message - errors examples: Example 1: summary: Example 1 value: code: 401 message: Unauthorized errors: null headers: X-Request-Id: description: >- Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request. schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 InternalError: description: "" content: application/json: schema: type: object properties: code: type: integer description: HTTP status code, duplicated in the body. message: type: string description: Human-readable message describing the error. errors: type: - object - "null" description: Additional error details; null when there are none. required: - code - message - errors examples: Example 1: summary: Example 1 value: code: 500 message: Internal Error errors: null headers: X-Request-Id: description: >- Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request. schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 Forbidden: description: Forbidden content: application/json: schema: type: object properties: code: type: integer description: HTTP status code, duplicated in the body. message: type: string description: Human-readable message describing the error. errors: type: - object - "null" description: Additional error details; null when there are none. required: - code - message - errors examples: Example 1: summary: Example 1 value: code: 403 message: Forbidden errors: null headers: X-Request-Id: description: >- Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request. schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 NotFound: description: "" content: application/json: schema: type: object properties: code: type: integer description: HTTP status code, duplicated in the body. message: type: string description: >- Human-readable message: either the generic 'Not Found' or a domain-specific one such as 'Client Not Found'. errors: type: - object - "null" description: Additional error details; null when there are none. required: - code - message - errors examples: Generic: summary: Generic value: code: 404 message: Not Found errors: null Client not found: summary: Client not found value: code: 404 message: Client Not Found errors: null headers: X-Request-Id: description: >- Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request. schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 InvalidParams: description: >- The request could not be processed. Two variants share this status: a validation failure, where `errors` is an object keyed by field name, and a business rejection, where `errors` is null and `message` states the reason (e.g. `Documents Not Accepted` when uploading to an already decided onboarding application, or the generic `Unprocessable Request`). content: application/json: schema: type: object properties: code: type: integer description: HTTP status code, duplicated in the body. message: type: string description: "`Invalid Parameters` for validation failures; the rejection reason otherwise." errors: type: - object - "null" description: >- Validation failures: object keyed by field name (camelCase); each value is either an array of ValidationError records (leaf), a nested object for struct fields, or an object keyed by array index for list fields. Business rejections: null. additionalProperties: $ref: "#/components/schemas/ValidationFieldErrors" required: - code - message - errors examples: Flat field errors: summary: Flat field errors value: code: 422 message: Invalid Parameters errors: legalEntityName: - code: length message: null params: value: "" min: 1 currency: - code: invalid_currency message: null params: value: ZZZ Nested struct errors: summary: Nested struct errors value: code: 422 message: Invalid Parameters errors: legalAddress: country: - code: invalid_country message: null params: value: INVALID postalCode: - code: length message: null params: value: "" min: 1 List item errors: summary: List item errors value: code: 422 message: Invalid Parameters errors: authorizedDirectors: "0": firstName: - code: length message: null params: value: "" min: 1 email: - code: email message: null params: value: not-an-email Custom validator: summary: Custom validator value: code: 422 message: Invalid Parameters errors: disbursementAccount: - code: disbursement_account_required message: null params: value: null Business rejection: summary: Business rejection value: code: 422 message: Documents Not Accepted errors: null headers: X-Request-Id: description: >- Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request. schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 webhooks: withdrawal.created: post: tags: - Webhooks/Withdrawal summary: Created operationId: onWithdrawalCreated security: [] requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: withdrawal.created data: $ref: "#/components/schemas/WithdrawalEventData" responses: "200": description: Acknowledged by your endpoint. withdrawal.held: post: tags: - Webhooks/Withdrawal summary: Held operationId: onWithdrawalHeld security: [] requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: withdrawal.held data: $ref: "#/components/schemas/WithdrawalEventData" responses: "200": description: Acknowledged by your endpoint. withdrawal.completed: post: tags: - Webhooks/Withdrawal summary: Completed operationId: onWithdrawalCompleted security: [] requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: withdrawal.completed data: $ref: "#/components/schemas/WithdrawalEventData" responses: "200": description: Acknowledged by your endpoint. withdrawal.canceled: post: tags: - Webhooks/Withdrawal summary: Canceled operationId: onWithdrawalCanceled security: [] requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: withdrawal.canceled data: $ref: "#/components/schemas/WithdrawalEventData" responses: "200": description: Acknowledged by your endpoint. withdrawal.rejected: post: tags: - Webhooks/Withdrawal summary: Rejected operationId: onWithdrawalRejected security: [] requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: withdrawal.rejected data: $ref: "#/components/schemas/WithdrawalEventData" responses: "200": description: Acknowledged by your endpoint. account.credited: post: tags: - Webhooks/Account summary: Credited operationId: onAccountCredited security: [] requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: account.credited data: $ref: "#/components/schemas/AccountMovementEventData" responses: "200": description: Acknowledged by your endpoint. account.debited: post: tags: - Webhooks/Account summary: Debited operationId: onAccountDebited security: [] requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: account.debited data: $ref: "#/components/schemas/AccountMovementEventData" responses: "200": description: Acknowledged by your endpoint. account.activated: post: tags: - Webhooks/Account summary: Activated operationId: onAccountActivated security: [] requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: account.activated data: $ref: "#/components/schemas/AccountStatusEventData" responses: "200": description: Acknowledged by your endpoint. account.suspended: post: tags: - Webhooks/Account summary: Suspended operationId: onAccountSuspended security: [] requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: account.suspended data: $ref: "#/components/schemas/AccountStatusEventData" responses: "200": description: Acknowledged by your endpoint. account.closed: post: tags: - Webhooks/Account summary: Closed operationId: onAccountClosed security: [] requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: account.closed data: $ref: "#/components/schemas/AccountStatusEventData" responses: "200": description: Acknowledged by your endpoint. deposit.created: post: tags: - Webhooks/Deposit summary: Created operationId: onDepositCreated security: [] requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: deposit.created data: $ref: "#/components/schemas/DepositEventData" responses: "200": description: Acknowledged by your endpoint. deposit.held: post: tags: - Webhooks/Deposit summary: Held operationId: onDepositHeld security: [] requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: deposit.held data: $ref: "#/components/schemas/DepositEventData" responses: "200": description: Acknowledged by your endpoint. deposit.completed: post: tags: - Webhooks/Deposit summary: Completed operationId: onDepositCompleted security: [] requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: deposit.completed data: $ref: "#/components/schemas/DepositEventData" responses: "200": description: Acknowledged by your endpoint. deposit.canceled: post: tags: - Webhooks/Deposit summary: Canceled operationId: onDepositCanceled security: [] requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: deposit.canceled data: $ref: "#/components/schemas/DepositEventData" responses: "200": description: Acknowledged by your endpoint. deposit.rejected: post: tags: - Webhooks/Deposit summary: Rejected operationId: onDepositRejected security: [] requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: deposit.rejected data: $ref: "#/components/schemas/DepositEventData" responses: "200": description: Acknowledged by your endpoint. destination.created: post: tags: - Webhooks/Address book entry summary: Created operationId: onDestinationCreated security: [] requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: destination.created data: $ref: "#/components/schemas/DestinationEventData" responses: "200": description: Acknowledged by your endpoint. destination.activated: post: tags: - Webhooks/Address book entry summary: Activated operationId: onDestinationActivated security: [] requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: destination.activated data: $ref: "#/components/schemas/DestinationEventData" responses: "200": description: Acknowledged by your endpoint. destination.suspended: post: tags: - Webhooks/Address book entry summary: Suspended operationId: onDestinationSuspended security: [] requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: destination.suspended data: $ref: "#/components/schemas/DestinationEventData" responses: "200": description: Acknowledged by your endpoint. destination.closed: post: tags: - Webhooks/Address book entry summary: Closed operationId: onDestinationClosed security: [] requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: destination.closed data: $ref: "#/components/schemas/DestinationEventData" responses: "200": description: Acknowledged by your endpoint.