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.
Overview
A beneficiary is a registered recipient for payouts. Before you can send money from an account, you create a beneficiary that describes where the money should go. There are two types:
| Type | Use case | Required fields |
|---|
CRYPTO | On-chain payout to a wallet address | chainName, address |
BANK | Fiat payout to a bank account | bankName, method, currency |
Unified response shape
All beneficiary endpoints return the same Beneficiary object. The type field tells you which detail object is populated:
{
"object": "beneficiary",
"beneficiaryId": "bene_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"type": "CRYPTO",
"nickname": "Treasury Wallet",
"status": "ACTIVE",
"entityType": null,
"email": null,
"phoneNumber": null,
"firstName": null,
"lastName": null,
"businessName": null,
"country": null,
"crypto": {
"chainName": "ethereum",
"chainDisplayName": "Ethereum",
"platform": "EVM",
"address": "0x1234...abcd"
},
"bank": null,
"createdAt": "2025-03-10T12:00:00.000Z"
}
crypto is null and bank contains the bank details:
{
"type": "BANK",
"crypto": null,
"bank": {
"bankName": "Deutsche Bank",
"swiftCode": "DEUTDEFF",
"iban": "DE89370400440532013000",
"bankCountry": "DE",
"method": "SEPA",
"currency": "EUR",
"intermediaryBankName": null,
"intermediarySwiftCode": null,
"intermediaryBankAddress": null
}
}
Creating beneficiaries
Crypto and bank beneficiaries have separate creation endpoints because their required fields differ.
Crypto beneficiary
curl -X POST https://api.sandbox.nxos.io/v1/beneficiaries/crypto \
-H "Authorization: Bearer nxos_sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"nickname": "Treasury Wallet",
"chainName": "ethereum",
"address": "0x1234567890abcdef1234567890abcdef12345678"
}'
Bank beneficiary
curl -X POST https://api.sandbox.nxos.io/v1/beneficiaries/bank \
-H "Authorization: Bearer nxos_sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"nickname": "EUR Treasury",
"bankName": "Deutsche Bank",
"method": "SEPA",
"currency": "EUR",
"swiftCode": "DEUTDEFF",
"iban": "DE89370400440532013000"
}'
entityType, firstName, lastName, businessName), contact details (email, phoneNumber), and address fields. These are stored with the beneficiary and can be updated later.
Shared identity fields
Every beneficiary can carry identity and compliance information:
| Field | Description |
|---|
entityType | INDIVIDUAL or BUSINESS |
firstName, lastName | Individual’s name |
businessName | Business name |
email, phoneNumber | Contact details |
country | Country code (ISO 3166-1 alpha-2) |
addressLine1, addressLine2, city, region, zipCode | Physical address |
taxId, taxIdType | Tax identification |
tags | Free-form string tags (max 20, each up to 100 chars) |
metadata | Arbitrary key-value pairs (max 50 keys, max 4 KB) |
null for brevity. Fetch a single beneficiary to see all populated fields.
Updating and archiving
Use PATCH /v1/beneficiaries/{beneficiaryId} to update shared fields or the nickname. The accountId must be included in the request body for ownership verification.
To remove a beneficiary, use DELETE /v1/beneficiaries/{beneficiaryId}. This archives (soft-deletes) the record — it remains in the system for audit purposes but no longer appears in list responses and cannot be used for new payouts.
Statuses
| Status | Description |
|---|
ACTIVE | Can be used for payouts. |
INACTIVE | Temporarily disabled. |
BLOCKED | Blocked by compliance. Cannot be used. |
ARCHIVED | Soft-deleted. Preserved for records. |
