Payouts

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.

POST

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"
}
'

import requests

url = "https://api.nxos.io/v1/transactions/crypto-payouts"

payload = {
    "accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "beneficiaryId": "bene_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "amount": "5000.000000",
    "asset": "USDC",
    "chainName": "ETHEREUM_MAINNET"
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountId: 'acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
    beneficiaryId: 'bene_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
    amount: '5000.000000',
    asset: 'USDC',
    chainName: 'ETHEREUM_MAINNET'
  })
};

fetch('https://api.nxos.io/v1/transactions/crypto-payouts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.nxos.io/v1/transactions/crypto-payouts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'accountId' => 'acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
    'beneficiaryId' => 'bene_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
    'amount' => '5000.000000',
    'asset' => 'USDC',
    'chainName' => 'ETHEREUM_MAINNET'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.nxos.io/v1/transactions/crypto-payouts"

	payload := strings.NewReader("{\n  \"accountId\": \"acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n  \"beneficiaryId\": \"bene_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n  \"amount\": \"5000.000000\",\n  \"asset\": \"USDC\",\n  \"chainName\": \"ETHEREUM_MAINNET\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.nxos.io/v1/transactions/crypto-payouts")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"accountId\": \"acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n  \"beneficiaryId\": \"bene_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n  \"amount\": \"5000.000000\",\n  \"asset\": \"USDC\",\n  \"chainName\": \"ETHEREUM_MAINNET\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nxos.io/v1/transactions/crypto-payouts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"accountId\": \"acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n  \"beneficiaryId\": \"bene_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n  \"amount\": \"5000.000000\",\n  \"asset\": \"USDC\",\n  \"chainName\": \"ETHEREUM_MAINNET\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "error": {
    "code": "invalid_request",
    "message": "The request body is malformed or missing required fields.",
    "requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "No Authorization header provided.",
    "requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Your organization is not enabled for this action.",
    "requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
  }
}

{
  "error": {
    "code": "quote_expired",
    "message": "The quote has expired.",
    "requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded: 1000 requests per minute. Retry in 23 seconds.",
    "requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected server error occurred.",
    "requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
  }
}

{
  "error": {
    "code": "chain_send_failed",
    "message": "On-chain transaction failed.",
    "requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
  }
}

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.

Show child attributes

description

string

Optional description.

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 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.

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.

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.

Show child attributes

Example:

{
  "fixed": "50.00",
  "bps": 0,
  "bpsAmount": "0.00",
  "total": "50.00",
  "asset": "USD"
}

createdAt

string

required

When the transaction was created.

txHash

string

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.

Initiate fiat payout

Get nxosnet settings

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"
}
'

import requests

url = "https://api.nxos.io/v1/transactions/crypto-payouts"

payload = {
    "accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "beneficiaryId": "bene_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "amount": "5000.000000",
    "asset": "USDC",
    "chainName": "ETHEREUM_MAINNET"
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountId: 'acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
    beneficiaryId: 'bene_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
    amount: '5000.000000',
    asset: 'USDC',
    chainName: 'ETHEREUM_MAINNET'
  })
};

fetch('https://api.nxos.io/v1/transactions/crypto-payouts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.nxos.io/v1/transactions/crypto-payouts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'accountId' => 'acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
    'beneficiaryId' => 'bene_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
    'amount' => '5000.000000',
    'asset' => 'USDC',
    'chainName' => 'ETHEREUM_MAINNET'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.nxos.io/v1/transactions/crypto-payouts"

	payload := strings.NewReader("{\n  \"accountId\": \"acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n  \"beneficiaryId\": \"bene_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n  \"amount\": \"5000.000000\",\n  \"asset\": \"USDC\",\n  \"chainName\": \"ETHEREUM_MAINNET\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.nxos.io/v1/transactions/crypto-payouts")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"accountId\": \"acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n  \"beneficiaryId\": \"bene_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n  \"amount\": \"5000.000000\",\n  \"asset\": \"USDC\",\n  \"chainName\": \"ETHEREUM_MAINNET\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nxos.io/v1/transactions/crypto-payouts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"accountId\": \"acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n  \"beneficiaryId\": \"bene_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n  \"amount\": \"5000.000000\",\n  \"asset\": \"USDC\",\n  \"chainName\": \"ETHEREUM_MAINNET\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "error": {
    "code": "invalid_request",
    "message": "The request body is malformed or missing required fields.",
    "requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "No Authorization header provided.",
    "requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Your organization is not enabled for this action.",
    "requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
  }
}

{
  "error": {
    "code": "quote_expired",
    "message": "The quote has expired.",
    "requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded: 1000 requests per minute. Retry in 23 seconds.",
    "requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected server error occurred.",
    "requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
  }
}

{
  "error": {
    "code": "chain_send_failed",
    "message": "On-chain transaction failed.",
    "requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
  }
}