# 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_fiat` constraint * Returns a full execution plan **Important** * No funds are locked * No transactions are sent * The result is informational only [**Documentation**](/payments/creating-a-payout/estimate.md) #### 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 [**Documentation**](/payments/creating-a-payout/execute.md) #### Recommended Flow 1. Call **Estimate PayOut** to validate cost and feasibility 2. Review the returned plan and fees 3. 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs-processing.crypto-chief.com/payments/creating-a-payout.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.