Get Sender (Collection Accounts) List

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

List Senders

Retrieve a list of third-party sender (collection) details configured for your account along with a list of their wallet addresses that they will deliver from. Senders are external entities that can send digital assets to Zodia Markets on your behalf. The contra-currency is then delivered to your named account.

Sender Status

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

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

Trading Requirement: Only Sender with enabled: true AND verified: true can be used for third-party collection 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 collection, the wallet must have enabled: true AND whitelisted: true, and match the asset being traded.

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 Senders

def get_all_senders():
    all_senders = []
    offset = 0
    page_size = 50

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

        senders = response['data']
        all_senders.extend(senders)

        if len(senders) < page_size:
            break

        offset += page_size

    return all_senders

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 — 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/senders"
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 senders in data['data']:
        print(f"\n{senders['companyName']}: {senders['uuid']}")
        print(f"  Enabled: {senders['enabled']}")
        print(f"  Verified: {senders['verified']}")
        print(f"  Wallets: {len(senders['wallets'])}")
        print(f"  Bank Accounts: {len(senders['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 — 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/senders';
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(senders => {
      console.log(`\n${senders.companyName}: ${senders.uuid}`);
      console.log(`  Enabled: ${senders.enabled}`);
      console.log(`  Verified: ${senders.verified}`);
      console.log(`  Wallets: ${senders.wallets.length}`);
      console.log(`  Bank Accounts: ${senders.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/senders \
  -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

Find Verified senders

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

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

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

Get senders by Name

def find_senders_by_name(name):
    response = make_api_request('POST', 'api/3/senders', {})

    for senders in response['data']:
        if senders['companyName'].lower() == name.lower():
            return senders

    return None

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

Find Wallets for Specific Asset

def find_wallets_for_asset(senders_id, asset):
    response = make_api_request('POST', 'api/3/senders', {})

    for senders in response['data']:
        if senders['uuid'] == senders_id:
            wallets = [
                w for w in senders['wallets']
                if w['asset'] == asset and w['enabled'] and w['whitelisted']
            ]
            return wallets

    return []

# Find USDC wallets for a senders
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 Sender Trading Readiness

def is_senders_ready_for_trading(senders):
    """Check if senders is ready for third-party settlement"""
    if not senders['enabled']:
        return False, "Sender is not enabled"

    if not senders['verified']:
        return False, "Sender 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 senders['wallets']
    )
    has_bank = any(
        ba['enabled'] and ba['verified']
        for ba in senders['bankAccounts']
    )

    if not (has_wallet or has_bank):
        return False, "No valid wallets or bank accounts configured"

    return True, "Ready for trading"

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

Filter by Account Group

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

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

Domain: Payment participants

Request

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

Headers

Header	Required	Description
`Rest-Key`		API key for authentication
`Rest-Sign`		Calculated API Signature

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

200

Sender list — `type: ENTITY`

Field	Type	Description
`data`	array of object	Array of sender objects
`data[].companyName`	string	Sender company/entity name
`data[].companyName2`	string	Second line of the registered name, where the name needs one
`data[].dateOfFormation`	string (date)	Sender 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 Sender
`data[].type`	string (enum)	Whether this participant is a legal entity or a natural person — One of: ENTITY, INDIVIDUAL
`data[].kind`	string (enum)	Always `SENDER` — One of: SENDER
`data[].enabled`	boolean	Whether Sender is enabled for trading
`data[].verified`	boolean	Whether Sender 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	Sender contact email
`data[].phoneNumber`	string	Sender contact phone
`data[].website`	string	Sender website URL
`data[].address`	object	Sender 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 (not currently supported)
`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 the Sender will send funds from 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)	Sender creation timestamp (ISO 8601)
`data[].updatedAt`	string (date-time)	Last update timestamp (ISO 8601)
`total`	integer	Total Sender records returned

Sender list — `type: INDIVIDUAL`

Field	Type	Description
`data`	array of object	Array of sender 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 Sender
`data[].type`	string (enum)	Whether this participant is a legal entity or a natural person — One of: ENTITY, INDIVIDUAL
`data[].kind`	string (enum)	Always `SENDER` — One of: SENDER
`data[].enabled`	boolean	Whether Sender is enabled for trading
`data[].verified`	boolean	Whether Sender 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	Sender contact email
`data[].phoneNumber`	string	Sender contact phone
`data[].website`	string	Sender website URL
`data[].address`	object	Sender 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 (not currently supported)
`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 the Sender will send funds from 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)	Sender creation timestamp (ISO 8601)
`data[].updatedAt`	string (date-time)	Last update timestamp (ISO 8601)
`total`	integer	Total Sender records returned

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