Guides
  1. Documentation

Payouts and Money Movement

How funds leave a Weenx workspace — queued crypto payouts with operator-gated execution, fee model and whitelist, invoice refunds and reversals, internal transfers, auto-convert, and settlement configuration.

This guide covers every way value leaves a workspace balance: crypto payouts to an external address, invoice refunds and reversals back to a payer, and internal transfers between your own workspace environments. It also covers auto-convert and settlement configuration, which shape how received funds are held and moved.

The queue-and-execute model

The Integration API can queue money-out requests; it cannot execute them on its own. Payout, refund, and reversal creation over an API key records the request and runs its safety checks, but approval and on-chain sending remain operator-gated in the Weenx console.

This is deliberate. A leaked or over-privileged API key can create a payout request, but it cannot approve and broadcast one — so it cannot drain a workspace. Your integration should treat a created payout as pending an operator, follow it to completion through the webhook lifecycle, and reconcile the final state through the read endpoints.

Payouts

The destination whitelist

A payout can only target an address on your payout whitelist. The destination is checked against the whitelist at create time, so an off-whitelist address fails immediately with 403 rather than sitting in a pending state an operator later rejects. Manage the whitelist with:

  • GET /v1/payout-whitelist — list entries (includeInactive optional)
  • POST /v1/payout-whitelist — add or update an entry (address required; optional currencyNetworkId, destinationTag, label, notes, isActive)
  • POST /v1/payout-whitelist/{id}/activate and /deactivate — toggle an entry

Estimate the fee

curl --request GET \
  --url 'https://api.weenx.com/v1/payouts/fee-estimate?currencyNetworkId=1001&amount=25' \
  --header 'X-Api-Key: YOUR_WORKSPACE_API_KEY'

GET /v1/payouts/fee-estimate returns a tiered pre-operation network-fee estimate for an asset, so you can show the expected fee before creating the payout. currencyNetworkId is required; amount and destinationAddress are optional and sharpen the estimate.

Create a payout

curl --request POST \
  --url https://api.weenx.com/v1/payouts \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: YOUR_WORKSPACE_API_KEY' \
  --data '{
    "currencyNetworkId": 1001,
    "amount": 25.00,
    "destinationAddress": "TXk...destination",
    "feeChargingMode": "SenderPaysAll",
    "feeSpeedTier": 1,
    "idempotencyKey": "payout-order-1234"
  }'

The request body carries:

  • currencyNetworkId — required, positive
  • amount — required, positive
  • destinationAddress — required, must be whitelisted
  • destinationTag — optional, for networks that use a memo/tag
  • externalUserId — optional, ties the payout to one of your customers
  • feeChargingMode — optional, defaults to SenderPaysAll
  • feeSpeedTier — optional confirmation-speed tier: 0 (Slow), 1 (Normal), 2 (Fast); omit for the policy default
  • idempotencyKey — optional; a retry with the same key returns the original payout instead of creating a second
  • correlationId, metadataJson — optional passthrough for your own reconciliation

The response is the payout model, which reports both the requested amount and the fee breakdown once resolved:

  • id, status, currencyNetworkId, requestedAmount, amount, destination, destinationTag
  • feeChargingMode
  • networkFee — the on-chain network fee
  • platformFeeAmount — the Weenx payout fee, when applicable
  • totalDebitAmount — the total debited from the workspace balance
  • netAmountToDestination — what the destination receives
  • txHash, failureReason (nullable), and lifecycle timestamps (createdAt, approvedAt, sentAt, completedAt)

Fee-charging modes

feeChargingMode decides who bears the network fee:

  • SenderPaysAll (default) — the workspace pays the full network fee on top of the amount; the destination receives the full amount.
  • Split — the fee is split between sender and recipient.
  • RecipientPaysNetworkFee — the network fee is deducted from the amount sent, so the destination receives amount minus the network fee.

Payout lifecycle

After creation, follow the payout through its webhooks: PayoutSent (broadcast, carries txHash), PayoutConfirming (gaining confirmations), and PayoutCompleted (final). A payout that does not complete surfaces as PayoutFailed, PayoutCancelled, or PayoutRejected. Batch payouts emit the corresponding PayoutBatch* events. Read the current state at any time with GET /v1/payouts/{payoutRequestId} or list with GET /v1/payouts. Cancel a still-pending payout with POST /v1/payouts/{payoutRequestId}/cancel.

Refunds and reversals

Refunds and reversals are invoice-scoped: you operate them under /v1/invoices/{invoiceId}/..., and they reuse the invoice scopes (invoices:read to read or quote, invoices:write to queue). Like payouts, creating one only queues the request; approval and execution stay operator-gated.

  • Refund — return value to a payer. Quote first with POST /v1/invoices/{invoiceId}/refunds/quote, then queue with POST /v1/invoices/{invoiceId}/refunds. The body carries requestedAmount and, depending on your flow, an incomingPaymentId, a destinationAddress and destinationTag, an optional networkFeeAmount, and a reason. Read history with GET /v1/invoices/{invoiceId}/refunds.
  • Reversal — unwind a payment/accounting entry. Quote with POST /v1/invoices/{invoiceId}/reversals/quote, queue with POST /v1/invoices/{invoiceId}/reversals. A reversal takes a mode — AccountingOnly (ledger only) or OperationalRollback (ledger plus the operational effect) — and an optional refundRequestId or incomingPaymentId target. Read history with GET /v1/invoices/{invoiceId}/reversals.

Always call the /quote endpoint first to see the computed amounts and fees before you queue the operation.

Internal transfers

POST /v1/transfers moves balance between two of your own workspace environments as a ledger-only operation — no on-chain transaction. The sender is always the key's workspace; you supply the recipient:

curl --request POST \
  --url https://api.weenx.com/v1/transfers \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: YOUR_WORKSPACE_API_KEY' \
  --data '{
    "toWorkspaceEnvironmentId": "3f8c1e2a-0000-0000-0000-000000000000",
    "currencyNetworkId": 1001,
    "amount": 100.00,
    "idempotencyKey": "transfer-run-2026-08-14"
  }'

idempotencyKey is required in the body — a retry with the same key returns the original transfer rather than moving funds twice. The response reports amount, feeAmount, netAmount, status, and the direction (outgoing on the sender's side). List with GET /v1/transfers, optionally filtered by direction (Any, Outgoing, Incoming).

The settlement fee, and how it is charged

Your plan's settlement fee — Starter 1.0%, Growth 0.7%, Enterprise 0.5% — is deducted from your proceeds when an invoice is paid, not billed as a separate per-transaction charge. When an invoice settles, Weenx computes the fee on the confirmed amount, records it, and credits the net to your workspace balance. The fee never exceeds the amount paid. Because it is taken at settlement, the balance you draw payouts from is already net of the platform fee. See Terms and Enterprise Custody for the plan tiers.

Auto-convert

Auto-convert rules swap a received asset into a target asset automatically — for example, convert any incoming volatile asset into a stablecoin on receipt. Writes require the plan's autoConvert capability and the autoconvert:write scope.

  • GET /v1/auto-convert/rules — list rules (includeInactive optional)
  • POST /v1/auto-convert/rules — create (omit id) or update (with id) a rule; a rule names a fromCurrencyNetworkId, a toCurrencyNetworkId, and optional bounds (minFromAmount, maxFromAmount), a maxSlippageBps, a priority, and a triggerForPaidInvoices flag
  • DELETE /v1/auto-convert/rules/{id} — remove a rule

Settlement configuration

Settlement configuration governs how settled funds are held and routed. It has three surfaces, and the on-chain surfaces are plan-gated:

  • Threshold policies (customSettlementSchedules capability) — GET/POST /v1/settlement/policies manage USD hot-float threshold policies; POST /v1/settlement/policies/apply applies them (defaults to a dry run unless dryRun:false).
  • On-chain hot/cold configuration (dedicatedWallets capability) — POST /v1/settlement/config sets the on-chain hot and cold wallet targets and per-token thresholds; POST /v1/settlement/config/preview-split returns a view-only preview of how a given amount would split between hot and cold, without moving anything.
  • Coin acceptance — PUT /v1/settlement/coin-acceptance/policy sets per-asset acceptance and an optional swap-to-stable receipt mode; GET /v1/settlement/coin-acceptance and GET /v1/settlement/coin-acceptance/effective/{currencyNetworkId} read the configured and effective policy.

The on-chain hot/cold model, and how it becomes non-custodial for Enterprise workspaces, is described in Terms and Enterprise Custody.

Updated 6 days ago

Did this page help you?