List Beneficiaries

Retrieve a list of third-party beneficiaries configured for your account along with their verified crypto wallet addresses. Beneficiaries are external entities that can receive digital assets from your trades via third-party settlement.

Request

Body Parameters

Parameter	Type	Required	Default	Description
`accountGroupUuid`	String	No	-	Filter beneficiaries by specific account group UUID
`limit`	Integer	No	50	Maximum results to return (1-200)
`offset`	Integer	No	0	Offset for pagination

Example Request

{
  "accountGroupUuid": "2073252c-81ed-41be-bf4d-d51b8f2246b8",
  "limit": 50,
  "offset": 0
}

Get all beneficiaries (no filter):

{
  "limit": 100,
  "offset": 0
}

Response

Success Response (200 OK)

{
  "data": [
    {
      "companyName": "TECH COMPANY",
      "dateOfFormation": "2025-11-01",
      "countryOfFormation": "GB",
      "countryOfRegistration": "GB",
      "uuid": "5fff78ca-d87f-424f-90bf-96b1906a284b",
      "clientShortcode": "USDTTEST1",
      "clientAccountGroupName": "Default",
      "clientAccountGroupUuid": "2073252c-81ed-41be-bf4d-d51b8f2246b8",
      "type": "ENTITY",
      "kind": "BENEFICIARY",
      "phoneNumber": "(44)172799567",
      "website": "www.mytechcompany.com",
      "email": "[email protected]",
      "vasp": true,
      "enabled": false,
      "verified": false,
      "beneficiaryAddress": {
        "country": "GB",
        "city": "London",
        "street": "21 Tech Street",
        "postalCode": "N5 YAY",
        "stateProvince": "Greater London",
        "createdAt": "2026-01-23T17:49:56Z",
        "updatedAt": "2026-01-23T17:49:56Z"
      },
      "kycDetails": {
        "occupation": "Service Provider",
        "sourceOfFunds": "Trading",
        "methodOfVerification": "Electronic",
        "industryType": "Technology",
        "entityType": "NA",
        "natureOfActivity": "Fintech",
        "beneficiaryOwnership": false,
        "createdAt": "2026-01-23T17:49:55Z",
        "updatedAt": "2026-01-23T17:49:55Z"
      },
      "identifications": [
        {
          "type": "BUSINESS_REGISTRATION",
          "number": "EA990098771",
          "typeOther": "",
          "createdAt": "2026-01-23T17:49:52Z",
          "updatedAt": "2026-01-23T17:49:52Z"
        },
        {
          "type": "LEI",
          "number": "12345678",
          "typeOther": "",
          "createdAt": "2026-01-23T17:49:52Z",
          "updatedAt": "2026-01-23T17:49:52Z"
        },
        {
          "type": "TAX_ID",
          "number": "09898766",
          "typeOther": "",
          "createdAt": "2026-01-23T17:49:54Z",
          "updatedAt": "2026-01-23T17:49:54Z"
        }
      ],
      "bankAccounts": [
        {
          "bankName": "STANDARD CHARTERED BANK GB",
          "bankBranchName": "STANDARD CHARTERED BASINGHALL",
          "accountNumber": "",
          "accountAlias": "Tech Company (UK) GBP",
          "accountName": "TECH COMPANY Account Main",
          "currency": "GBP",
          "iban": "GB07SCB60924280026876",
          "swiftBic": "SCBGLXXX",
          "country": "GB",
          "city": "London",
          "street": "1 Basinghall Avenue",
          "postalCode": "EC1 2LA",
          "memo": "TEST MEMO",
          "enabled": true,
          "verified": true,
          "createdAt": "2026-01-23T17:49:50Z",
          "updatedAt": "2026-01-23T17:49:50Z"
        }
      ],
      "wallets": [
        {
          "uuid": "d1d6a755-e97e-4278-b246-2ea18a54ab60",
          "blockchain": "Polygon",
          "asset": "USDC",
          "walletAddress": "0x9882761678912",
          "alias": "TECH_USDC_POL",
          "type": "SELF_HOSTED",
          "memo": "Backup",
          "vasp": "",
          "executionProvider": "",
          "default": false,
          "enabled": true,
          "whitelisted": true,
          "createdAt": "2026-01-23T17:49:48Z",
          "updatedAt": "2026-01-23T17:50:32Z"
        },
        {
          "uuid": "88ce5ff8-3199-4b8c-85e2-44d9da960abf",
          "blockchain": "Ethereum",
          "asset": "USDC",
          "walletAddress": "0x908728727777661",
          "alias": "TECH_USDC_MAIN-ETH",
          "type": "SELF_HOSTED",
          "memo": "Payments",
          "vasp": "",
          "executionProvider": "",
          "default": false,
          "enabled": true,
          "whitelisted": true,
          "createdAt": "2026-01-23T17:49:49Z",
          "updatedAt": "2026-01-23T17:50:31Z"
        },
        {
          "uuid": "0e333c18-cbf1-4c26-8b9e-cdecce5e04bc",
          "blockchain": "TRON",
          "asset": "USDT",
          "walletAddress": "0x98887182891",
          "alias": "TECH_USDT_TRON",
          "type": "CUSTODY",
          "memo": "Payment2",
          "vasp": "COINBASE",
          "executionProvider": "BINANCE",
          "default": false,
          "enabled": true,
          "whitelisted": true,
          "createdAt": "2026-01-23T17:49:47Z",
          "updatedAt": "2026-01-23T17:50:30Z"
        }
      ],
      "createdAt": "2026-01-23T17:41:41Z",
      "updatedAt": "2026-01-23T17:41:41Z"
    }
  ]
}

Response Fields

Root Object

Field	Type	Description
`data`	Array	Array of beneficiary objects

Beneficiary Object

Field	Type	Description
`uuid`	String	Unique identifier for the beneficiary
`companyName`	String	Beneficiary company/entity name
`type`	String	`ENTITY` or `INDIVIDUAL`
`kind`	String	Always `BENEFICIARY`
`enabled`	Boolean	Whether beneficiary is enabled for trading
`verified`	Boolean	Whether beneficiary has completed verification
`vasp`	Boolean	Virtual Asset Service Provider flag
`clientShortcode`	String	Your account identifier
`clientAccountGroupName`	String	Account group (sub-account) name
`clientAccountGroupUuid`	String	Account group UUID
`email`	String	Beneficiary contact email
`phoneNumber`	String	Beneficiary contact phone
`website`	String	Beneficiary website URL
`dateOfFormation`	String	Company formation date (YYYY-MM-DD)
`countryOfFormation`	String	ISO 3166-1 alpha-2 country code
`countryOfRegistration`	String	ISO 3166-1 alpha-2 country code
`beneficiaryAddress`	Object	Beneficiary address details
`kycDetails`	Object	KYC and compliance information
`identifications`	Array	Business registration and tax identifications
`bankAccounts`	Array	Bank accounts configured for fiat settlement
`wallets`	Array	Crypto wallet addresses for digital asset settlement
`createdAt`	String	Beneficiary creation timestamp (ISO 8601)
`updatedAt`	String	Last update timestamp (ISO 8601)

Beneficiary Address

Field	Type	Description
`street`	String	Street address
`city`	String	City
`stateProvince`	String	State or province
`postalCode`	String	Postal/ZIP code
`country`	String	ISO 3166-1 alpha-2 country code
`createdAt`	String	Creation timestamp (ISO 8601)
`updatedAt`	String	Last update timestamp (ISO 8601)

KYC Details

Field	Type	Description
`occupation`	String	Occupation or business activity
`sourceOfFunds`	String	Source of funds description
`methodOfVerification`	String	Verification method used
`industryType`	String	Industry classification
`entityType`	String	Legal entity type
`natureOfActivity`	String	Nature of business activity
`beneficiaryOwnership`	Boolean	Beneficiary ownership flag
`createdAt`	String	Creation timestamp (ISO 8601)
`updatedAt`	String	Last update timestamp (ISO 8601)

Identification Object

Field	Type	Description
`type`	String	`BUSINESS_REGISTRATION`, `LEI`, `PASSPORT`, `NATIONAL_ID`, `DRIVERS_LICENSE`, `SSN`, `TAX_ID`, `EIN`, `VAT_NUMBER`, `OTHER`
`number`	String	Identification number
`typeOther`	String	Custom type (if type is "OTHER")
`createdAt`	String	Creation timestamp (ISO 8601)
`updatedAt`	String	Last update timestamp (ISO 8601)

Bank Account Object

Field	Type	Description
`bankName`	String	Bank institution name
`bankBranchName`	String	Branch name
`accountNumber`	String	Bank account number
`accountAlias`	String	Friendly alias for the account
`accountName`	String	Account holder name
`currency`	String	Account currency (ISO 4217)
`iban`	String	International Bank Account Number
`swiftBic`	String	SWIFT/BIC code
`country`	String	ISO 3166-1 alpha-2 country code
`city`	String	Bank branch city
`street`	String	Bank branch street address
`postalCode`	String	Bank branch postal code
`memo`	String	Additional notes
`enabled`	Boolean	Whether account is enabled
`verified`	Boolean	Whether account is verified
`createdAt`	String	Creation timestamp (ISO 8601)
`updatedAt`	String	Last update timestamp (ISO 8601)

Wallet Object

Field	Type	Description
`uuid`	String	Unique identifier
`blockchain`	String	Blockchain network (e.g., `Ethereum`, `Polygon`, `TRON`)
`asset`	String	Digital asset symbol (e.g., `USDC`, `USDT`, `BTC`)
`walletAddress`	String	Blockchain wallet address
`alias`	String	Friendly alias for the wallet
`type`	String	`SELF_HOSTED` or `CUSTODY`
`memo`	String	Additional notes
`vasp`	String	Virtual Asset Service Provider name (if custody)
`executionProvider`	String	Execution provider name (if applicable)
`default`	Boolean	Whether this is the default wallet for the asset
`enabled`	Boolean	Whether wallet is enabled for trading
`whitelisted`	Boolean	Whether wallet address is whitelisted
`createdAt`	String	Creation timestamp (ISO 8601)
`updatedAt`	String	Last update timestamp (ISO 8601)

Beneficiary Status

A beneficiary must be both enabled AND verified to be used for third-party settlement:

Field	Value	Meaning
`enabled`	`true`	Beneficiary is active
`enabled`	`false`	Beneficiary is inactive
`verified`	`true`	Passed KYC/compliance checks
`verified`	`false`	Pending verification

Trading Requirement: Only beneficiaries with enabled: true AND verified: true can be used for third-party settlement orders.

Wallet Status

For crypto settlement, wallets must be properly configured:

Field	Value	Required for Trading?
`enabled`	`true`	✅ Yes
`whitelisted`	`true`	✅ Yes
`enabled`	`false`	❌ No - wallet disabled
`whitelisted`	`false`	❌ No - wallet not whitelisted

Crypto Settlement: To use a wallet for third-party settlement, the wallet must have enabled: true AND whitelisted: true, and match the asset being traded.

Pagination

Use max (1-200) and offset parameters to paginate through results.

Example: Get All Beneficiaries

def get_all_beneficiaries():
    all_beneficiaries = []
    offset = 0
    max_per_page = 200
    
    while True:
        response = make_api_request('POST', 'api/3/beneficiaries', {
            'max': max_per_page,
            'offset': offset
        })
        
        beneficiaries = response['data']
        all_beneficiaries.extend(beneficiaries)
        
        if len(beneficiaries) < max_per_page:
            break
        
        offset += max_per_page
    
    return all_beneficiaries

Code Examples

Python

import json
import hmac
import hashlib
import time
import requests

# Configuration
api_key = "your_api_key"
api_secret = "your_api_secret"
base_url = "https://trade-uk.sandbox.zodiamarkets.com"

# Request body
body = {
    "accountGroupUuid": "2073252c-81ed-41be-bf4d-d51b8f2246b8",
    "max": 50,
    "offset": 0
}
body_json = json.dumps(body)

# Generate signature
path = "api/3/beneficiaries"
tonce = str(int(time.time() * 1000000))
message = f"{path}\0{body_json}"
signature = hmac.new(
    api_secret.encode(),
    message.encode(),
    hashlib.sha512
).hexdigest()

# Make request
headers = {
    "Rest-Key": api_key,
    "Rest-Sign": signature,
    "Content-Type": "application/json"
}

response = requests.post(
    f"{base_url}/{path}",
    headers=headers,
    data=body_json
)

# Process response
if response.status_code == 200:
    data = response.json()
    for beneficiary in data['data']:
        print(f"\n{beneficiary['companyName']}: {beneficiary['uuid']}")
        print(f"  Enabled: {beneficiary['enabled']}")
        print(f"  Verified: {beneficiary['verified']}")
        print(f"  Wallets: {len(beneficiary['wallets'])}")
        print(f"  Bank Accounts: {len(beneficiary['bankAccounts'])}")
else:
    print(f"Error: {response.status_code}")
    print(response.text)

JavaScript (Node.js)

const crypto = require('crypto');
const axios = require('axios');

// Configuration
const apiKey = 'your_api_key';
const apiSecret = 'your_api_secret';
const baseUrl = 'https://trade-uk.sandbox.zodiamarkets.com';

// Request body
const body = {
  accountGroupUuid: '2073252c-81ed-41be-bf4d-d51b8f2246b8',
  max: 50,
  offset: 0
};
const bodyJson = JSON.stringify(body);

// Generate signature
const path = 'api/3/beneficiaries';
const tonce = Date.now() * 1000;
const message = `${path}\0${bodyJson}`;
const signature = crypto
  .createHmac('sha512', apiSecret)
  .update(message)
  .digest('hex');

// Make request
const headers = {
  'Rest-Key': apiKey,
  'Rest-Sign': signature,
  'Content-Type': 'application/json'
};

axios.post(`${baseUrl}/${path}`, body, { headers })
  .then(response => {
    response.data.data.forEach(beneficiary => {
      console.log(`\n${beneficiary.companyName}: ${beneficiary.uuid}`);
      console.log(`  Enabled: ${beneficiary.enabled}`);
      console.log(`  Verified: ${beneficiary.verified}`);
      console.log(`  Wallets: ${beneficiary.wallets.length}`);
      console.log(`  Bank Accounts: ${beneficiary.bankAccounts.length}`);
    });
  })
  .catch(error => {
    console.error('Error:', error.response?.status);
    console.error(error.response?.data);
  });

cURL

curl -X POST https://trade-uk.sandbox.zodiamarkets.com/api/3/beneficiaries \
  -H "Rest-Key: your_api_key" \
  -H "Rest-Sign: your_hmac_signature" \
  -H "Content-Type: application/json" \
  -d '{
    "accountGroupUuid": "2073252c-81ed-41be-bf4d-d51b8f2246b8",
    "max": 50,
    "offset": 0
  }'

Common Use Cases

Find Verified Beneficiaries

response = make_api_request('POST', 'api/3/beneficiaries', {})

verified = [
    b for b in response['data'] 
    if b['verified'] and b['enabled']
]

for beneficiary in verified:
    print(f"{beneficiary['companyName']}: {beneficiary['uuid']}")

Get Beneficiary by Name

def find_beneficiary_by_name(name):
    response = make_api_request('POST', 'api/3/beneficiaries', {})
    
    for beneficiary in response['data']:
        if beneficiary['companyName'].lower() == name.lower():
            return beneficiary
    
    return None

beneficiary = find_beneficiary_by_name('TECH COMPANY')
if beneficiary:
    print(f"UUID: {beneficiary['uuid']}")
    print(f"Status: {'Active' if beneficiary['enabled'] else 'Inactive'}")

Find Wallets for Specific Asset

def find_wallets_for_asset(beneficiary_id, asset):
    response = make_api_request('POST', 'api/3/beneficiaries', {})
    
    for beneficiary in response['data']:
        if beneficiary['uuid'] == beneficiary_id:
            wallets = [
                w for w in beneficiary['wallets']
                if w['asset'] == asset and w['enabled'] and w['whitelisted']
            ]
            return wallets
    
    return []

# Find USDC wallets for a beneficiary
wallets = find_wallets_for_asset(
    '5fff78ca-d87f-424f-90bf-96b1906a284b',
    'USDC'
)

for wallet in wallets:
    print(f"{wallet['alias']}: {wallet['blockchain']}")
    print(f"  Address: {wallet['walletAddress']}")

Check Beneficiary Trading Readiness

def is_beneficiary_ready_for_trading(beneficiary):
    """Check if beneficiary is ready for third-party settlement"""
    if not beneficiary['enabled']:
        return False, "Beneficiary is not enabled"
    
    if not beneficiary['verified']:
        return False, "Beneficiary is not verified"
    
    # Check if has at least one valid wallet or bank account
    has_wallet = any(
        w['enabled'] and w['whitelisted'] 
        for w in beneficiary['wallets']
    )
    has_bank = any(
        ba['enabled'] and ba['verified']
        for ba in beneficiary['bankAccounts']
    )
    
    if not (has_wallet or has_bank):
        return False, "No valid wallets or bank accounts configured"
    
    return True, "Ready for trading"

# Check beneficiary status
response = make_api_request('POST', 'api/3/beneficiaries', {})
for beneficiary in response['data']:
    ready, message = is_beneficiary_ready_for_trading(beneficiary)
    status = "✅" if ready else "❌"
    print(f"{status} {beneficiary['companyName']}: {message}")

Filter by Account Group

response = make_api_request('POST', 'api/3/beneficiaries', {
    'accountGroupUuid': '2073252c-81ed-41be-bf4d-d51b8f2246b8'
})

print(f"Found {len(response['data'])} beneficiaries in this account group")