# Create static wallet

<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**

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

**Request JSON attributes**

| Name                                         | Type   | Description                                                                                                                                                                                                                                                                                                   |
| -------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| monetary<mark style="color:red;">\*</mark>   | String | Wallet monetary (cryptocurrency)                                                                                                                                                                                                                                                                              |
| 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",
    "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",
    "status": 400,
    "timestamp": "2026-01-01 00:00:00",
    "message": "merchantId: Merchant id does not valid. "
}
```

{% 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</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 '{
    "monetary": "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 '{
    "monetary": "BTC_BITCOIN",
    "merchantId": "MERCHANT123",
    "clientId": "CLIENT123",
    "fiatCurrency": "USD",
    "successUrl": "https://test.success",
    "failureUrl": "https://test.failure",
    "callbackUrl": "https://test.callback"
}'

```


---

# 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/invoices/create-static-wallet.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.