binance_get_fiat_history
Retrieve complete fiat deposit, withdrawal, buy, and sell history across pages and time windows, with automatic paging, API-call budgeting, and a resume cursor for interrupted walks.
Instructions
Walk fiat deposit/withdraw or buy/sell history across pages and time windows.
Tries ONE call spanning beginTime=since .. endTime=now (or resume_before when
resuming) and pages page until a short page signals the end. If that wide-span
attempt fails with a plausibly span-related HTTP error (commonly -1127, an
undocumented span cap on these two endpoints), falls back to walking 30-day windows
newest-first instead.
Honors a max_calls budget so one invocation can never blow past the weight-limited
call rate — deposits/withdrawals cost UID 45000/call (default budget 4, i.e. the
whole 180000/min UID budget for a minute), buys/sells cost IP 1/call (default budget
20). Every request checks the budget first, and a request that itself errors still
counts against it, since it still spent real quota.
The walk NEVER discards rows it already has: whenever it stops early — budget
exhaustion or ANY request failure, span-related or not — it renders the normal
report (rows collected so far, totals, call count) plus a resume_before cursor,
and for a failure it also shows the underlying error (via handle_api_error) as a
prominent line. Binance treats endTime as inclusive, so a re-fetched boundary row
is expected; rows are deduped by orderNo before being returned. The cursor comes
in two flavours, worded differently so one is never mistaken for the other: a
redo cursor (the wide span, or the window in progress, was not fully covered —
page order inside it is undocumented, so the whole thing must be retried) says it
"re-covers the same range, it does not advance"; an advance cursor (every window
up to it is fully covered; only the budget stopped a NEW window from starting) says
rows "were not fetched" before it and to "continue" from there.
Status values Binance returns for fiat orders/payments: Processing, Failed, Successful, Finished, Refunding, Refunded, Refund Failed, Order Partial credit Stopped.
When to Use:
A bulk backfill of fiat activity (deposits, withdrawals, or crypto buys/sells with fiat) since account creation, paged and budgeted automatically.
Continuing a previous walk that stopped early: pass its
resume_beforeback in.
When NOT to Use:
A single narrow lookup — use
binance_get_fiat_orders/binance_get_fiat_paymentsdirectly with your own begin_time/end_time; it is one call instead of many.Binance Card spend — not retrievable via any API (see the module docstring); a "Credit Card"
paymentMethodinbuys/sellsis a bank card, not the Binance Card.
Returns:
Deduped rows sorted newest-first (display capped at 50, JSON keeps the full walked
set), a per-fiat-currency total (and, for buys/sells, a per-crypto-currency received
total), how many API calls were spent, whether the window fallback triggered, and —
when the walk stopped early — a resume_before cursor plus (for a failure) the
error that caused the stop.
Examples: params = {"kind": "deposits"} params = {"kind": "buys", "since": "2023-01-01"} params = {"kind": "withdrawals", "resume_before": 1700000000000}
Error Handling:
A span-related HTTP error on the wide-span attempt triggers the 30-day-window
fallback automatically. Any failure after that point — inside a window, or an
auth/rate-limit/envelope/other error that was never span-related — stops the walk
instead of raising: the response still shows the rows already collected, the
API-call count, a resume_before cursor, and the failure itself via
handle_api_error. A malformed since/resume_before returns
Error: <field> must be epoch milliseconds or an ISO-8601 string before any call
is made.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |