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

# Beneficiaries

> Recipients for payouts — crypto wallets and bank accounts.

## 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```bash theme={null}
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

```bash theme={null}
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.   |