Skip to main content
In a nutshell
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.

​
Prerequisites

1

API Key

Get your API key from the Blockradar Dashboard. Navigate to Developers to generate one.
2

Wallet Created

You’ll need a walletId to associate beneficiaries with a wallet.

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

Save Once, Use Many Times

Register a destination address as a named beneficiary and reuse it across any number of withdrawals.

Reduce Human Error

Eliminate copy-paste mistakes by referencing addresses by ID rather than entering them manually each time.

Audit Trail

Every beneficiary has a creation timestamp and name, making it easy to track who you’re paying and when the relationship was established.

Whitelisting

Use beneficiaries as part of an address whitelisting strategy to restrict payouts to pre-approved destinations only.

​
Creating a Beneficiary

POST /v1/wallets/{walletId}/beneficiaries

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

ActionEndpoint
CreatePOST /v1/wallets/{walletId}/beneficiaries
Get AllGET /v1/wallets/{walletId}/beneficiaries
Get OneGET /v1/wallets/{walletId}/beneficiaries/{beneficiaryId}
UpdatePATCH /v1/wallets/{walletId}/beneficiaries/{beneficiaryId}
DeleteDELETE /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

EndpointDescription
Create BeneficiarySave a new destination address
Get All BeneficiariesList all saved beneficiaries
Get BeneficiaryFetch a single beneficiary by ID
Update BeneficiaryUpdate a beneficiary’s name or details
Delete BeneficiaryRemove a beneficiary