Withdrawals (payouts) — /v1/withdrawals
Pay USDT out of your business's Hot Wallet to a customer's or partner's address from your server, e.g. a player cash-out or a refund. The API uses the same engine as the dashboard: every limit, approval and safety check below applies to API withdrawals too.
Requirements
| What | Where |
|---|---|
| Business in Full mode with a verified Hot Wallet | Dashboard → Businesses (polysiad business full-mode) |
| API withdrawals switched on (default off) | Dashboard → Businesses → Withdrawals → Allow withdrawals through the merchant API (admin; audited) |
An API key with scope withdrawals:write (and withdrawals:read for GET) | Dashboard → API → New API key, or polysiad apikey create … -scopes withdrawals:read,withdrawals:write -ip 203.0.113.10 |
| The key must have an IP allowlist | Refused at creation without one; a key without one gets 403 ip_allowlist_required |
Withdrawal scopes are never part of the default scopes — an invoice key cannot move money. Use a separate key for payouts, kept on the server that sends them, and restrict it to that server's IP address(es).
Optional per-key limits (set when the key is created): max per withdrawal and daily limit (UTC day). They are checked in addition to the business limits.
Create — POST /v1/withdrawals
| Field | Type | |
|---|---|---|
to | string | Polygon address (0x…, 40 hex). Checksum is not required |
amount | string | USDT decimal, max 6 decimals ("25.50"). Not a JSON number |
customer_id | string, optional | Your user id (≤ 128 printable characters). Enables the per-customer daily limit |
reference | string, optional | Your own reference (≤ 128), e.g. your cash-out id. Returned in the object and webhooks |
Idempotency-Key header is required (1–64 visible ASCII characters). Retrying with the same key and body returns the same withdrawal (200, header Idempotent-Replayed: true) — never a second payout. The same key with a different body is 422 idempotency_key_reused. Generate the key when you create the cash-out on your side and store it with it.
curl -sS "$API/v1/withdrawals" \
-H "Authorization: Bearer $POLYSIA_PAYOUT_KEY" \
-H "Idempotency-Key: cashout-88213" \
-H "Content-Type: application/json" \
-d '{"to":"0xCustomerPolygonAddress","amount":"25.50","customer_id":"user-7","reference":"cashout-88213"}'{ "object": "withdrawal", "id": "wd_8f2c0a1b9d3e4f5a6b7c8d9e0f1a2b3c", "status": "approved",
"to": "0xCustomerPolygonAddress", "amount": "25.500000", "amount_units": "25500000",
"customer_id": "user-7", "reference": "cashout-88213", "idempotency_key": "cashout-88213",
"approvals_required": 0, "reason": null, "tx_hash": null, "source": "api",
"created_at": "2026-11-19T10:00:00Z", "sent_at": null, "completed_at": null }201 = created. The payout is sent by the running Polysia daemon a few seconds later; follow it with webhooks or GET.
Status
| Status | Meaning | Final? |
|---|---|---|
awaiting_approval | Above the manual threshold, auto withdrawals off, or a possible address-poisoning match — an admin must approve in the dashboard (2FA; maker ≠ checker) | no |
approved | Will be sent by the daemon | no |
waiting_funds | Hot Wallet balance too low; a sweep was forced and it is re-checked every 5 s | no |
broadcast | Transaction sent, not mined yet | no |
mined | Paid on-chain, waiting for finality (withdrawal.sent) | no (practically paid) |
completed | Finalized (withdrawal.completed, tx_hash set) | yes |
cancelled | Cancelled by you, an admin, or the timeout (default 24 h, reason) — nothing was paid | yes |
rejected | An approver rejected it — nothing was paid | yes |
failed | Could not be sent (simulation failed, e.g. the destination is blocked by the token) — needs review, not retried automatically | yes |
cancelling | A cancel of an in-flight tx is pending (dashboard only); ends as cancelled or completed | no |
Your balance bookkeeping: take the amount off the user's balance when you create the withdrawal. On cancelled, rejected or failed you must give it back — Polysia keeps no user balances. On completed the money has left for good.
Get / list — GET /v1/withdrawals/{id}, GET /v1/withdrawals
Scope withdrawals:read. List parameters: limit (1–100, default 50), starting_after (a wd_ id), status. Newest first; has_more tells you to page on. Ids of another business answer 404.
Cancel — POST /v1/withdrawals/{id}/cancel
Scope withdrawals:write. Only while nothing was broadcast (awaiting_approval, approved, waiting_funds); afterwards 409 withdrawal_not_cancellable (an in-flight payout can only be cancelled by an admin in the dashboard, which replaces the transaction). Cancelling a cancelled withdrawal returns it again (200).
Limits and checks (all enforced server-side)
| Check | Error |
|---|---|
| Business switch off | 403 api_withdrawals_disabled |
| Destination = zero address, the USDT contract, the factory, your own Hot Wallet or one of your deposit addresses | 400 destination_not_allowed |
| Destination not on the whitelist (when the business whitelist is on) | 400 destination_not_allowed |
| Amount > business max per withdrawal, or > this key's max per withdrawal | 400 amount_over_limit |
Daily limit exceeded — business, customer (customer_id) or this key (UTC day; cancelled / rejected give the amount back) | 400 daily_limit_exceeded |
| Above the manual threshold (default 500 USDT) or poisoning suspect | created as awaiting_approval |
| Request rate | 429 (the API's per-key create limit) |
Every create / cancel is in the dashboard audit log as api:<key id>.
Webhooks
Subscribe the endpoint to withdrawal.* explicitly (not part of "all events"). data is the withdrawal object above, plus withdrawal_id (the dashboard number) and user_ref (= customer_id).
| Event | When |
|---|---|
withdrawal.created | Created (any source) |
withdrawal.approved | Ready to send (auto or after approval) |
withdrawal.sent | Mined (tx_hash) — not final yet |
withdrawal.completed | Finalized (tx_hash) — final, paid |
withdrawal.cancelled | Cancelled (reason: by you / an admin / timeout) — give the balance back |
withdrawal.failed | Failed, needs review (reason) — give the balance back (or retry with a new Idempotency-Key after fixing the cause) |
As with all events: verify the signature, de-duplicate on the event id, do not rely on order — call GET /v1/withdrawals/{id} when in doubt.
Safety checklist
- One payout key per server, IP-restricted, per-key daily limit set, stored like a password.
- Set a business daily limit and keep the manual threshold low; large payouts then need a human with 2FA.
- Turn on the destination whitelist if you only pay known addresses (e.g. your exchange).
- Validate the user's address in your app before sending (Polygon, not an exchange deposit memo address).
- Watch the
withdraw_pending,withdraw_failedandwithdraw_limitalerts.

