Withdrawal requests

Generated page, from the OpenAPI specification the gateway serves (GET /v1/openapi.json). Do not edit it by hand: it is rewritten on every build.

Method	Path	Description
GET	/v1/payout-requests	List your withdrawal requests
POST	/v1/payout-requests	Request a withdrawal
GET	/v1/payout-requests/{id}	Retrieve a withdrawal request

GET /v1/payout-requests

List your withdrawal requests

Your requests and their state, from requested through to the decision.

Parameters

Name	In	Required	Description
page	query	no
per_page	query	no

Responses

• 200 — OK
• 401 — API key missing or rejected (Error)
• 403 — The key does not carry the required scope, or the account is not active (Error)
• 429 — The key's request budget is exhausted (300/min) — honour Retry-After (Error)

POST /v1/payout-requests

Request a withdrawal

Requests a withdrawal of YOUR balance to your own account.

⚠️ THIS IS A REQUEST, NOT A PAYOUT. No money moves and nothing is reserved: the operation opens at status requested and a person decides it in the dashboard. That is the maker-checker separation, with the API key as the requester and an account owner as the decider. There is deliberately no cancellation — a pending request holds nothing, so it is rejected by the decider rather than withdrawn by the requester.

ⓘ The balance check made here is INDICATIVE. You see an aggregate balance; the funds live in pockets per (platform, country) and the decider chooses which to debit. The check that counts is the ledger's no-overdraft rule, at settlement time.

⚠️ Pricing is CLOSED BY DEFAULT: with no withdrawal fee schedule configured for that asset, the request is refused (409). A free withdrawal is a zero line entered on purpose, never an absence.

Parameters

Name	In	Required	Description
Idempotency-Key	header	no	An idempotency key specific to THIS operation.

Request body

Field	Type	Required	Description
asset_id	integer	yes
amount_minor	string	yes	GROSS amount in minor units; fees come out of it, they are not added to it.
description	string	no	Your note, read by the person who decides.
destination	object	no	Where you want the funds. Free text: a person reads it, no rail parses it.
destination.phone	string	no
destination.iban	string	no
destination.bank	string	no

Responses

• 200 — Idempotent replay — the request already existed
• 201 — Request recorded
• 401 — API key missing or rejected (Error)
• 403 — The key does not carry the required scope, or the account is not active (Error)
• 409 — No withdrawal fee schedule configured for that asset (Error)
• 422 — Amount lower than the fee, or insufficient available balance (Error)
• 429 — The key's request budget is exhausted (300/min) — honour Retry-After (Error)

GET /v1/payout-requests/{id}

Retrieve a withdrawal request

ⓘ An operation that is not a withdrawal answers 404 on this path even if it belongs to you: without that check, a confused identifier would return a status belonging to another lifecycle.

Parameters

Name	In	Required	Description
id	path	yes	The request's identifier or reference.

Responses

• 200 — OK (object)
• 401 — API key missing or rejected (Error)
• 403 — The key does not carry the required scope, or the account is not active (Error)
• 404 — No withdrawal request with that identifier (Error)
• 429 — The key's request budget is exhausted (300/min) — honour Retry-After (Error)

Schemas

The shapes the operations above return.

Error

Field	Type	Description
error	object
error.code	string
error.message	string