Overview
Accounts
Beneficiaries
Create crypto beneficiary
Create a crypto beneficiary for an account.
curl --request POST \
--url https://api.nxos.io/v1/beneficiaries/crypto \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"nickname": "Treasury Wallet",
"chainName": "ethereum",
"address": "0x1234567890abcdef1234567890abcdef12345678"
}
'{
"object": "beneficiary",
"beneficiaryId": "bene_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"type": "CRYPTO",
"nickname": "Treasury Wallet",
"status": "ACTIVE",
"entityType": "INDIVIDUAL",
"email": "[email protected]",
"phoneNumber": null,
"firstName": "John",
"lastName": "Doe",
"businessName": null,
"country": "US",
"crypto": {
"chainName": "ethereum",
"chainDisplayName": "Ethereum",
"platform": "EVM",
"address": "0x1234567890abcdef1234567890abcdef12345678"
},
"bank": null,
"createdAt": "2025-03-10T12:00:00.000Z"
}Headers
Bearer token. Format: Bearer <api_key>
Body
Request body for creating a crypto beneficiary.
Account to register this beneficiary for.
Display name for the beneficiary.
Blockchain network name (e.g., ethereum, solana).
On-chain wallet address.
Optional label for the address.
Entity type.
INDIVIDUAL, BUSINESS Email address.
Phone number.
First name (individuals).
Last name (individuals).
Legal name.
Date of birth (YYYY-MM-DD).
Business name (businesses).
Registration / incorporation number.
Address line 1.
Address line 2.
City.
Region / state / province.
ZIP / postal code.
Country code (ISO 3166-1 alpha-2).
Tax ID.
Tax ID type (e.g., SSN, TIN).
Free-form tags (max 20 tags, each up to 100 characters).
Arbitrary metadata (max 50 keys, max 4 KB serialized).
Show child attributes
Show child attributes
Response
The request has succeeded.
A beneficiary (recipient) registered for payouts from an account.
All responses share this shape — the type field indicates which detail
object (crypto or bank) is populated; the other will be null.
Shared identity fields may be null in list and create responses.
Object type. Always beneficiary.
beneficiary Unique beneficiary identifier.
Account this beneficiary belongs to.
Beneficiary type.
CRYPTO, BANK Display name for the beneficiary.
Current status.
ACTIVE, INACTIVE, BLOCKED, ARCHIVED Entity type.
INDIVIDUAL, BUSINESS Email address.
Phone number.
First name (individuals).
Last name (individuals).
Business name (businesses).
Country code (ISO 3166-1 alpha-2).
Crypto-specific details. Present when type is CRYPTO, otherwise null.
Show child attributes
Show child attributes
Bank-specific details. Present when type is BANK, otherwise null.
Show child attributes
Show child attributes
When the beneficiary was created.
curl --request POST \
--url https://api.nxos.io/v1/beneficiaries/crypto \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"nickname": "Treasury Wallet",
"chainName": "ethereum",
"address": "0x1234567890abcdef1234567890abcdef12345678"
}
'{
"object": "beneficiary",
"beneficiaryId": "bene_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"type": "CRYPTO",
"nickname": "Treasury Wallet",
"status": "ACTIVE",
"entityType": "INDIVIDUAL",
"email": "[email protected]",
"phoneNumber": null,
"firstName": "John",
"lastName": "Doe",
"businessName": null,
"country": "US",
"crypto": {
"chainName": "ethereum",
"chainDisplayName": "Ethereum",
"platform": "EVM",
"address": "0x1234567890abcdef1234567890abcdef12345678"
},
"bank": null,
"createdAt": "2025-03-10T12:00:00.000Z"
}