> 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/fetch-static-wallet.md).

# Fetch static wallet

Returns a static wallet address by walletId or by a combination of clientId + merchantId + blockchain

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

### Search modes

A wallet can be fetched in one of two ways:

1. **By `walletId`** – returns the wallet with the given ID **regardless of its status** (active or inactive).
2. **By a combination of fields** (`clientId` + `merchantId` + `blockchain`) – returns **only the active wallet**.

{% hint style="warning" %}
When searching by a combination of fields, **only the active wallet is returned**. Several inactive wallets may share the same combination, so they cannot be retrieved unambiguously this way. To fetch an inactive wallet, use `walletId`.
{% endhint %}

Either `walletId` or a combination of fields must be provided.

### Headers

| Name             | Type   | Description                        |
| ---------------- | ------ | ---------------------------------- |
| X-EX-APIKEY\*    | String | Your API key                       |
| X-EX-PAYLOAD\*   | String | Body to base64                     |
| X-EX-SIGNATURE\* | String | Encrypted body with the secret key |

### Request Body

**Option 1: by `walletId`**

```json
{
    "walletId": "String"
}
```

**Option 2: by a combination of fields (Blockchain-based mode)**

```json
{
    "clientId": "String",
    "merchantId": "String",
    "blockchain": "String"
}
```

### Request JSON attributes

| Name       | Type   | Description                                                                                                                                        |
| ---------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| walletId   | String | The unique identifier of the requested wallet. Required if the combination of fields is not used. The wallet is returned regardless of its status. |
| clientId   | String | Arbitrary identifier of the client. Required when searching by a combination of fields.                                                            |
| merchantId | String | Identifier of the merchant. Required when searching by a combination of fields.                                                                    |
| blockchain | String | Blockchain network of the wallet. Required when searching by a combination of fields.                                                              |

### Response Body

**200 response**

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

### Response JSON attributes

| Name             | Type    | Description                                                                                                                                                                                 |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"walletId"`     | String  | Unique identifier of the wallet                                                                                                                                                             |
| `"blockchain"`   | String  | Blockchain network of the wallet. Returned only if the wallet was created in Blockchain-based mode                                                                                          |
| `"clientId"`     | String  | Arbitrary identifier of the client                                                                                                                                                          |
| `"successUrl"`   | String  | Success url to redirect customer after successful payment                                                                                                                                   |
| `"failureUrl"`   | String  | Failure url to redirect customer after failed payment                                                                                                                                       |
| `"callbackUrl"`  | String  | Callback url for payment notifications                                                                                                                                                      |
| `"address"`      | String  | Wallet address                                                                                                                                                                              |
| `"minAmount"`    | String  | Minimum payment amount                                                                                                                                                                      |
| `"isActive"`     | Boolean | Indicates whether the wallet is active. Always `true` when the wallet is fetched by a combination of fields.                                                                                |
| `"payUrl"`       | String  | Pay url                                                                                                                                                                                     |
| `"qrBase64"`     | String  | A Base64-encoded PNG image of a QR code that encodes the wallet address for payment                                                                                                         |
| `"fiatCurrency"` | String  | <p><strong>Default = USD</strong><br>Reach out all available fiat currencies by endpoint: /api/v1/info/currencies<br>Primary used for recalculation of <code>paid\_amount\_fiat</code>.</p> |

### Errors

| HTTP code | Description                                                                                                                                 |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| 400       | Invalid `walletId` format, or required fields are missing: either `walletId` or a combination of `clientId`, `merchantId` and `blockchain.` |
| 401       | The `merchantId` does not belong to the authorized merchant.                                                                                |
| 422       | Wallet not found.                                                                                                                           |

### Request Curl (by walletId)

```bash
curl --location --request POST 'https://app.thedex.cloud/api/v1/wallets/one' \
--header 'X-EX-APIKEY: <string>' \
--header 'X-EX-PAYLOAD: <string>' \
--header 'X-EX-SIGNATURE: <string>' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data '{
    "walletId": "String"
}'
```

### Request Curl (by combination of fields)

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

### Example Curl (by walletId)

```bash
curl --location --request POST 'https://app.thedex.cloud/api/v1/wallets/one' \
--header 'X-EX-APIKEY: test_api_key_123456' \
--header 'X-EX-PAYLOAD: eyJ3YWxsZXRJZCI6ICJXQUxMRVRfMTIzIn0=' \
--header 'X-EX-SIGNATURE: dummy_signature_abc123' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data-raw '{
    "walletId": "WALLET_123"
}'
```

### Example Curl (by combination of fields)

```bash
curl --location --request POST 'https://app.thedex.cloud/api/v1/wallets/one' \
--header 'X-EX-APIKEY: test_api_key_123456' \
--header 'X-EX-PAYLOAD: eyJjbGllbnRJZCI6ICJDTElFTlRfMTIzIiwgIm1lcmNoYW50SWQiOiAiTUVSQ0hBTlRfMTIzIiwgImJsb2NrY2hhaW4iOiAiVFJPTiJ9' \
--header 'X-EX-SIGNATURE: dummy_signature_abc123' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data-raw '{
    "clientId": "CLIENT_123",
    "merchantId": "MERCHANT_123",
    "blockchain": "TRON"
}'
```
