Skip to main content

​
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:
TypeUse caseRequired fields
CRYPTOOn-chain payout to a wallet addresschainName, address
BANKFiat payout to a bank accountbankName, method, currency
Beneficiaries are scoped to an account. The same recipient can be registered as a beneficiary on multiple accounts if needed.

​
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"
}
For a bank beneficiary, 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
  }
}
This design means you never need to handle different response shapes per type — the structure is always the same, only the populated fields differ.

​
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"
  }'
Both endpoints accept optional shared fields — identity information (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:
FieldDescription
entityTypeINDIVIDUAL or BUSINESS
firstName, lastNameIndividual’s name
businessNameBusiness name
email, phoneNumberContact details
countryCountry code (ISO 3166-1 alpha-2)
addressLine1, addressLine2, city, region, zipCodePhysical address
taxId, taxIdTypeTax identification
tagsFree-form string tags (max 20, each up to 100 chars)
metadataArbitrary key-value pairs (max 50 keys, max 4 KB)
These fields are nullable. In list responses, they may be 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

StatusDescription
ACTIVECan be used for payouts.
INACTIVETemporarily disabled.
BLOCKEDBlocked by compliance. Cannot be used.
ARCHIVEDSoft-deleted. Preserved for records.