Custody, Collateral, and Settlement

Use custody endpoints to connect the funding ledger with exchange collateral. They expose linked custody accounts, eligible exchanges, allocation state, and settlement records.

Discover Linked Accounts

GET /v1/custodians lists custody integrations, including Ceffu, Copper, Coinbase Custody, BitGo, Komainu, and Zodia Custody. GET /v1/custody/accounts returns the accounts and routes enabled for your organization.

{
  "custody_account_id": "cust_example_ceffu",
  "account_id": "acct_example_main",
  "custodian": "ceffu",
  "asset": "USDT",
  "balance": "10000.00",
  "allocated": "2500.00",
  "available": "7500.00",
  "eligible_venues": ["binance"],
  "updated_at": "2026-08-31T12:00:00.000Z"
}

This example is one account record. A Copper account can expose routes such as OKX and Bybit; a custody-only account can return an empty eligible_venues array. Provider availability, assets, settlement arrangements, and account eligibility determine the returned routes.

Allocate Collateral

Submit a source custody account, destination exchange, asset, and amount. Save client_allocation_id and the idempotency key before submission.

from rest_client import request

allocation = request("POST", "/v1/collateral/allocations", {
    "account_id": "acct_example_main",
    "client_allocation_id": "collateral-0001",
    "custody_account_id": "cust_example_ceffu",
    "venue": "binance",
    "asset": "USDT",
    "amount": "2500.00",
}, "allocation-request-0001")
print(allocation["allocation_id"], allocation["status"])

The acknowledgement returns pending. Follow the collateral channel or allocation lookup. active means the exchange has acknowledged the collateral. rejected requires a review of the available balance, eligibility, or provider response.

A release moves through releasing to released under the account’s collateral process. Open positions, orders, and pending settlements can restrict releasable amounts. Read current margin requirements before changing allocations.

Reconcile Settlements

Settlement records identify the custodian, exchange, asset, amount, cycle, and processing state. Positive amounts credit custody; negative amounts debit it. The examples include a Copper/OKX settlement of 125.50 USDT.

import { request } from './rest-client.mjs';
const query = new URLSearchParams({
  account_id: 'acct_example_main', venue: 'okx',
  start_time: '2026-08-31T00:00:00.000Z',
  end_time: '2026-09-01T00:00:00.000Z', limit: '100',
});
const page = await request('GET', `/v1/settlements?${query}`);
for (const settlement of page.settlements) {
  console.log(settlement.custodian, settlement.venue,
    settlement.amount, settlement.asset, settlement.status);
}

Retain the latest updated_at per settlement_id. Reconcile completed cycles against custody statements, exchange records, and the Trade8 ledger. Use custody:read for reconciliation and reserve custody:write for processes authorized to allocate assets.

Deposits and Internal Transfers

Deposit history tracks Bitcoin and stablecoin receipts through confirmations, review, and ledger credit. Use the deposit’s network and required confirmations when following progress.

Internal transfers move available balance between accounts belonging to the same organization. The key needs transfers:write and grants for both accounts. Persist client_transfer_id; after a timeout, query transfer history with that ID before retrying. A completed transfer has credited the destination ledger.