Skip to main content
POST
Request a payout
Requires scope: manage:pay-outs — see Required scopes. Requests a PULL pay-out against an ACTIVE route: Venly sends crypto from the account wallet to the provider’s deposit address using the up-front permit, and the provider pays fiat to the beneficiary. The route already fixes the beneficiary, lane, asset and fiat currency, so you supply only the route, the crypto amount, and an idempotency key.
A 201 is not a success signal. Permit allowance and account-wallet balance are deliberately not pre-checked. If either is insufficient, this call still returns 201 and the asynchronous send fails terminally — the pay-out moves to FAILED with a failureReason.Track the real outcome by polling Get a payout or by registering a webhook.
Status advances REQUESTED → SENDING → PROVIDER_PROCESSING → COMPLETED. Note that a fiat leg can still bounce after completion, moving to RETURNED. PUSH pay-outs are not created here — see Pay-outs. Idempotency: the key must be unique per company across all idempotent endpoints. Reuse with a different body, or after the original failed, returns 422; reuse while the original is in flight returns 409.

Errors

The codes this endpoint can return, in addition to the standard errors. Branch on code, never the message.

Authorizations

Path Parameters

accountId
string<uuid>
required

Unique account identifier

Body

application/json

Requests a PULL pay-out. The route fixes the beneficiary, lane, asset and fiat currency, so there is no fiat target, no provider field and no funding-mode field.

payoutRouteId
string<uuid>
required

The selected payout route. Must belong to this account and be ACTIVE.

cryptoAmount
number
required

Crypto amount to send to the provider's deposit address. Must be greater than zero, with at most 20 integer digits and 18 fractional digits.

Example:

100

idempotencyKey
string
required

Client-supplied idempotency key. Must be unique per company across all idempotent endpoints.

Maximum string length: 255
Example:

"payout-2026-07-14-0001"

Response

Payout created (REQUESTED)

success
boolean

Indicates whether the request was successful

result
object

Full pay-out shape, returned on creation and by the detail read. Never carries the idempotency key, permit material, internal wallet ids, managed transaction ids or raw provider data.