Transfers

client.transfers is your ledger transfer history: every balance movement, regardless of cause. Deposits, withdrawals, trade legs, fees, rebates, and internal transfers all show up here as transfer rows. Every method is authenticated and account-scoped, so each input accepts an optional account field ("main", "active", or { subaccountId }). See Account scoping for how the default resolves.

Amounts are decimal strings and timestamps are epoch milliseconds. Where the backend reports it, each row also carries the running balanceAfter.

Methods

list(input?, options?)

Returns { transfers, nextPageToken } for the account scope. The input is optional; use it to filter by direction, time range, transfer code, and ledger, and page through with the returned token.

const { transfers, nextPageToken } = await client.transfers.list({
	limit: 100,
	transferCode: "deposit",
	timestampMin: Date.now() - 7 * 24 * 60 * 60 * 1000,
});

for (const tr of transfers) {
	console.log(tr.type, tr.assetId, tr.amount, tr.isDebit ? "out" : "in");
}

Page through the full history with the returned token:

let pageToken = "";
do {
	const page = await client.transfers.list({ pageToken, limit: 200 });
	console.log(page.transfers.length);
	pageToken = page.nextPageToken;
} while (pageToken !== "");

ListTransfersInput

transferCode is one of "deposit", "withdraw", "maker_fee", "taker_fee", "internal_transfer", "trade_base", "trade_quote", "rebate", "funding_to_trading", "trading_to_funding", "trading_withdraw_reserve", "funding_user_transfer", or "trading_withdraw_request_fee".

A trading withdrawal writes two rows: "trading_withdraw_reserve" for the amount held, and "trading_withdraw_request_fee" for the fee charged to request it. Filter on the reserve code alone and the fee row is missing from your reconciliation.

subscribe(input)

Streams live transfers over a private channel. Takes an accountId plus the standard handler fields, and returns an idempotent unsubscribe function. See the realtime client reference for the handler contract.

const unsubscribe = client.transfers.subscribe({
	accountId,
	onEvent: (tr) => console.log(tr.type, tr.assetId, tr.amount),
	onError: (ctx) => console.error(ctx.channel, ctx.error),
});

// later
unsubscribe();

Each publication carries a batch of transfer legs, and onEvent receives them one at a time in the order the account's transfers settled. A deposit or withdrawal leg still waiting for its lifecycle details arrives once they are known. (transferId, accountCode, isDebit) identifies a leg: a leg with an identity you already hold replaces the earlier copy. A malformed leg reaches onError without dropping the rest of its batch.

The LedgerTransfer shape

List and stream results share one parsed shape. Amounts are decimal strings and timestamps are epoch milliseconds.

import type { LedgerTransfer, LedgerTransferSide, TransferCodeValue } from "@polyester/sdk";

transferId is the stable transfer identifier, an unsigned 128-bit integer as a decimal string. Both legs of a transfer share it; with accountCode and isDebit it identifies one row.

type is a TransferCodeValue (for example "deposit") plus "unspecified". accountCode is "funding" | "trading" | "unspecified". Side kind includes "unspecified" when the server omits a label. An external source or destination can include chainId, the PolyChain network ID from ZipperChainConfig. It is not an EIP-155 chain ID or a Polyester chain ID.

Related

• Balances for the current totals these movements sum to.
• Internal transfers to move funds between Polyester accounts.
• Deposit and Withdrawals for on-chain movement.
• Realtime client reference for the streaming handler contract.

Related Topics