> For the complete documentation index, see [llms.txt](https://docs.thedex.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thedex.cloud/documentation/invoices/create-static-wallet.md).

# Create static wallet

The system supports creating static wallets in two modes:

* **Monetary mode** — creates a wallet for one cryptocurrency.
* **Blockchain mode** — creates a wallet for a blockchain network. It supports all enabled currencies on that network.

<mark style="color:green;">`POST`</mark> `https://app.thedex.cloud/api/v1/wallets/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 (**&#x4D;onetar&#x79;**)**

```json
{
    "clientId": "String",
    "monetary": "String",
    "merchantId": "String",
    "fiatCurrency": "String", //optional
    "successUrl": "String", // optional
    "failureUrl": "String", // optional
    "callbackUrl": "String" // optional
}
```

**Request Body (Blockchain)**

```json
{
    "clientId": "String",
    "blockchain": "String",
    "merchantId": "String",
    "fiatCurrecy": "String", //optional
    "successUrl": "String", // optional
    "failureUrl": "String", // optional
    "callbackUrl": "String" // optional
}
```

**Request JSON attributes**

| Name                                                    | Type   | Description                                                                                                                                                                                                                                                                                                   |
| ------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| monetary / blockchain<mark style="color:red;">\*</mark> | String | Specify either a monetary or a blockchain to create a wallet                                                                                                                                                                                                                                                  |
| merchantId<mark style="color:red;">\*</mark>            | String | You can find it on page 'Merchants' in your account                                                                                                                                                                                                                                                           |
| clientId<mark style="color:red;">\*</mark>              | String | An arbitrary identifier for the client                                                                                                                                                                                                                                                                        |
| fiatCurrency                                            | String | <p><strong>Default = USD</strong></p><p>Reach out all available fiat currencies by endpoint: <a href="https://docs.thedex.cloud/documentation/informational/fetch-currency-definitions"><code>/api/v1/info/currencies</code></a></p><p>Primary Used for recalculation of <code>paid\_amount\_fiat</code>.</p> |
| successUrl                                              | String | Custom successUrl for an invoice, that can be differ from merchant settings                                                                                                                                                                                                                                   |
| failureUrl                                              | String | Custom failureUrl for an invoice, that can be differ from merchant settings                                                                                                                                                                                                                                   |
| callbackUrl                                             | String | Custom callback url for receiving events about created invoice on wallet                                                                                                                                                                                                                                      |

**Response Body**

{% tabs %}
{% tab title="200 created wallet" %}

```json
{
    "walletId": "String",
    "monetary": "String",    // Returned if created in Monetary mode
    "blockchain": "String",  // Returned if created in Blockchain-based mode
    "clientId": "String",
    "fiatCurrency": "String",
    "successUrl": "String",
    "failureUrl": "String",
    "callbackUrl": "String",
    "address": "String",
    "minAmount": "String",
    "isActive": "Boolean",
    "payUrl": "String",
    "qrBase64": "String"
}
```

{% endtab %}

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

```json
{
    "error": "Bad Request",
    "message": "Bad Request",
    "status": 400,
    "timestamp": "2026-01-01 00:00:00"
}
```

Missing wallet identifier error: when neither 'monetary' nor 'blockchain' is specified.

```json
{
    "error": "Bad Request",
    "message": "Either 'monetary' or 'blockchain' must be provided. ",
    "status": 400,
    "timestamp": "2026-01-01 00:00:00"
}
```

{% endtab %}

{% tab title="422" %}
Specific field validation error.

```json
{
    "error": "Unprocessable Entity",
    "status": 422,
    "timestamp": "2026-01-01 00:00:00",
    "message": "An active wallet with monetary USDT_TRON, merchant ID `merchantId`, and client ID `clientId` already exists."
}
```

```json
{
    "error": "Unprocessable Entity",
    "status": 422,
    "timestamp": "2026-01-01 00:00:00",
    "message": "`payCurrency` is not active"
}
```

{% endtab %}

{% tab title="401" %}
When `merchantId` in request not equal to API key merchant id

```json
{
    "error": "Unauthorized",
    "status": 401,
    "timestamp": "2026-01-20 04:24:58",
    "message": "Request is not authorized: The requested merchant is not allowed to work with this API key"
}
```

{% endtab %}

{% tab title="500" %}
Blockchain or server side problem.

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

{% endtab %}
{% endtabs %}

**Response JSON attributes**

<table data-header-hidden><thead><tr><th width="427.3333333333333"></th><th width="150"></th><th></th></tr></thead><tbody><tr><td><code>"walletId"</code></td><td><code>String</code></td><td>Unique identifier of the created wallet</td></tr><tr><td><code>"monetary"</code></td><td><code>String</code></td><td>Cryptocurrency of the created wallet. Returned only if the wallet was created in Monetary mode</td></tr><tr><td><code>"blockchain"</code></td><td><code>String</code></td><td>Blockchain network of the created wallet. Returned only if the wallet was created in Blockchain-based mode</td></tr><tr><td><code>"clientId"</code></td><td><code>String</code></td><td>Arbitrary identifier of the client</td></tr><tr><td><code>"fiatCurrency"</code></td><td><code>String</code></td><td>Wallet currency used for <code>paid_amount_fiat</code></td></tr><tr><td><code>"successUrl"</code></td><td><code>String</code></td><td>Success url to redirect customer after successful payment</td></tr><tr><td><code>"failureUrl"</code></td><td><code>String</code></td><td>Failure url to redirect customer after failed payment</td></tr><tr><td><code>"callbackUrl"</code></td><td><code>String</code></td><td>Callback url to receive webhook about created invoices after successful / failed deposit of wallet</td></tr><tr><td><code>"address"</code></td><td><code>String</code></td><td>Generated crypto address for accepting payments</td></tr><tr><td><code>"minAmount"</code></td><td><code>String</code></td><td>Minimum amount required to accept a payment</td></tr><tr><td><code>"isActive"</code></td><td><code>Boolean</code></td><td>Indicates whether the wallet is active.</td></tr><tr><td><code>"payUrl"</code></td><td><code>String</code></td><td>Pay url</td></tr><tr><td><code>"qrBase64"</code></td><td><code>String</code></td><td>A Base64-encoded PNG image of a QR code that encodes the wallet address for payment</td></tr></tbody></table>

**Request curl**

```powershell
curl --location --request POST 'https://app.thedex.cloud/api/v1/wallets/create' \
--header 'X-EX-APIKEY: <string>' \
--header 'X-EX-PAYLOAD: <string>' \
--header 'X-EX-SIGNATURE: <string>' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data '{
    "blockchain": "String",
    "merchantId": "String",
    "fiatCurrency": "String",
    "clientId": "String",
    "successUrl": "String",
    "failureUrl": "String",
    "callbackUrl": "String"
}'
```

**Example Curl**

```powershell
curl --location --request POST 'https://app.thedex.cloud/api/v1/wallets/create' \
--header 'X-EX-APIKEY: test_api_key_123456' \
--header 'X-EX-PAYLOAD: eyJtb25ldGFyeSI6IkJUSDIiLCJtZXJjaGFudElkIjoiTVJDSEFOVDEyMyIsImNsaWVudElkIjoiQ0xJRU5UMTIzIiwic3VjY2Vzc1VybCI6Imh0dHBzOi8vdGVzdC5zdWNjZXNzIiwiZmFpbHVyZVVybCI6Imh0dHBzOi8vdGVzdC5mYWlsdXJlIiwiY2FsbGJhY2tVcmwiOiJodHRwczovL3Rlc3QuY2FsbGJhY2sifQ==' \
--header 'X-EX-SIGNATURE: dummy_signature_abc123' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data '{
    "blockchain": "BITCOIN",
    "merchantId": "MERCHANT123",
    "clientId": "CLIENT123",
    "fiatCurrency": "USD",
    "successUrl": "https://test.success",
    "failureUrl": "https://test.failure",
    "callbackUrl": "https://test.callback"
}'

```