# Create payout

<mark style="color:green;">`POST`</mark> `https://app.thedex.cloud/api/v1/payouts/create`

#### Headers

| Name                                             | Type   | Description                        |
| ------------------------------------------------ | ------ | ---------------------------------- |
| X-EX-APIKEY<mark style="color:red;">\*</mark>    | String | Your API key                       |
| X-EX-PAYLOAD<mark style="color:red;">\*</mark>   | String | Body to base64                     |
| X-EX-SIGNATURE<mark style="color:red;">\*</mark> | String | Encrypted body with the secret key |

#### Request Body

```json
{
    "amountInPayCurrency": "Number",
    "payCurrency": "String",
    "address": "String",
    "memo": "Number",         // optional 
    "description": "String",  // optional 
    "callbackUrl": "String"   // optional 
}
```

**Request JSON attributes**

<table><thead><tr><th>Name</th><th width="192">Type</th><th>Description</th></tr></thead><tbody><tr><td>payCurrency<mark style="color:red;">*</mark></td><td>String</td><td>Reach out accessed values to define attribute by link: <a href="/pages/T8Adh6BIVE4Ma5SN3zSc"><code>/api/v1/info/currencies</code></a><br>attribute <code>"payCurrencies"</code></td></tr><tr><td>amountInPayCurrency<mark style="color:red;">*</mark></td><td>BigDecimal</td><td>Amount in cryptocurrency that will be transferred to the address. Please ensure the value respects the precision limits for each currency and blockchain (see <a href="#amount-precision-limits"><code>Precision Limits</code></a><br>for details).</td></tr><tr><td>address<mark style="color:red;">*</mark></td><td>String</td><td>Address of  crypto wallet</td></tr><tr><td>memo</td><td>Integer</td><td>An additional TON or Ripple specific field to define the intended recipient or destination.</td></tr><tr><td>description</td><td>String</td><td><code>max size = 300</code></td></tr><tr><td>callbackUrl</td><td>String</td><td>Custom callbackUrl for a payout, that can be differ from user settings</td></tr></tbody></table>

**Response body**

{% tabs %}
{% tab title="200 payout" %}

```json
{
   "id": "String",
   "status": "Integer",
   "statusName": "String",
   "fiatCurrency": "String",
   "fiatAmount": "String",
   "payCurrency": "String",
   "address": "String",
   "memo": "Integer",
   "createDate":"String",
   "modifiedDate":"String",
   "transactionId":"String",
   "withdrawalAmount":"String",
   "transferAmount":"String",
   "blockchainFee":"String",
   "payoutCommissionPercentage":"String",
   "isApiCalled":"Boolean",
   "description":"String",
   "merchantId":"String",
   "callbackUrl":"String"
}
```

{% endtab %}

{% tab title="400" %}
General validation error: missing or malformed parameters.

```json
{
    "error": "Bad Request",
    "status": 400,
    "timestamp": "2026-01-01 00:00:00",
    "message": "amountInPayCurrency: must not be null. "
}
```

{% endtab %}

{% tab title="422" %}
Field-level validation error: if amountInPayCurrency exceeds allowed decimal precision for the given currency.

```json
{
    "errors": {
        "amountInPayCurrency": "Max decimal scale for payCurrency `payout currency` is 6"
    },
    "status": 6
}
```

Insufficient funds to perform payout.

```json
{
    "errors": {
        "balance": "Not enough balance to create payout with amount `payout amount`. Available balance is `available amount` `payout currency`"
    },
    "status": 6
}
```

Invalid or incorrectly formatted address.

```json
{
    "errors": {
        "address": "The wallet address is invalid"
    },
    "status": 6
}
```

Transaction exceeds daily limits.

```json
{
    "errors": {
        "limit": "The daily limit has been exceeded."
    },
    "status": 6
}
```

Specific field validation error. ([Minimal limits](/introduction/confirmations-and-limits.md), etc)

```json
{
    "error": "Unprocessable Entity",
    "status": 422,
    "timestamp": "2026-01-01 00:00:00",
    "message": "Withdrawal amount `payout amount` is below the minimum limit of `minimal limit` `payout currency`."
}
```

Blockchain related errors.

```json
{
    "error": "Internal Server Error",
    "status": 422,
    "timestamp": "2026-01-01 00:00:00",
    "message": "Cannot create payout"
}
```

{% endtab %}

{% tab title="403" %}

In case of not existing parameters, incorrect headers, etc..

```json
Empty response
```

Similar for not whitelisted address in merchant settings

```json
{
    "error": "Forbidden",
    "status": 403,
    "timestamp": "2026-01-01 00:00:00",
    "message": "Unauthorized access: IP address not in whitelist"
}
```

{% endtab %}

{% tab title="401" %}
In case of incorrect signature, api key or payload header

```json
{
    "error": "Unauthorized",
    "status": 401,
    "timestamp": "2026-01-01 00:00:00",
    "message": "Request is not authorized"
}
```

{% endtab %}
{% endtabs %}

**Response JSON attributes:**

<table data-header-hidden><thead><tr><th width="264.3333333333333"></th><th width="149"></th><th></th></tr></thead><tbody><tr><td><code>"id"</code></td><td><code>String</code></td><td>Payout id</td></tr><tr><td><code>"status"</code></td><td><code>BigDecimal</code></td><td>each out all accessed values by link: <a href="/pages/z3ihQbPDAepeTxdumQ0z"><code>/api/v1/info/statuses</code></a></td></tr><tr><td><code>"statusName"</code></td><td><code>String</code></td><td>reach out all accessed values by link: <a href="/pages/z3ihQbPDAepeTxdumQ0z"><code>/api/v1/info/statuses</code></a></td></tr><tr><td><code>"payCurrency"</code></td><td><code>String</code></td><td>Cryptocurrency</td></tr><tr><td><code>"address"</code></td><td><code>String</code></td><td>Address is used to widthrawal</td></tr><tr><td><code>"memo"</code></td><td><code>Integer</code></td><td>Additional destination info</td></tr><tr><td><code>"createDate"</code></td><td><code>String</code></td><td>Creation date</td></tr><tr><td><code>"modifiedDate"</code></td><td><code>String</code></td><td>Modification date</td></tr><tr><td><code>"transactionId"</code></td><td><code>String</code></td><td>Could be ignored for this API.</td></tr><tr><td><code>"withdrawalAmount"</code></td><td><code>String</code></td><td>Withdrawal amount</td></tr><tr><td><code>"transferAmount"</code></td><td><code>String</code></td><td>Transfer amount</td></tr><tr><td><code>"blockchainFee"</code></td><td><code>String</code></td><td>Blockchain fee</td></tr><tr><td><code>"payoutCommissionPercentage"</code></td><td><code>String</code></td><td>Payout commission in percentage</td></tr><tr><td><code>"isApiCalled"</code></td><td><code>Boolean</code></td><td>Always true for this API</td></tr><tr><td><code>"fiatAmount"</code></td><td><code>String</code></td><td>Fiat amount of payout</td></tr><tr><td><code>"description"</code></td><td><code>String</code></td><td>Description</td></tr><tr><td><code>"merchantId"</code></td><td><code>String</code></td><td>Merchant id</td></tr><tr><td><code>"fiatCurrency"</code></td><td><code>String</code></td><td>Fiat currency of payout</td></tr></tbody></table>

**Request curl**

```powershell
curl --location --request POST 'https://app.thedex.cloud/api/v1/payouts/create' \
--header 'X-EX-APIKEY: <string>' \
--header 'X-EX-PAYLOAD: <string>' \
--header 'X-EX-SIGNATURE: <string>' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data '{
  "address": "<string>",
  "amountInPayCurrency": "<number>",
  "description": "<string>",
  "payCurrency": "<string>",
  "memo": "<Number>",
  "callbackUrl": "<String>"
}'
```

**Example Curl**

```powershell
curl --location --request POST 'https://app.thedex.cloud/api/v1/payouts/create' \
--header 'X-EX-APIKEY: test_api_key_123456' \
--header 'X-EX-PAYLOAD: eyJhZGRyZXNzIjogIjB4QWJjMTIzIiwgImFtb3VudEluUGF5Q3VycmVuY3kiOiAxMCwgImRlc2NyaXB0aW9uIjogIlRlc3QgcGF5b3V0IiwgInBheUN1cnJlbmN5IjogIkVUSCIsICJtZW1vIjogIjEyMzQ1IiwgImNhbGxiYWNrVXJsIjogImh0dHBzOi8vY2FsbGJhY2suZXhhbXBsZS5jb20ifQ==' \
--header 'X-EX-SIGNATURE: dummy_signature_abc123' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data-raw '{
  "address": "0xAbc123",
  "amountInPayCurrency": 10,
  "description": "Test payout",
  "payCurrency": "ETH",
  "memo": "12345",
  "callbackUrl": "https://callback.example.com"
}'
```

<details>

<summary><strong>Amount Precision Limits</strong></summary>

For payout operations, the `amountInPayCurrency` field is subject to precision (decimal scale) limits that depend on the selected blockchain and cryptocurrency.

Each cryptocurrency supports a **maximum number of decimal places**. Values with a scale greater than the allowed limit will be rejected.

Below is the list of supported currencies and their maximum allowed decimal scale:

#### **Precision by Currency and Blockchain** <a href="#amount-precision-limit" id="amount-precision-limit"></a>

<table><thead><tr><th width="274.20001220703125">Currency</th><th>Precision</th></tr></thead><tbody><tr><td><strong>Bitcoin Network</strong></td><td></td></tr><tr><td>   BTC_BITCOIN</td><td>8</td></tr><tr><td><strong>Ethereum Network</strong></td><td></td></tr><tr><td>   ETH_ETHEREUM</td><td>18</td></tr><tr><td>   USDT_ETHEREUM</td><td>6</td></tr><tr><td>   USDC_ETHEREUM</td><td>6</td></tr><tr><td>   DAI_ETHEREUM</td><td>18</td></tr><tr><td><strong>Litecoin Network</strong></td><td></td></tr><tr><td>   LTC_LITECOIN</td><td>8</td></tr><tr><td><strong>Tron Network</strong></td><td></td></tr><tr><td>   TRX_TRON</td><td>6</td></tr><tr><td>   USDT_TRON</td><td>6</td></tr><tr><td><strong>Ripple Network</strong></td><td></td></tr><tr><td>   XRP_RIPPLE</td><td>6</td></tr><tr><td><strong>The Open Network</strong></td><td></td></tr><tr><td>   TON_TON</td><td>9</td></tr><tr><td>   USDT_TON</td><td>6</td></tr><tr><td><strong>Doge Network</strong></td><td></td></tr><tr><td>   DOGE_DOGECOIN</td><td>8</td></tr><tr><td><strong>Polygon Network</strong></td><td></td></tr><tr><td>   POL_POLYGON</td><td>18</td></tr><tr><td>   USDT_POLYGON</td><td>6</td></tr><tr><td>   USDC_POLYGON</td><td>6</td></tr><tr><td><strong>Arbitrum Network</strong></td><td></td></tr><tr><td>   ARB_ARBITRUM</td><td>18</td></tr><tr><td>   ETH_ARBITRUM</td><td>18</td></tr><tr><td>   USDT_ARBITRUM</td><td>6</td></tr><tr><td>   USDC_ARBITRUM</td><td>6</td></tr><tr><td><strong>Optimism Network</strong></td><td></td></tr><tr><td>   OP_OPTIMISM</td><td>18</td></tr><tr><td>   ETH_OPTIMISM</td><td>18</td></tr><tr><td>   USDT_OPTIMISM</td><td>6</td></tr><tr><td>   USDC_OPTIMISM</td><td>6</td></tr><tr><td><strong>BSC Network</strong></td><td></td></tr><tr><td>   BNB_BSC</td><td>18</td></tr><tr><td>   USDT_BSC</td><td>18</td></tr><tr><td>   USDC_BSC</td><td>18</td></tr><tr><td><strong>Solana Network</strong></td><td></td></tr><tr><td>   SOL_SOLANA</td><td>9</td></tr><tr><td>   USDT_SOLANA</td><td>6</td></tr><tr><td>   USDC_SOLANA</td><td>6</td></tr><tr><td><strong>Base Network</strong></td><td></td></tr><tr><td>   ETH_BASE</td><td>18</td></tr><tr><td>   USDC_BASE</td><td>6</td></tr></tbody></table>

**Notes**

* The precision limit applies **only to the number of decimal places**, not to the total amount.
* If the provided `amountInPayCurrency` exceeds the allowed decimal scale for the selected currency and blockchain, the request will fail validation.
* Clients should round or truncate values to the supported precision before submitting payout requests.

</details>


---

# 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.thedex.cloud/documentation/payouts/create-a-payout.md?ask=<question>
```

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.