{
"data": [
{
"id": "b1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"currency": "USDT",
"amount": "150.5",
"from_balance": "main",
"to_balance": "spot",
"created_at": 1755000000
},
{
"id": "9c8b7a6d-5e4f-4a3b-9c8d-7e6f5a4b3c2d",
"currency": "USDT",
"amount": "40",
"from_balance": "main",
"to_balance": "collateral",
"created_at": 1754990000
},
{
"id": "5f4e3d2c-1b0a-4c9d-8e7f-6a5b4c3d2e1f",
"currency": "USDT",
"amount": "40",
"from_balance": "spot",
"to_balance": "main",
"created_at": 1754990000
}
],
"limit": 50,
"offset": 0
}{
"code": 0,
"message": "Validation failed",
"errors": {
"from_balance": [
"The selected from_balance is invalid."
]
}
}Get transfer history
The endpoint returns the history of transfers between the main, spot and collateral balances of the authenticated account, newest first.
The endpoint requires an API key with the Balance transfer permission enabled — the same permission as Transfer between balances.
For transfers between a main account and its sub-accounts, use Get Sub-Account Transfer History instead.
Every transfer is recorded with the main balance on one side. A transfer between the spot and collateral balances executes as two steps through the main balance, so such a transfer appears as two records — spot → main and main → collateral — each carrying a separate identifier and the full transferred amount. Account for both records when summing amounts. Filter combinations that cannot be stored (spot with collateral, collateral with spot, or the same balance on both sides) return an empty data array — filter by the individual legs instead.
Records are ordered from newest to oldest by the order of execution. Neither id nor created_at is a sort key — id is a random identifier, and two records can share the same created_at second — so page through the history with limit and offset. The response carries no total count and no cursor: a returned count below limit marks the last page, and an empty array means no further records. offset cannot exceed 10000 — for a longer history, use report generation on the History page.
The API does not cache the response. POST /api/v4/main-account/transfer returns 201 as soon as a transfer is queued, so a request sent immediately afterwards can return no records yet. A failed transfer leaves no record, so a missing record does not show whether a transfer is still queued or failed: check again, and do not resend automatically. The history also covers transfers the platform performs for the account, such as mining-pool conversions, and transfers in delisted currencies. Every returned transfer is completed.
{
"data": [
{
"id": "b1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"currency": "USDT",
"amount": "150.5",
"from_balance": "main",
"to_balance": "spot",
"created_at": 1755000000
},
{
"id": "9c8b7a6d-5e4f-4a3b-9c8d-7e6f5a4b3c2d",
"currency": "USDT",
"amount": "40",
"from_balance": "main",
"to_balance": "collateral",
"created_at": 1754990000
},
{
"id": "5f4e3d2c-1b0a-4c9d-8e7f-6a5b4c3d2e1f",
"currency": "USDT",
"amount": "40",
"from_balance": "spot",
"to_balance": "main",
"created_at": 1754990000
}
],
"limit": 50,
"offset": 0
}{
"code": 0,
"message": "Validation failed",
"errors": {
"from_balance": [
"The selected from_balance is invalid."
]
}
}Used in these guides
- On/Off-Ramp integration — confirming that a Main/Trade transfer completed.
- Payment Integration — crypto deposits, withdrawals, conversion, WhiteBIT Codes, and Express Withdraw.
Rate limit
Authorizations
Body
Balance FROM which funds moved. Acceptable values: main, spot, collateral. Do not send this parameter in order to receive transfers from every balance.
Values are case-sensitive — main, not MAIN. An empty string counts as no filter.
main, spot, collateral "main"
Balance TO which funds moved. Acceptable values: main, spot, collateral. Do not send this parameter in order to receive transfers to every balance.
Values are case-sensitive — main, not MAIN. An empty string counts as no filter.
main, spot, collateral "spot"
Was this page helpful?