Creating a PayOut
PayOut: Withdrawals & Settlements
The PayOut API enables automated withdrawals from your Master Wallets to external addresses (Cold Wallets). Unlike incoming payments, payouts require active liquidity management. The platform handles gas estimation, automatic refuels, and complex routing strategies to ensure successful delivery.
1. Overview & Mechanics
1.1 Wallet Roles
Payouts are strictly executed from Master Wallets.
Transit Wallets: Never used for payouts.
Master Wallets: Act as the source. They must hold the target token (e.g., USDT) and the Native Coin (e.g., ETH/TRX) for network fees.
1.2 Gas Protection & Auto-Refuel
Token transfers (e.g. USDT) require network fees paid in the native coin of the blockchain. Before executing any payout, the system performs a pre-flight check to estimate the required gas and verify availability.
If the Master Wallet does not have enough native balance, the platform may automatically perform a gas refuel operation. To protect against unexpected costs, the payout is rejected if the total required amount (network fee + refuel) exceeds the configured max_fee_amount_fiat.
Fee Handling Modes
The platform supports multiple fee handling strategies that define how network fees are funded:
client Network fees are paid using the client’s own Master Wallet. If the target wallet lacks native balance, the system attempts to refuel it from the client’s Master Wallet.
service Network fees are paid by the platform. Gas is supplied from the project’s service wallet, and the equivalent amount is deducted from API Credits.
mix A hybrid approach for maximum reliability. The system first attempts the client flow; if it fails (for example, due to insufficient master balance), it automatically falls back to the service flow.
1.3 Liquidity Aggregation (Multi-Source)
If a single wallet cannot cover the requested amount, you can enable Multi-Source Mode.
Logic: The system scans all available Master Wallets.
Plan: It splits the payout into multiple transactions (e.g., 60 USDT from Wallet A + 40 USDT from Wallet B).
Result: The recipient receives the total requested amount in multiple transfers.
1.4 Double-Spend Protection (Locked Funds)
The system tracks "Pending Payouts" in real-time. Even if the blockchain balance hasn't updated yet, funds reserved for queued tasks are subtracted from the available balance. This prevents creating orders that would overdraft your wallets.
2. PayOut Methods
The PayOut flow is split into two explicit steps: Estimate and Execute. This separation allows you to preview costs and feasibility before committing funds on-chain.
2.1 Estimate PayOut
Purpose The Estimate method simulates a payout without creating any blockchain transactions. It allows you to understand fees, routing, and liquidity availability in advance.
What it does
Calculates the required network fee (gas)
Checks native coin balance for gas payment
Plans auto-refuel operations if needed
Evaluates multi-source splitting (if enabled)
Verifies the
max_fee_amount_fiatconstraintReturns a full execution plan
Important
No funds are locked
No transactions are sent
The result is informational only
2.2 Execute PayOut
Purpose The Execute method creates and submits a real payout order based on the validated parameters.
What it does
Locks required funds immediately (pending payout protection)
Executes auto-refuel operations if required
Sends one or multiple on-chain transactions
Tracks execution status until completion or failure
Execution guarantees
Double-spend protection via locked balances
Gas sufficiency ensured before token transfer
Multi-source payouts executed atomically at the planning level
Important
Funds are reserved immediately
Blockchain transactions are created
The operation is irreversible once broadcasted
Recommended Flow
Call Estimate PayOut to validate cost and feasibility
Review the returned plan and fees
Call Execute PayOut using the same parameters to perform the withdrawal
This two-step model provides maximum transparency, safety, and cost control for automated payouts.
Last updated