Skip to navigation
HTTP APIAPI Domains

Custody

Crypto addresses, holdings, and on-chain transaction visibility

Custody Domain

The custody domain manages crypto addresses (deposit and whitelisted withdrawal addresses) and on-chain transaction visibility.

Deposit Addresses

Platform-generated addresses for receiving crypto deposits. Each address is specific to a sub-account and instrument.

Endpoints

EndpointMethodDescription
/addresses/internal/by-sub-account/{subAccountId}GETList deposit addresses
/addresses/internal/by-sub-account/{subAccountId}/by-instrument/{instrumentId}GETGet or create deposit address

Deposit Address Fields

FieldTypeDescription
addressstringBlockchain address
instrumentIdUUIDInstrument this address receives
blockchainstringBlockchain network
memostringTag/memo if required by the blockchain

Whitelisted Addresses

Pre-approved external addresses for withdrawals. Addresses must be whitelisted and confirmed before funds can be sent to them.

Endpoints

EndpointMethodDescription
/addresses/externalPOSTCreate whitelisted address
/addresses/external/{id}PUTUpdate address label
/addresses/external/initPOSTResend confirmation email
/addresses/external/confirmPOSTConfirm address with code
/addresses/external/by-sub-account/{subAccountId}GETList whitelisted addresses

Whitelisted Address Fields

FieldTypeDescription
idUUIDAddress identifier
addressstringExternal blockchain address
labelstringUser-defined name
instrumentIdUUIDInstrument for this address
subAccountIdUUIDSub-account this address belongs to
statusenumApproval status
memostringTag/memo if applicable

Address Status

StatusDescription
STATUS_CREATEDAddress created, awaiting confirmation
STATUS_CONFIRMEDUser confirmed via email code
STATUS_PENDING_VERIFICATIONAwaiting verification
STATUS_VERIFIEDVerified and ready for withdrawals
STATUS_WHITELISTED_IN_CUSTODIANWhitelisted in custody provider

Confirmation Flow

  1. Create address via POST /addresses/external
  2. Receive confirmation email with code
  3. Confirm via POST /addresses/external/confirm with code + MFA challenge
  4. Address status progresses through verification stages to STATUS_VERIFIED

Cooling Period: New addresses may require 24-48 hours before becoming active for withdrawals.

Crypto Transactions

View on-chain transaction details for deposits and withdrawals.

Endpoints

EndpointMethodDescription
/crypto-transactions/{id}GETGet transaction details

Transaction Fields

FieldTypeDescription
idUUIDTransaction identifier
txHashstringBlockchain transaction hash
statusenumTransaction status
confirmationsintegerCurrent confirmation count
blockHeightintegerBlock number

Custody Holdings

View aggregated custody holdings across the client account.

Endpoints

EndpointMethodDescription
/custody/holdings/mineGETGet custody holdings

Custody Holding Fields

FieldTypeDescription
blockchainstringBlockchain network
currencystringCurrency/token symbol
addressstringCustody address
totalConfirmedBalancedecimalTotal confirmed balance
totalUnconfirmedBalancedecimalPending balance
availableConfirmedBalancedecimalAvailable confirmed
availableUnconfirmedBalancedecimalAvailable pending
decimalsintegerDecimal precision

Address Formats by Blockchain

BlockchainAddress FormatMemo/Tag Required
Bitcoinbc1…, 3…, 1…No
Ethereum0x…No
StellarG…Yes (memo)
Rippler…Yes (destination tag)

Security Considerations

  1. Address Verification: Always verify the full address before sending
  2. Memo/Tag: Include memo/tag when required or funds may be lost
  3. Network Selection: Ensure correct blockchain network
  4. Whitelist Period: New addresses have cooling periods before activation
  5. Test Transactions: Consider small test transaction first