# TypeScript SDK — Account Services: Withdrawals & Transfers

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

See the [API specifications](/api-specifications) for full request/response schemas and the [authentication guide](/tools/typescript-sdk/authentication) for setup.

## Methods

### withdrawCryptoFunds

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

Initiates a cryptocurrency withdrawal. This is a security-sensitive mutation — the request body is [validated client-side](/tools/typescript-sdk/deep-dives/request-validation) before sending. The SDK enforces:

- `address` — required string
- `amount` — required decimal string
- `clientTransferId` — optional UUID
- `memo` — optional string

Uses the `{ path, body }` input pattern with both `network` and `ticker` as path parameters.

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

This is a POST mutation — never automatically retried. Use the optional `clientTransferId` (UUID) for idempotency if you need safe retries. The destination must be on your [approved address list](/tools/typescript-sdk/reference/account-services/addresses-and-deposits). Amounts are decimal strings, not numbers.

### transferBetweenAccounts

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

Transfers funds between accounts within the same master group. The request body is [validated client-side](/tools/typescript-sdk/deep-dives/request-validation). The SDK enforces:

- `sourceAccount`, `targetAccount` — required strings
- `amount` — required decimal string
- `clientTransferId` — required UUIDv4

Uses the `{ path, body }` input pattern with `currency` as the path parameter.

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

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

> **Caveat:** `clientTransferId` is a **required** UUIDv4 — the SDK validates its format client-side. This provides idempotency for safe retries on network failures.

### getGasFeeEstimation

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

Returns an estimated gas fee for a withdrawal without actually executing it. Uses the `{ path, body }` input pattern with both `network` and `ticker` as path parameters.

```ts
const estimate = await client.accountServices.getGasFeeEstimation({
  path: { network: "ethereum", ticker: "ETH" },
  body: {
    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.

```ts
const transfers = await client.accountServices.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`.

```ts
const history = await client.accountServices.getTransactionHistory({
  limit: 50,
});

for (const tx of history.results ?? []) {
  // tx.eid, tx.tid, tx.orderId, tx.correlationId may be bigint
  console.log(`${tx.amount} ${tx.currency ?? tx.symbol} (eid: ${tx.eid})`);
}
```

> **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](/tools/typescript-sdk/deep-dives/data-types).

## What's next

- [Addresses & Deposits](/tools/typescript-sdk/reference/account-services/addresses-and-deposits) — managing deposit and approved withdrawal addresses
- [Balances & Account](/tools/typescript-sdk/reference/account-services/balances-and-account) — checking balances
- [Request Validation](/tools/typescript-sdk/deep-dives/request-validation) — how client-side validation catches errors early
- [Data Types](/tools/typescript-sdk/deep-dives/data-types) — decimal strings and bigint fields