Copy page

TypeScript SDK — Account Services: Withdrawals & Transfers

Withdraw crypto, transfer between accounts, estimate gas fees, and review transfer history. All methods are on client.transfers.

See the API specifications for full request/response schemas and the authentication guide for setup.

Methods

withdrawCryptoFunds

POST /v2/withdraw/{network}/{ticker} · Authenticated

Initiates a cryptocurrency withdrawal. This is a security-sensitive mutation — the request is validated client-side before sending. The SDK enforces:

• network, ticker — required strings
• address — required string
• amount — required decimal string
• clientTransferId — optional UUID
• memo — optional string

Code
const withdrawal = await client.transfers.withdrawCryptoFunds({
  network: "ethereum",
  ticker: "ETH",
  address: "0x1234567890abcdef1234567890abcdef12345678",
  amount: "1.5",
  clientTransferId: "550e8400-e29b-41d4-a716-446655440000",
});

This is a POST mutation — never automatically retried. The optional clientTransferId (UUID) provides withdrawal idempotency: duplicate requests with the same ID do not create additional withdrawals. The destination must be on your approved address list. Amounts are decimal strings, not numbers.

transferBetweenAccounts

POST /v1/account/transfer/{currency} · Authenticated

Transfers funds between accounts within the same master group. The request is validated client-side. The SDK enforces:

• currency — required string
• sourceAccount, targetAccount — required strings
• amount — required decimal string
• clientTransferId — optional UUIDv4

Code
const transfer = await client.transfers.transferBetweenAccounts({
  currency: "btc",
  sourceAccount: "primary",
  targetAccount: "trading",
  amount: "0.25",
  clientTransferId: "550e8400-e29b-41d4-a716-446655440000",
});

console.log(transfer.message); // "Success, transfer completed."

Tip: When provided, clientTransferId must be a UUIDv4. It identifies the transfer request; the API documentation does not promise duplicate suppression, so confirm the transfer status before retrying an uncertain request.

getGasFeeEstimation

POST /v2/withdraw/{network}/{ticker}/feeEstimate · Authenticated

Returns an estimated gas fee for a withdrawal without actually executing it.

Code
const estimate = await client.transfers.getGasFeeEstimation({
  network: "ethereum",
  ticker: "ETH",
  address: "0x1234567890abcdef1234567890abcdef12345678",
  amount: "1.0",
});

// fee is a number, not a string
console.log(`Estimated fee: ${estimate.fee} ${estimate.currency}`);
console.log(`Free withdrawals remaining: ${estimate.monthlyRemaining}`);

Tip: Call this before withdrawCryptoFunds to show users the expected fee. The fee field is a number (not a string). monthlyLimit and monthlyRemaining track free withdrawal allowances.

listPastTransfers

POST /v2/transfers · Authenticated

Returns a history of past transfers (deposits, withdrawals, and internal transfers). The response is a bare array of V2Transfer objects.

Code
const transfers = await client.transfers.listPastTransfers({});

for (const t of transfers) {
  // t.eid may be bigint
  console.log(`${t.type}: ${t.amount} ${t.currency} (eid: ${t.eid})`);
}

Tip: The eid field in the response may be a bigint. The request body accepts optional timestamp (bigint/number) for pagination.

getTransactionHistory

POST /v1/transactions · Authenticated

Returns detailed transaction history with filtering support. The response is a wrapper object with a results array. Response fields like eid, tid, orderId, and other IDs may be bigint.

Code
const history = await client.transfers.getTransactionHistory({
  limit: 50,
});

for (const tx of history.results ?? []) {
  // Transaction entries are either trade or transfer records, with
  // operation-specific fields. IDs may be bigint.
  const currency = "currency" in tx ? tx.currency : "symbol" in tx ? tx.symbol : undefined;
  const eventId = "eid" in tx ? tx.eid : undefined;
  console.log(`${tx.amount ?? ""} ${currency ?? ""} (eid: ${eventId ?? "n/a"})`);
}

Tip: The timestamp_nanos request field accepts bigint for nanosecond-precision filtering. Use continuation_token from the response for pagination. Many response ID fields are bigint — see Data Types.

listCustodyFeeTransfers

POST /v1/custodyaccountfees · Authenticated

Returns custody fee transfers for custody accounts. The request body accepts an optional timestamp field (bigint or number) for filtering. The response is a bare array.

Code
const fees = await client.transfers.listCustodyFeeTransfers({});

for (const fee of fees) {
  console.log(`${fee.feeAmount} ${fee.feeCurrency} — ${fee.eventType}`);
}

Tip: Fee amounts are decimal strings. Pass timestamp as a bigint or number to filter results — the API returns records on or after the given timestamp (lower bound, forward paging), not backward.

What's next

• Addresses & Deposits — managing deposit and approved withdrawal addresses
• Balances & Account — checking balances
• Request Validation — how client-side validation catches errors early
• Data Types — decimal strings and bigint fields