> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockradar.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Beneficiaries

> Save and manage trusted destination addresses for recurring payouts

<Note>
  In a nutshell<br />
  Beneficiaries are saved payout destinations — named wallet addresses you can reference by ID instead of passing raw addresses every time you send funds. Think of them as your contacts list for crypto payments.
</Note>

## Prerequisites

<Steps>
  <Step title="API Key">
    Get your API key from the [Blockradar Dashboard](https://dashboard.blockradar.co). Navigate to **Developers** to generate one.
  </Step>

  <Step title="Wallet Created">
    You'll need a `walletId` to associate beneficiaries with a wallet.
  </Step>
</Steps>

## How It Works

Every time you send a payout, you need a destination address. For one-off transfers, passing the address directly is fine. But for recurring payments: payroll, partner settlements, user withdrawals to known wallets, storing and managing addresses manually introduces risk: typos, copy-paste errors, and no audit trail.

Beneficiaries solve this by letting you register a destination address once, give it a name, and reference it by ID in all future payouts.

<CardGroup cols={2}>
  <Card title="Save Once, Use Many Times" icon="floppy-disk">
    Register a destination address as a named beneficiary and reuse it across any number of withdrawals.
  </Card>

  <Card title="Reduce Human Error" icon="shield-check">
    Eliminate copy-paste mistakes by referencing addresses by ID rather than entering them manually each time.
  </Card>

  <Card title="Audit Trail" icon="clock-rotate-left">
    Every beneficiary has a creation timestamp and name, making it easy to track who you're paying and when the relationship was established.
  </Card>

  <Card title="Whitelisting" icon="list-check">
    Use beneficiaries as part of an address whitelisting strategy to restrict payouts to pre-approved destinations only.
  </Card>
</CardGroup>

## Creating a Beneficiary

```bash theme={null}
POST /v1/wallets/{walletId}/beneficiaries
```

```javascript theme={null}
const beneficiary = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/beneficiaries`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      name: 'Alice Treasury Wallet',
      address: '0xabc123...',
      assetId: 'asset_usdc_base_mainnet'
    })
  }
).then(r => r.json());

console.log('Beneficiary ID:', beneficiary.data.id);
```

## Using a Beneficiary in a Payout

Once saved, reference the beneficiary ID when executing a withdrawal instead of passing the raw address.

```javascript theme={null}
const withdrawal = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/withdraw`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      beneficiaryId: beneficiary.data.id,
      amount: '500',
      assetId: 'asset_usdc_base_mainnet'
    })
  }
).then(r => r.json());
```

## Managing Beneficiaries

| Action  | Endpoint                                                      |
| ------- | ------------------------------------------------------------- |
| Create  | `POST /v1/wallets/{walletId}/beneficiaries`                   |
| Get All | `GET /v1/wallets/{walletId}/beneficiaries`                    |
| Get One | `GET /v1/wallets/{walletId}/beneficiaries/{beneficiaryId}`    |
| Update  | `PATCH /v1/wallets/{walletId}/beneficiaries/{beneficiaryId}`  |
| Delete  | `DELETE /v1/wallets/{walletId}/beneficiaries/{beneficiaryId}` |

## Best Practices

* **Name beneficiaries clearly** — use names that identify the person, team, or purpose (e.g. "Finance Team - Polygon", "User Payout - Alice").
* **Review regularly** — periodically audit your beneficiary list and remove destinations that are no longer active.
* **Combine with whitelisting** — if your compliance requirements restrict payouts to approved addresses only, use beneficiaries as your whitelist layer.

## API Reference

| Endpoint                                                         | Description                            |
| ---------------------------------------------------------------- | -------------------------------------- |
| [Create Beneficiary](/en/api-reference/beneficiaries/create)     | Save a new destination address         |
| [Get All Beneficiaries](/en/api-reference/beneficiaries/get-all) | List all saved beneficiaries           |
| [Get Beneficiary](/en/api-reference/beneficiaries/get-one)       | Fetch a single beneficiary by ID       |
| [Update Beneficiary](/en/api-reference/beneficiaries/update)     | Update a beneficiary's name or details |
| [Delete Beneficiary](/en/api-reference/beneficiaries/delete)     | Remove a beneficiary                   |