Skip to main content
POST
/
v1
/
transactions
/
crypto-payouts
cURL
curl --request POST \
  --url https://api.nxos.io/v1/transactions/crypto-payouts \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "beneficiaryId": "bene_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "amount": "5000.000000",
  "asset": "USDC",
  "chainName": "ETHEREUM_MAINNET"
}
'
{
  "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"
}

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.

Headers

​
Authorization
string
required

Bearer token. Format: Bearer <api_key>

​
Idempotency-Key
string

Unique key per logical operation. UUID v4 recommended. Max 255 characters.

Body

application/json

Request body for executing a crypto payout.

​
accountId
string
required

Source account to debit.

​
beneficiaryId
string
required

Crypto beneficiary to pay out to.

​
amount
string
required

Payout amount in major units (e.g. "100.00").

​
asset
string
required

Asset code (e.g. USDC, USDT).

​
chainName
string
required

Blockchain network name (e.g. ETHEREUM_MAINNET, SOLANA_MAINNET).

​
expectedFeeSchedule
object

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
string

Optional description.

​
tags
string[]

Free-form tags (max 20 tags, each up to 100 characters).

​
metadata
object

Arbitrary metadata (max 50 keys, max 4 KB serialized).

Response

The request has succeeded.

A completed crypto payout transaction.

​
object
enum<string>
required

Object type. Always transaction.

Available options:
transaction
​
transactionId
string
required

Unique transaction identifier.

​
type
enum<string>
required

Transaction type. Always CRYPTO_PAYOUT.

Available options:
CRYPTO_PAYOUT
​
status
enum<string>
required

Transaction status. LOCKED means the payout was broadcast on-chain (the response carries the tx hash) but confirmation is pending. 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.

Available options:
LOCKED
​
accountId
string
required

Source account.

​
beneficiaryId
string
required

Target beneficiary.

​
amount
string
required

Payout amount in major units.

​
asset
string
required

Asset code.

​
toAddress
string
required

Destination on-chain address.

​
txHash
string
required

On-chain transaction hash.

​
fee
object
required

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.

Example:
{
  "fixed": "50.00",
  "bps": 0,
  "bpsAmount": "0.00",
  "total": "50.00",
  "asset": "USD"
}
​
createdAt
string
required

When the transaction was created.