Beneficiaries

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`

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:

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)

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

Status	Description
`ACTIVE`	Can be used for payouts.
`INACTIVE`	Temporarily disabled.
`BLOCKED`	Blocked by compliance. Cannot be used.
`ARCHIVED`	Soft-deleted. Preserved for records.

Getting started

Core concepts

Guides

Beneficiaries

Overview

Unified response shape

Creating beneficiaries

Crypto beneficiary

Bank beneficiary

Shared identity fields

Updating and archiving

Statuses

​Overview

​Unified response shape

​Creating beneficiaries

​Crypto beneficiary

​Bank beneficiary

​Shared identity fields

​Updating and archiving

​Statuses

Overview

Unified response shape

Creating beneficiaries

Crypto beneficiary

Bank beneficiary

Shared identity fields

Updating and archiving

Statuses