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.


Request

Body Parameters

ParameterTypeRequiredDefaultDescription
accountGroupUuidStringNo-Filter senders by specific account group UUID
limitIntegerNo50Maximum results to return (1-200)
offsetIntegerNo0Offset for pagination

Example Request

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

Get all senders (no filter):

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

Response

Success Response (200 OK)

{
    "data": [
        {
            "companyName": "MY TEST SENDER",
            "dateOfFormation": "2026-03-04",
            "countryOfFormation": "RS",
            "countryOfRegistration": "RS",
            "uuid": "adece4a5-52eb-4858-93ad-1c7ce3271c0c",
            "clientShortcode": "USDTTEST1",
            "clientAccountGroupName": "Default",
            "clientAccountGroupUuid": "2073252c-81ed-41be-bf4d-d51b8f2246b8",
            "type": "ENTITY",
            "kind": "SENDER",
            "phoneNumber": "",
            "website": "www.po123411.com",
            "email": "[email protected]",
            "vasp": true,
            "enabled": true,
            "verified": true,
            "beneficiaryAddress": {
                "country": "GB",
                "city": "London",
                "street": "200 Twenty Street",
                "postalCode": "N99 2LA",
                "stateProvince": "London",
                "createdAt": "2026-05-07T16:47:25Z",
                "updatedAt": "2026-05-07T16:47:25Z"
            },
            "kycDetails": {
                "occupation": "Service Provider",
                "sourceOfFunds": "Trading",
                "methodOfVerification": "Electronic",
                "industryType": "Technology",
                "entityType": "NA",
                "natureOfActivity": "Payment Service Provider",
                "beneficiaryOwnership": false,
                "createdAt": "2026-05-07T16:47:24Z",
                "updatedAt": "2026-05-07T16:47:24Z"
            },
            "associatedPersons": [
                {
                    "firstname": "Paul",
                    "lastname": "Spaul",
                    "dateOfBirth": "2017-01-31",
                    "countryOfOrigin": "AR",
                    "nationality": "AR",
                    "uuid": "bcaaf5aa-373e-496e-bc49-d35f0735edbe",
                    "clientShortcode": "USDTTEST1",
                    "type": "INDIVIDUAL",
                    "kind": "AUTHORIZED_SIGNATORY",
                    "phoneNumber": "",
                    "website": "",
                    "email": "",
                    "createdAt": "2026-05-07T16:47:20Z",
                    "updatedAt": "2026-05-07T16:47:20Z"
                }
            ],
            "identifications": [
                {
                    "type": "OTHER",
                    "number": "MB109871",
                    "typeOther": "MSB",
                    "createdAt": "2026-05-07T16:47:21Z",
                    "updatedAt": "2026-05-07T16:47:21Z"
                },
                {
                    "type": "BUSINESS_REGISTRATION",
                    "number": "100099887762",
                    "typeOther": "",
                    "createdAt": "2026-05-07T16:47:23Z",
                    "updatedAt": "2026-05-07T16:47:23Z"
                }
            ],
            "bankAccounts": [],
            "wallets": [
                {
                    "uuid": "c7f3d22f-d70a-4e08-9aeb-46187603ecba",
                    "blockchain": "Ethereum",
                    "asset": "USDC",
                    "walletAddress": "0x9023092829822",
                    "alias": "USDC_SENDER_USDTTEST1",
                    "type": "SELF_HOSTED",
                    "memo": "MY USDC WALLET",
                    "vasp": "",
                    "executionProvider": "",
                    "default": true,
                    "enabled": true,
                    "whitelisted": true,
                    "createdAt": "2026-04-16T15:49:19Z",
                    "updatedAt": "2026-04-16T15:49:19Z"
                },
                {
                    "uuid": "37f58a57-2795-4280-979b-960984d6759f",
                    "blockchain": "TRON",
                    "asset": "USDT",
                    "walletAddress": "0x98289282827272",
                    "alias": "USDT_WALLET_USDTTEST1_SENDER",
                    "type": "SELF_HOSTED",
                    "memo": "",
                    "vasp": "",
                    "executionProvider": "",
                    "default": true,
                    "enabled": true,
                    "whitelisted": true,
                    "createdAt": "2026-03-25T14:15:19Z",
                    "updatedAt": "2026-03-25T14:15:19Z"
                }
            ],
            "createdAt": "2026-05-07T16:47:27Z",
            "updatedAt": "2026-05-07T16:47:27Z"
        }
    ],
    "total": 1
}

Response Fields

Root Object

FieldTypeDescription
dataArrayArray of sender objects

Sender Object

FieldTypeDescription
uuidStringUnique identifier for the sender
companyNameStringSender company/entity name
typeStringENTITY or INDIVIDUAL
kindStringAlways SENDER
enabledBooleanWhether sender is enabled for trading
verifiedBooleanWhether sender has completed verification
vaspBooleanVirtual Asset Service Provider flag
clientShortcodeStringYour account identifier
clientAccountGroupNameStringAccount group (sub-account) name
clientAccountGroupUuidStringAccount group UUID
emailStringSender contact email
phoneNumberStringSender contact phone
websiteStringSender website URL
dateOfFormationStringSender Company formation date (YYYY-MM-DD)
countryOfFormationStringISO 3166-1 alpha-2 country code
countryOfRegistrationStringISO 3166-1 alpha-2 country code
addressObjectSender address details
kycDetailsObjectKYC and compliance information
identificationsArrayBusiness registration and tax identifications
associatedPersonsArrayAssociated Person details (e.g. authorized signatory, beneficial owners)
bankAccountsArrayBank accounts configured for fiat settlement (not currently supported)
walletsArrayCrypto wallet addresses the Sender will send funds from for digital asset settlement
createdAtStringSender creation timestamp (ISO 8601)
updatedAtStringLast update timestamp (ISO 8601)
totalStringTotal Sender records returned

Address

FieldTypeDescription
streetStringStreet address
cityStringCity
stateProvinceStringState or province
postalCodeStringPostal/ZIP code
countryStringISO 3166-1 alpha-2 country code
createdAtStringCreation timestamp (ISO 8601)
updatedAtStringLast update timestamp (ISO 8601)

KYC Details

FieldTypeDescription
occupationStringOccupation or business activity
sourceOfFundsStringSource of funds description
methodOfVerificationStringVerification method used
industryTypeStringIndustry classification
entityTypeStringLegal entity type
natureOfActivityStringNature of business activity
beneficiaryOwnershipBooleanBeneficiary ownership flag
createdAtStringCreation timestamp (ISO 8601)
updatedAtStringLast update timestamp (ISO 8601)

Identification Object

FieldTypeDescription
typeStringBUSINESS_REGISTRATION, LEI, PASSPORT, NATIONAL_ID, DRIVERS_LICENSE, SSN, TAX_ID, EIN, VAT_NUMBER, OTHER
numberStringIdentification number
typeOtherStringCustom type (if type is "OTHER")
createdAtStringCreation timestamp (ISO 8601)
updatedAtStringLast update timestamp (ISO 8601)

Bank Account Object

FieldTypeDescription
bankNameStringBank institution name
bankBranchNameStringBranch name
accountNumberStringBank account number
accountAliasStringFriendly alias for the account
accountNameStringAccount holder name
currencyStringAccount currency (ISO 4217)
ibanStringInternational Bank Account Number
swiftBicStringSWIFT/BIC code
countryStringISO 3166-1 alpha-2 country code
cityStringBank branch city
streetStringBank branch street address
postalCodeStringBank branch postal code
memoStringAdditional notes
enabledBooleanWhether account is enabled
verifiedBooleanWhether account is verified
createdAtStringCreation timestamp (ISO 8601)
updatedAtStringLast update timestamp (ISO 8601)

Wallet Object

FieldTypeDescription
uuidStringUnique identifier
blockchainStringBlockchain network (e.g., Ethereum, Polygon, TRON)
assetStringDigital asset symbol (e.g., USDC, USDT, BTC)
walletAddressStringBlockchain wallet address
aliasStringFriendly alias for the wallet
typeStringSELF_HOSTED or CUSTODY
memoStringAdditional notes
vaspStringVirtual Asset Service Provider name (if custody)
executionProviderStringExecution provider name (if applicable)
defaultBooleanWhether this is the default wallet for the asset
enabledBooleanWhether wallet is enabled for trading
whitelistedBooleanWhether wallet address is whitelisted
createdAtStringCreation timestamp (ISO 8601)
updatedAtStringLast update timestamp (ISO 8601)

Sender Status

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

FieldValueMeaning
enabledtrueSender is active
enabledfalseSender is inactive
verifiedtruePassed KYC/compliance checks
verifiedfalsePending 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:

FieldValueRequired for Trading?
enabledtrue✅ Yes
whitelistedtrue✅ Yes
enabledfalse❌ No - wallet disabled
whitelistedfalse❌ 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 max (1-200) and offset parameters to paginate through results.

Example: Get All Senders

def get_all_senders():
    all_senders = []
    offset = 0
    max_per_page = 200
    
    while True:
        response = make_api_request('POST', 'api/3/senders', {
            'max': max_per_page,
            'offset': offset
        })
        
        senders = response['data']
        all_senders.extend(senders)
        
        if len(senders) < max_per_page:
            break
        
        offset += max_per_page
    
    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
body = {
    "accountGroupUuid": "2073252c-81ed-41be-bf4d-d51b8f2246b8",
    "max": 50,
    "offset": 0
}
body_json = json.dumps(body)

# Generate signature
path = "api/3/senders"
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 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
const body = {
  accountGroupUuid: '2073252c-81ed-41be-bf4d-d51b8f2246b8',
  max: 50,
  offset: 0
};
const bodyJson = JSON.stringify(body);

// Generate signature
const path = 'api/3/senders';
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(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 '{
    "accountGroupUuid": "2073252c-81ed-41be-bf4d-d51b8f2246b8",
    "max": 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")