Skip to content
Zodia MarketsZodia Markets API

Get Beneficiary List

POST https://trade-uk.sandbox.zodiamarkets.com/api/3/beneficiaries

List Beneficiaries

Section titled “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.

Beneficiary Status

Section titled “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

Section titled “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

Section titled “Pagination”

Use limit (0-50) and offset parameters to paginate through results. limit is capped at 50 — a larger value is rejected.

Example: Get All Beneficiaries

Section titled “Example: Get All Beneficiaries”
def get_all_beneficiaries():
    all_beneficiaries = []
    offset = 0
    page_size = 50


    while True:
        response = make_api_request('POST', 'api/3/beneficiaries', {
            'limit': page_size,
            'offset': offset
        })


        beneficiaries = response['data']
        all_beneficiaries.extend(beneficiaries)


        if len(beneficiaries) < page_size:
            break


        offset += page_size


    return all_beneficiaries

Code Examples

Section titled “Code Examples”

Python

Section titled “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 — every signed request must carry a nonce or tonce
tonce = str(int(time.time() * 1000000))
body = {
    "tonce": tonce,
    "accountGroupUuid": "2073252c-81ed-41be-bf4d-d51b8f2246b8",
    "limit": 50,
    "offset": 0
}
body_json = json.dumps(body)


# Generate signature
path = "api/3/beneficiaries"
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)

Section titled “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 — every signed request must carry a nonce or tonce
const tonce = Date.now() * 1000;
const body = {
  tonce,
  accountGroupUuid: '2073252c-81ed-41be-bf4d-d51b8f2246b8',
  limit: 50,
  offset: 0
};
const bodyJson = JSON.stringify(body);


// Generate signature
const path = 'api/3/beneficiaries';
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

Section titled “cURL”
Terminal window
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 '{
    "tonce": 1770888183656000,
    "accountGroupUuid": "2073252c-81ed-41be-bf4d-d51b8f2246b8",
    "limit": 50,
    "offset": 0
  }'

Common Use Cases

Section titled “Common Use Cases”

Find Verified Beneficiaries

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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")

Domain: Payment participants

Request

Section titled “Request”
POST https://trade-uk.sandbox.zodiamarkets.com/api/3/beneficiaries

Headers

Section titled “Headers”
Header Required Description
Rest-Key API key for authentication
Rest-Sign Calculated API Signature

Body

Section titled “Body”
Field Type Required Description
tonce integer (int64) yes The current Unix time in microseconds.
nonce integer (int64) Alternative to tonce. Every request must carry either nonce or tonce, and the value must parse as a whole number; a request with neither is rejected with INVALID_NONCE_OR_TONCE.
accountGroupUuid string Filter beneficiaries by specific account group UUID
limit integer (int32) Maximum results to return. Validation caps this at 50 — a larger value is rejected with INVALID_PARAMETERS. When omitted, the participants service applies its own default.
offset integer (int32) Offset for pagination
userUuid string Master API keys only: UUID of the user to act on behalf of. Ignored unless the calling key belongs to the owner of a master-API-enabled site.

Responses

Section titled “Responses”

200

Section titled “200”

Beneficiary list — type: ENTITY

Section titled “Beneficiary list — type: ENTITY”
Field Type Required Description
data array of object Array of beneficiary objects
data[].companyName string Beneficiary company/entity name
data[].companyName2 string Second line of the registered name, where the name needs one
data[].dateOfFormation string (date) Company formation date (YYYY-MM-DD)
data[].countryOfFormation string ISO 3166-1 alpha-2 country code
data[].countryOfRegistration string ISO 3166-1 alpha-2 country code
data[].uuid string (uuid) Unique identifier for the Beneficiary
data[].type string (enum) Whether this participant is a legal entity or a natural person — One of: ENTITY, INDIVIDUAL
data[].kind string (enum) Always BENEFICIARY — One of: BENEFICIARY
data[].enabled boolean Whether Beneficiary is enabled for trading
data[].verified boolean Whether Beneficiary has completed verification
data[].vasp boolean Virtual Asset Service Provider flag
data[].ownershipPercentage string Percentage of the participant owned, for participants held as an ownership interest. Absent when not recorded.
data[].clientShortcode string Your account identifier
data[].clientAccountGroupName string Account group (sub-account) name
data[].clientAccountGroupUuid string Account group UUID
data[].email string Beneficiary contact email
data[].phoneNumber string Beneficiary contact phone
data[].website string Beneficiary website URL
data[].address object Beneficiary address details
data[].address.street string Street address
data[].address.city string City
data[].address.stateProvince string State or province
data[].address.postalCode string Postal/ZIP code
data[].address.country string ISO 3166-1 alpha-2 country code
data[].address.createdAt string (date-time) Creation timestamp (ISO 8601)
data[].address.updatedAt string (date-time) Last update timestamp (ISO 8601)
data[].kycDetails object KYC and compliance information
data[].kycDetails.occupation string Occupation or business activity
data[].kycDetails.sourceOfFunds string Source of funds description
data[].kycDetails.methodOfVerification string Verification method used
data[].kycDetails.industryType string Industry classification
data[].kycDetails.entityType string Legal entity type
data[].kycDetails.natureOfActivity string Nature of business activity
data[].kycDetails.beneficiaryOwnership boolean Beneficiary ownership flag
data[].kycDetails.createdAt string (date-time) Creation timestamp (ISO 8601)
data[].kycDetails.updatedAt string (date-time) Last update timestamp (ISO 8601)
data[].identifications array of object Business registration and tax identifications
data[].identifications[].type string (enum) Identification type — One of: PASSPORT, NATIONAL_ID, DRIVERS_LICENSE, SSN, TAX_ID, LEI, EIN, VAT_NUMBER, BUSINESS_REGISTRATION, OTHER
data[].identifications[].number string Identification number
data[].identifications[].typeOther string Custom type (if type is “OTHER”)
data[].identifications[].createdAt string (date-time) Creation timestamp (ISO 8601)
data[].identifications[].updatedAt string (date-time) Last update timestamp (ISO 8601)
data[].associatedPersons array of object Associated Person details (e.g. authorized signatory, beneficial owners). enabled, verified and vasp are always null on these entries.
data[].associatedPersons[].uuid string (uuid) Unique identifier for the person
data[].associatedPersons[].firstname string Given name
data[].associatedPersons[].lastname string Family name
data[].associatedPersons[].dateOfBirth string (date) Date of birth (YYYY-MM-DD)
data[].associatedPersons[].countryOfOrigin string ISO 3166-1 alpha-2 country code of origin
data[].associatedPersons[].nationality string ISO 3166-1 alpha-2 country code of nationality
data[].associatedPersons[].type string (enum) Always INDIVIDUAL for an associated person — One of: INDIVIDUAL
data[].associatedPersons[].kind string (enum) Role this person holds in relation to the participant — One of: AUTHORIZED_SIGNATORY, BENEFICIARY_OWNER, INTERMEDIARY_BENEFICIARY_OWNER
data[].associatedPersons[].clientShortcode string Your account identifier
data[].associatedPersons[].phoneNumber string Contact phone
data[].associatedPersons[].website string Website URL
data[].associatedPersons[].email string Contact email
data[].associatedPersons[].createdAt string (date-time) Creation timestamp (ISO 8601)
data[].associatedPersons[].updatedAt string (date-time) Last update timestamp (ISO 8601)
data[].bankAccounts array of object Bank accounts configured for fiat settlement
data[].bankAccounts[].uuid string (uuid) Unique identifier for the bank account
data[].bankAccounts[].bankName string Bank institution name
data[].bankAccounts[].bankBranchName string Branch name
data[].bankAccounts[].accountNumber string Bank account number
data[].bankAccounts[].accountAlias string Friendly alias for the account
data[].bankAccounts[].accountName string Account holder name
data[].bankAccounts[].currency string Account currency (ISO 4217)
data[].bankAccounts[].iban string International Bank Account Number
data[].bankAccounts[].swiftBic string SWIFT/BIC code
data[].bankAccounts[].country string ISO 3166-1 alpha-2 country code
data[].bankAccounts[].city string Bank branch city
data[].bankAccounts[].street string Bank branch street address
data[].bankAccounts[].postalCode string Bank branch postal code
data[].bankAccounts[].memo string Additional notes
data[].bankAccounts[].intermediaryBankCountry string ISO 3166-1 alpha-2 country code of the intermediary bank, where one is used
data[].bankAccounts[].intermediaryBankSwiftBic string SWIFT/BIC code of the intermediary bank, where one is used
data[].bankAccounts[].enabled boolean Whether account is enabled
data[].bankAccounts[].verified boolean Whether account is verified
data[].bankAccounts[].networkIds array of string Settlement networks this bank account may be used with
data[].bankAccounts[].createdAt string (date-time) Creation timestamp (ISO 8601)
data[].bankAccounts[].updatedAt string (date-time) Last update timestamp (ISO 8601)
data[].wallets array of object Crypto wallet addresses for digital asset settlement
data[].wallets[].uuid string (uuid) Unique identifier
data[].wallets[].blockchain string Blockchain network (e.g., Ethereum, Polygon, TRON)
data[].wallets[].asset string Digital asset symbol (e.g., USDC, USDT, BTC)
data[].wallets[].walletAddress string Blockchain wallet address
data[].wallets[].alias string Friendly alias for the wallet
data[].wallets[].type string SELF_HOSTED or CUSTODY
data[].wallets[].memo string Additional notes
data[].wallets[].vasp string Virtual Asset Service Provider name (if custody)
data[].wallets[].executionProvider string Execution provider name (if applicable)
data[].wallets[].default boolean Whether this is the default wallet for the asset
data[].wallets[].enabled boolean Whether wallet is enabled for trading
data[].wallets[].whitelisted boolean Whether wallet address is whitelisted
data[].wallets[].createdAt string (date-time) Creation timestamp (ISO 8601)
data[].wallets[].updatedAt string (date-time) Last update timestamp (ISO 8601)
data[].createdAt string (date-time) Beneficiary creation timestamp (ISO 8601)
data[].updatedAt string (date-time) Last update timestamp (ISO 8601)
total integer Total Beneficiary records returned

Beneficiary list — type: INDIVIDUAL

Section titled “Beneficiary list — type: INDIVIDUAL”
Field Type Required Description
data array of object Array of beneficiary objects
data[].firstname string Given name
data[].lastname string Family name
data[].dateOfBirth string (date) Date of birth (YYYY-MM-DD)
data[].countryOfOrigin string ISO 3166-1 alpha-2 country code of origin
data[].nationality string ISO 3166-1 alpha-2 country code of nationality
data[].uuid string (uuid) Unique identifier for the Beneficiary
data[].type string (enum) Whether this participant is a legal entity or a natural person — One of: ENTITY, INDIVIDUAL
data[].kind string (enum) Always BENEFICIARY — One of: BENEFICIARY
data[].enabled boolean Whether Beneficiary is enabled for trading
data[].verified boolean Whether Beneficiary has completed verification
data[].vasp boolean Virtual Asset Service Provider flag
data[].ownershipPercentage string Percentage of the participant owned, for participants held as an ownership interest. Absent when not recorded.
data[].clientShortcode string Your account identifier
data[].clientAccountGroupName string Account group (sub-account) name
data[].clientAccountGroupUuid string Account group UUID
data[].email string Beneficiary contact email
data[].phoneNumber string Beneficiary contact phone
data[].website string Beneficiary website URL
data[].address object Beneficiary address details
data[].address.street string Street address
data[].address.city string City
data[].address.stateProvince string State or province
data[].address.postalCode string Postal/ZIP code
data[].address.country string ISO 3166-1 alpha-2 country code
data[].address.createdAt string (date-time) Creation timestamp (ISO 8601)
data[].address.updatedAt string (date-time) Last update timestamp (ISO 8601)
data[].kycDetails object KYC and compliance information
data[].kycDetails.occupation string Occupation or business activity
data[].kycDetails.sourceOfFunds string Source of funds description
data[].kycDetails.methodOfVerification string Verification method used
data[].kycDetails.industryType string Industry classification
data[].kycDetails.entityType string Legal entity type
data[].kycDetails.natureOfActivity string Nature of business activity
data[].kycDetails.beneficiaryOwnership boolean Beneficiary ownership flag
data[].kycDetails.createdAt string (date-time) Creation timestamp (ISO 8601)
data[].kycDetails.updatedAt string (date-time) Last update timestamp (ISO 8601)
data[].identifications array of object Business registration and tax identifications
data[].identifications[].type string (enum) Identification type — One of: PASSPORT, NATIONAL_ID, DRIVERS_LICENSE, SSN, TAX_ID, LEI, EIN, VAT_NUMBER, BUSINESS_REGISTRATION, OTHER
data[].identifications[].number string Identification number
data[].identifications[].typeOther string Custom type (if type is “OTHER”)
data[].identifications[].createdAt string (date-time) Creation timestamp (ISO 8601)
data[].identifications[].updatedAt string (date-time) Last update timestamp (ISO 8601)
data[].associatedPersons array of object Associated Person details (e.g. authorized signatory, beneficial owners). enabled, verified and vasp are always null on these entries.
data[].associatedPersons[].uuid string (uuid) Unique identifier for the person
data[].associatedPersons[].firstname string Given name
data[].associatedPersons[].lastname string Family name
data[].associatedPersons[].dateOfBirth string (date) Date of birth (YYYY-MM-DD)
data[].associatedPersons[].countryOfOrigin string ISO 3166-1 alpha-2 country code of origin
data[].associatedPersons[].nationality string ISO 3166-1 alpha-2 country code of nationality
data[].associatedPersons[].type string (enum) Always INDIVIDUAL for an associated person — One of: INDIVIDUAL
data[].associatedPersons[].kind string (enum) Role this person holds in relation to the participant — One of: AUTHORIZED_SIGNATORY, BENEFICIARY_OWNER, INTERMEDIARY_BENEFICIARY_OWNER
data[].associatedPersons[].clientShortcode string Your account identifier
data[].associatedPersons[].phoneNumber string Contact phone
data[].associatedPersons[].website string Website URL
data[].associatedPersons[].email string Contact email
data[].associatedPersons[].createdAt string (date-time) Creation timestamp (ISO 8601)
data[].associatedPersons[].updatedAt string (date-time) Last update timestamp (ISO 8601)
data[].bankAccounts array of object Bank accounts configured for fiat settlement
data[].bankAccounts[].uuid string (uuid) Unique identifier for the bank account
data[].bankAccounts[].bankName string Bank institution name
data[].bankAccounts[].bankBranchName string Branch name
data[].bankAccounts[].accountNumber string Bank account number
data[].bankAccounts[].accountAlias string Friendly alias for the account
data[].bankAccounts[].accountName string Account holder name
data[].bankAccounts[].currency string Account currency (ISO 4217)
data[].bankAccounts[].iban string International Bank Account Number
data[].bankAccounts[].swiftBic string SWIFT/BIC code
data[].bankAccounts[].country string ISO 3166-1 alpha-2 country code
data[].bankAccounts[].city string Bank branch city
data[].bankAccounts[].street string Bank branch street address
data[].bankAccounts[].postalCode string Bank branch postal code
data[].bankAccounts[].memo string Additional notes
data[].bankAccounts[].intermediaryBankCountry string ISO 3166-1 alpha-2 country code of the intermediary bank, where one is used
data[].bankAccounts[].intermediaryBankSwiftBic string SWIFT/BIC code of the intermediary bank, where one is used
data[].bankAccounts[].enabled boolean Whether account is enabled
data[].bankAccounts[].verified boolean Whether account is verified
data[].bankAccounts[].networkIds array of string Settlement networks this bank account may be used with
data[].bankAccounts[].createdAt string (date-time) Creation timestamp (ISO 8601)
data[].bankAccounts[].updatedAt string (date-time) Last update timestamp (ISO 8601)
data[].wallets array of object Crypto wallet addresses for digital asset settlement
data[].wallets[].uuid string (uuid) Unique identifier
data[].wallets[].blockchain string Blockchain network (e.g., Ethereum, Polygon, TRON)
data[].wallets[].asset string Digital asset symbol (e.g., USDC, USDT, BTC)
data[].wallets[].walletAddress string Blockchain wallet address
data[].wallets[].alias string Friendly alias for the wallet
data[].wallets[].type string SELF_HOSTED or CUSTODY
data[].wallets[].memo string Additional notes
data[].wallets[].vasp string Virtual Asset Service Provider name (if custody)
data[].wallets[].executionProvider string Execution provider name (if applicable)
data[].wallets[].default boolean Whether this is the default wallet for the asset
data[].wallets[].enabled boolean Whether wallet is enabled for trading
data[].wallets[].whitelisted boolean Whether wallet address is whitelisted
data[].wallets[].createdAt string (date-time) Creation timestamp (ISO 8601)
data[].wallets[].updatedAt string (date-time) Last update timestamp (ISO 8601)
data[].createdAt string (date-time) Beneficiary creation timestamp (ISO 8601)
data[].updatedAt string (date-time) Last update timestamp (ISO 8601)
total integer Total Beneficiary records returned

Error — returned with HTTP 200

Section titled “Error — returned with HTTP 200”
Field Type Required Description
timestamp string Unix timestamp of the response (milliseconds).
resultCode string (enum) Failure reason. — One of: INVALID_PARAMETERS, UNAUTHORISED