> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thiqwave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Account

> Create a settlement account or stablecoin wallet.

## Endpoint

```
POST https://api.thiqwave.com/v1/accounts
```

## Description

Create a fiat settlement account or a stablecoin wallet. Fiat accounts are corridor-specific and ready to receive funds. Stablecoin wallets can be MPC-managed (Thiqwave provisions a non-custodial wallet) or self-custody (you supply your own address).

<Tip>
  Use the `Idempotency-Key` header when creating accounts to safely retry the request without the risk of creating duplicates.
</Tip>

## Request

### Headers

<ParamField header="X-API-Key" type="string" required>
  Your Thiqwave API key.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

<ParamField header="Idempotency-Key" type="string">
  A unique string (e.g. a UUID) that you generate per request. If you retry a request with the same key, Thiqwave returns the original response instead of creating a duplicate account. Recommended for all account creation requests.
</ParamField>

### Body

<ParamField body="type" type="string" required>
  Account type. One of: `"fiat"` or `"stablecoin"`.
</ParamField>

<ParamField body="currency" type="string" required>
  Currency code. For fiat: `"AED"` (UAE Dirham). For stablecoin: `"USDC"` or `"USDT"`.
</ParamField>

<ParamField body="corridor" type="string" conditional>
  Required for fiat accounts. Corridor code: `"uae"`.
</ParamField>

<ParamField body="network" type="string" conditional>
  Required for stablecoin wallets. Blockchain network: `"ethereum"`, `"avalanche"`, `"arbitrum"`, `"base"`, `"polygon"`, `"tron"`, `"stellar"`, `"solana"`, `"xrpl"`, `"algorand"`, `"sui"`.
</ParamField>

<ParamField body="wallet_mode" type="string" conditional>
  Required for stablecoin wallets. Mode: `"mpc"` (Thiqwave provisions address) or `"self_custody"` (you supply your own wallet address).
</ParamField>

<ParamField body="external_address" type="string" conditional>
  Required if `wallet_mode` is `"self_custody"`. The blockchain address to use for this wallet.
</ParamField>

<ParamField body="label" type="string">
  Friendly name for the account. Optional.
</ParamField>

## Example requests

### Create fiat account (AED in UAE)

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.thiqwave.com/v1/accounts \
    -H "X-API-Key: your-api-key" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
    -d '{
      "type": "fiat",
      "currency": "AED",
      "corridor": "uae",
      "label": "UAE Operations Account"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.thiqwave.com/v1/accounts', {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key',
      'Content-Type': 'application/json',
      'Idempotency-Key': '550e8400-e29b-41d4-a716-446655440000',
    },
    body: JSON.stringify({
      type: 'fiat',
      currency: 'AED',
      corridor: 'uae',
      label: 'UAE Operations Account',
    }),
  });

  const account = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.thiqwave.com/v1/accounts',
      headers={
          'X-API-Key': 'your-api-key',
          'Content-Type': 'application/json',
          'Idempotency-Key': '550e8400-e29b-41d4-a716-446655440000',
      },
      json={
          'type': 'fiat',
          'currency': 'AED',
          'corridor': 'uae',
          'label': 'UAE Operations Account',
      },
  )

  account = response.json()
  ```
</CodeGroup>

### Create MPC stablecoin wallet (USDC on Polygon)

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.thiqwave.com/v1/accounts \
    -H "X-API-Key: your-api-key" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001" \
    -d '{
      "type": "stablecoin",
      "currency": "USDC",
      "network": "polygon",
      "wallet_mode": "mpc",
      "label": "USDC Polygon Treasury"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.thiqwave.com/v1/accounts', {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key',
      'Content-Type': 'application/json',
      'Idempotency-Key': '550e8400-e29b-41d4-a716-446655440001',
    },
    body: JSON.stringify({
      type: 'stablecoin',
      currency: 'USDC',
      network: 'polygon',
      wallet_mode: 'managed',
      label: 'USDC Polygon Treasury',
    }),
  });

  const account = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.thiqwave.com/v1/accounts',
      headers={
          'X-API-Key': 'your-api-key',
          'Content-Type': 'application/json',
          'Idempotency-Key': '550e8400-e29b-41d4-a716-446655440001',
      },
      json={
          'type': 'stablecoin',
          'currency': 'USDC',
          'network': 'polygon',
          'wallet_mode': 'managed',
          'label': 'USDC Polygon Treasury',
      },
  )

  account = response.json()
  ```
</CodeGroup>

## Response

A `201 Created` response returns the newly created account or wallet object.

<ResponseField name="id" type="string">
  The unique account ID. Use this to retrieve the account or reference it in transactions.
</ResponseField>

<ResponseField name="type" type="string">
  The account type: `"fiat"` or `"stablecoin"`.
</ResponseField>

<ResponseField name="status" type="string">
  The current account status: `"active"`, `"frozen"`, or `"closed"`.
</ResponseField>

<ResponseField name="currency" type="string">
  The account currency code.
</ResponseField>

<ResponseField name="corridor" type="string">
  For fiat accounts: the corridor code (`"uae"`).
</ResponseField>

<ResponseField name="network" type="string">
  For stablecoin wallets: the blockchain network.
</ResponseField>

<ResponseField name="wallet_mode" type="string">
  For stablecoin wallets: `"mpc"` or `"self_custody"`.
</ResponseField>

<ResponseField name="address" type="string">
  For managed stablecoin wallets: the blockchain address provisioned by Thiqwave.
</ResponseField>

<ResponseField name="label" type="string">
  Friendly name for the account.
</ResponseField>

<ResponseField name="created_at" type="string">
  The ISO 8601 timestamp of when the account was created.
</ResponseField>

### Example response

```json theme={null}
{
  "id": "acc_01HZ5NM2XDQE8F1G7HKRWS4JV",
  "type": "stablecoin",
  "status": "active",
  "currency": "USDC",
  "network": "polygon",
  "wallet_mode": "mpc",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
  "label": "USDC Polygon Treasury",
  "created_at": "2026-04-08T12:00:00Z"
}
```

## Error responses

| Status | Code                      | Description                                                      |
| ------ | ------------------------- | ---------------------------------------------------------------- |
| `400`  | `VALIDATION_ERROR`        | One or more request fields are invalid or missing.               |
| `401`  | `UNAUTHORIZED`            | Your API key is missing or invalid.                              |
| `409`  | `DUPLICATE_ACCOUNT`       | An account with this configuration already exists.               |
| `422`  | `UNSUPPORTED_COMBINATION` | The currency, network, or corridor combination is not supported. |