# 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="../informational/fetch-currency-definitions"><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](https://docs.thedex.cloud/introduction/confirmations-and-limits), 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="../informational/fetch-status-definitions"><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="../informational/fetch-status-definitions"><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>