> ## Documentation Index > Fetch the complete documentation index at: https://docs.nxos.io/llms.txt > Use this file to discover all available pages before exploring further. # Execute crypto payout > Execute a crypto payout from an account to a crypto beneficiary. Funds are debited immediately and the payout is processed on-chain. The response `status` is `LOCKED` (pending); `txHash` is present once the transaction is broadcast. Chain confirmation is asynchronous: clients should poll `GET /v1/transactions/{id}` to observe the transition to `COMPLETED` (confirmed on chain) or `DECLINED` (rejected on chain). Requires the organization to be enabled for crypto payouts. ## OpenAPI ````yaml POST /v1/transactions/crypto-payouts openapi: 3.0.0 info: title: nxos API version: 1.0.0 contact: name: nxos url: https://nxos.io description: |- The nxos platform API provides programmatic access to accounts, balances, quotes, and trades. All endpoints require API key authentication. servers: - url: https://api.nxos.io description: Production variables: {} - url: https://api.sandbox.nxos.io description: Sandbox variables: {} security: [] tags: - name: Accounts - name: Quotes - name: Beneficiaries - name: Fiat Payouts - name: Crypto Payouts - name: Nxosnet - name: Fees - name: Funding Methods - name: Transactions - name: Organizations - name: Authorizations - name: Webhooks description: >- Register an HTTPS endpoint to receive events (organization verification and transaction status changes) instead of polling. Deliveries are signed; verify the `svix-signature` header before acting on an event. See the [Webhooks guide](https://docs.nxos.io/core-concepts/webhooks) for the delivery format, signature verification, retries, and broker behavior. Payload shapes are documented in the `…Event` models below. paths: /v1/transactions/crypto-payouts: post: tags: - Crypto Payouts description: >- Execute a crypto payout from an account to a crypto beneficiary. Funds are debited immediately and the payout is processed on-chain. The response `status` is `LOCKED` (pending); `txHash` is present once the transaction is broadcast. Chain confirmation is asynchronous: clients should poll `GET /v1/transactions/{id}` to observe the transition to `COMPLETED` (confirmed on chain) or `DECLINED` (rejected on chain). Requires the organization to be enabled for crypto payouts. operationId: CryptoPayouts_execute parameters: - $ref: '#/components/parameters/ApiKeyAuth' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExecuteCryptoPayoutRequest' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CryptoPayoutTransaction' '400': description: The server could not understand the request due to invalid syntax. content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Access is unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: Access is forbidden. content: application/json: schema: $ref: '#/components/schemas/Error403' '404': description: The server cannot find the requested resource. content: application/json: schema: $ref: '#/components/schemas/Error404' '409': description: The request conflicts with the current state of the server. content: application/json: schema: $ref: '#/components/schemas/Error409' '429': description: Client error content: application/json: schema: $ref: '#/components/schemas/Error429' '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/Error500' '502': description: Server error content: application/json: schema: $ref: '#/components/schemas/Error502' components: parameters: ApiKeyAuth: name: Authorization in: header required: true description: 'Bearer token. Format: `Bearer `' schema: type: string IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Unique key per logical operation. UUID v4 recommended. Max 255 characters. schema: type: string schemas: ExecuteCryptoPayoutRequest: type: object required: - accountId - beneficiaryId - amount - asset - chainName properties: accountId: type: string description: Source account to debit. beneficiaryId: type: string description: Crypto beneficiary to pay out to. amount: allOf: - $ref: '#/components/schemas/amount' description: Payout amount in major units (e.g. `"100.00"`). asset: type: string description: Asset code (e.g. `USDC`, `USDT`). chainName: type: string description: Blockchain network name (e.g. `ETHEREUM_MAINNET`, `SOLANA_MAINNET`). expectedFeeSchedule: allOf: - $ref: '#/components/schemas/ExpectedFeeSchedule' description: >- Optional pin against fee drift. Echo the schedule returned by `GET /v1/fees/crypto-payout` to guarantee we charge exactly what you quoted. If the schedule has changed since the quote, we return `409 fee_schedule_drifted` and the client should refresh + retry. Omit to accept whatever the current schedule says. description: type: string description: Optional description. tags: type: array items: type: string description: Free-form tags (max 20 tags, each up to 100 characters). metadata: type: object additionalProperties: {} description: Arbitrary metadata (max 50 keys, max 4 KB serialized). description: Request body for executing a crypto payout. example: accountId: acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 beneficiaryId: bene_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 amount: '5000.000000' asset: USDC chainName: ETHEREUM_MAINNET CryptoPayoutTransaction: type: object required: - object - transactionId - type - status - accountId - beneficiaryId - amount - asset - toAddress - fee - createdAt properties: object: type: string enum: - transaction description: Object type. Always `transaction`. transactionId: type: string description: Unique transaction identifier. type: type: string enum: - CRYPTO_PAYOUT description: Transaction type. Always `CRYPTO_PAYOUT`. status: type: string enum: - LOCKED description: >- Transaction status. `LOCKED` means the payout is pending: it has been accepted and is being processed on-chain. `txHash` is present once the transaction is broadcast. Poll `GET /v1/transactions/{id}` to observe the final state — typically `COMPLETED` within seconds to minutes depending on chain, or `DECLINED` if the on-chain tx was rejected. accountId: type: string description: Source account. beneficiaryId: type: string description: Target beneficiary. amount: allOf: - $ref: '#/components/schemas/amount' description: Payout amount in major units. asset: type: string description: Asset code. toAddress: type: string description: Destination on-chain address. txHash: type: string description: >- On-chain transaction hash. Present once the transaction is broadcast; may be absent while the payout is still pending (status `LOCKED`). Poll `GET /v1/transactions/{id}` to pick it up. fee: allOf: - $ref: '#/components/schemas/TransactionFee' description: >- Fee breakdown for this transaction. Always populated; every component is zero when no fee applies. `amount` is what the beneficiary receives on-chain; the user's account is debited `amount + fee.total`. createdAt: allOf: - $ref: '#/components/schemas/dateTimeString' description: When the transaction was created. description: A completed crypto payout transaction. example: object: transaction transactionId: txn_c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6 type: CRYPTO_PAYOUT status: LOCKED accountId: acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 beneficiaryId: bene_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 amount: '5000.000000' asset: USDC toAddress: '0x1234567890abcdef1234567890abcdef12345678' txHash: '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890' fee: fixed: '1.000000' bps: 0 bpsAmount: '0.000000' total: '1.000000' asset: USDC createdAt: '2025-03-15T14:32:00.000Z' Error400: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. example: error: code: invalid_request message: The request body is malformed or missing required fields. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 Error401: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. example: error: code: missing_api_key message: No Authorization header provided. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 Error403: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. example: error: code: forbidden message: Your organization is not enabled for this action. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 Error404: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. example: error: code: not_found message: The requested resource was not found. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 Error409: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. example: error: code: quote_expired message: The quote has expired. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 Error429: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. example: error: code: rate_limited message: 'Rate limit exceeded: 1000 requests per minute. Retry in 23 seconds.' requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 Error500: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. example: error: code: internal_error message: An unexpected server error occurred. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 Error502: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. example: error: code: chain_send_failed message: On-chain transaction failed. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 amount: type: string description: >- Monetary amount as a decimal string in major units (e.g., `"10.50"` for ten dollars and fifty cents). Amounts are always returned at the asset's native precision — for example, USDT amounts have 6 decimal places (`"10.500000"`). Clients should parse amounts as arbitrary-precision decimals, never as floating-point numbers, to avoid rounding errors. Internally, the platform stores all amounts as integer subunits and converts at the API boundary. ExpectedFeeSchedule: type: object required: - fixed - bps - asset properties: fixed: allOf: - $ref: '#/components/schemas/amount' description: >- Expected fixed component in major units. Must match the quoted value byte-for-byte. bps: type: integer format: int32 description: Expected rate in basis points. Must match the quoted value. asset: type: string description: Asset the fee is denominated in. Must match the withdrawal's asset. description: >- A fee schedule echoed back from `GET /v1/fees/*` to pin what the client was quoted. If provided on a payout submit, the server re-looks-up the current schedule and refuses with `409 fee_schedule_drifted` if any component changed. Optional — omit to accept whatever fee the current config says. Fields match the `FeeSchedule` response model: `fixed` + `bps` + `asset`. The `asset` must match the withdrawal's asset. TransactionFee: type: object required: - fixed - bps - bpsAmount - total - asset properties: fixed: allOf: - $ref: '#/components/schemas/amount' description: >- Flat component charged regardless of the principal. Zero when the schedule has no fixed component. bps: type: integer format: int32 description: >- Rate applied to the principal, in basis points (1 bp = 0.01%, so 50 bps = 0.5%). Zero when the schedule has no rate component. bpsAmount: allOf: - $ref: '#/components/schemas/amount' description: >- Rate-based component, derived from `bps` and the principal and rounded at charge time. Zero when `bps` is zero. total: allOf: - $ref: '#/components/schemas/amount' description: >- Total fee charged: `fixed + bpsAmount`. The single number surfaced to customers as "Fee". asset: type: string description: >- Asset code the fee is denominated in. Always matches the transaction's principal asset — fees are never FX-converted. description: >- Fee breakdown for a transaction. Always present on every transaction response; when no fee applies, every amount is zero and `bps` is zero. Construction: total = fixed + bpsAmount (the number the customer is charged on top of the principal) bpsAmount = round(principal × bps / 10_000) (the rate-based component, rounded at charge time) Fixed and rate components are independent — any combination of zero and non-zero is valid: - Flat fee only (e.g. SWIFT $50): fixed > 0, bps = 0, bpsAmount = 0 - Rate fee only (e.g. 50 bps): fixed = 0, bps > 0, bpsAmount > 0 - Combined: fixed > 0, bps > 0, bpsAmount > 0 - No fee: everything zero All `amount` fields are denominated in `asset` — the same asset as the transaction's principal. The `bps` value is the rate that was applied at charge time, preserved so clients can re-derive "what percentage was this?" without recomputing from fee ÷ principal. example: fixed: '50.00' bps: 0 bpsAmount: '0.00' total: '50.00' asset: USD dateTimeString: type: string description: ISO 8601 timestamp string. ErrorBody: type: object required: - code - message - requestId properties: code: allOf: - $ref: '#/components/schemas/ErrorCode' description: Machine-readable error code. message: type: string description: Human-readable error message. requestId: type: string description: Unique identifier for this request, useful for debugging. ErrorCode: type: string enum: - missing_api_key - authentication_failed - invalid_api_key - forbidden - not_found - organization_not_found - account_not_found - quote_not_found - beneficiary_not_found - transaction_not_found - funding_method_not_found - authorization_not_found - nxosnet_handle_not_found - quote_expired - quote_already_used - beneficiary_already_archived - beneficiary_not_archived - beneficiary_blocked - nxosnet_not_enabled - nxosnet_handle_taken - chain_send_failed - idempotency_key_in_use - idempotency_request_in_flight - invalid_request - insufficient_funds - validation_error - share_token_invalid - verification_import_unsupported - rate_limited - webhooks_unavailable - internal_error description: All possible error codes returned by the API. ````