Z Zise Developers
/
简体中文
Stablecoin Account › API Reference › Withdrawals

Withdrawal list (cursor pagination and four filters)

GET /v1/withdrawals scope: withdrawals:read
Merchant account

Call as the merchant. x-on-behalf-of is optional here: include it for one member's withdrawals, or omit it for all withdrawals under your merchant.

── This endpoint addresses a specific failure scenario ──

If POST /v1/withdrawals times out and you never receive an order ID, resending with the same x-idempotency-key within 24 hours replays the original response. After 24 hours, the same key causes a second actual debit: once the idempotency record expires, the handler executes, generates a new order ID and ledger idempotency key, and no database layer prevents it. Real funds are involved: the member's available has already moved to withdrawing.

Before this endpoint, the Open API had no way to recover that original withdrawal by member, time, or status; you had to search manually in the merchant portal. Therefore, before resubmitting, query with x-on-behalf-of + from to check whether that withdrawal already exists.

⚠ to is exclusive (< to), while from is inclusive. Both use created_at, the same column as the cursor, and can directly support incremental synchronization.

⚠ Output matches GET /v1/withdrawals/{id} field for field, including keys and amount representation. amount is a fixed-point integer string using the asset's ledger_scale, not a decimal amount with an inserted point.

Query Parameters

FieldTypeRequiredDescription
limit integer Optional Defaults to 20, maximum 100.
cursor string Optional Pass the previous page's next_cursor unchanged.
status string Optional One of locked / settled / failed. ⚠ This is a closed enum enforced by a database constraint. Other values immediately return 400 invalid_fields; returning an empty list could make you conclude that no failed withdrawals exist while you are trying to reconcile them.
asset string Optional Filter by asset, automatically converted to uppercase.
from string Optional Start time, inclusive, in ISO-8601. Compared against created_at.
to string Optional End time, exclusive, in ISO-8601.
FieldTypeRequiredDescription
x-on-behalf-of string Optional Include for this member's withdrawals only; omit for all withdrawals under your merchant. Deliberately optional: in the scenario above, you may not know which member is involved because you did not even receive an order ID.

Response

200OK
{
  "data": [
    {
      "id": "wdr_9f1c0b2a-4d33-4a51-9f2e-7c1b0a5d6e88",
      "external_member_id": "u_10023",
      "asset": "USDT",
      "amount": "200000000",
      "ledger_scale": 6,
      "to_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
      "status": "locked",
      "created_at": "2026-08-12T09:31:02.881Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
400invalid_fields: status is not one of the three values, or from / to is not valid ISO-8601.
404member_not_found: x-on-behalf-of was supplied but the member does not exist, belongs to another merchant, or is suspended.
Request 
curl -X GET 'https://api.zinfra.vip/v1/withdrawals' \
  -H 'x-auth-token: Bearer $TOKEN'
const res = await fetch("https://api.zinfra.vip/v1/withdrawals", {
  method: "GET",
  headers: {
    "x-auth-token": "Bearer $TOKEN",
  },
});
// Keep monetary amounts as strings, never numbers.
const data = await res.json();
import requests

res = requests.get(
    "https://api.zinfra.vip/v1/withdrawals",
    headers={
        "x-auth-token": "Bearer $TOKEN",
    },
)
# Use Decimal(str(...)) for amounts, not float.
data = res.json()
req, _ := http.NewRequest("GET", "https://api.zinfra.vip/v1/withdrawals",
    nil)
req.Header.Set("x-auth-token", "Bearer $TOKEN")
res, err := http.DefaultClient.Do(req)
// Decode amount fields as string, not float64.
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.zinfra.vip/v1/withdrawals"))
    .header("x-auth-token", "Bearer $TOKEN")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
// Use String / BigDecimal for amounts, not double.
$ch = curl_init('https://api.zinfra.vip/v1/withdrawals');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-auth-token: Bearer $TOKEN',
  ],
]);
$res = curl_exec($ch);
// Use bcmath / strings for amounts, not floatval.
200 
{
  "data": [
    {
      "id": "wdr_9f1c0b2a-4d33-4a51-9f2e-7c1b0a5d6e88",
      "external_member_id": "u_10023",
      "asset": "USDT",
      "amount": "200000000",
      "ledger_scale": 6,
      "to_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
      "status": "locked",
      "created_at": "2026-08-12T09:31:02.881Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}