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

# Stable Currency Wallet

> Manage stable currency wallets, check balances, and move funds across supported networks.

## Overview

The Stable Currency Wallet API lets users create a custodial wallet, receive deposits, check token balances across supported networks, and initiate withdrawals. Each user gets exactly one wallet tied to their account, with a dedicated address on each supported chain.

**Supported networks:** `polygon`, `arbitrum`, `base`, `tron`, `solana`

**Supported tokens:** `USDT`, `USDC`

***

## Create Wallet

<Note>
  Each user can only have one wallet. Calling this endpoint when a wallet already exists returns a `409` error.
</Note>

**Endpoint**

```text theme={null}
POST /v1/stable-currency/wallet
```

On success, a wallet is provisioned with an address on each supported chain, and the addresses are registered for deposit monitoring automatically.

**Response**

```json theme={null}
{
    "success": true,
    "data": {
        "id": "6a60cb58318a85d918e36c8c",
        "userId": "6914b8de530486c362268f77",
        "type": "BUSINESS",
        "address": "0x9488bb0a83a8c1f312c46aa655d30ec56afdc298",
        "tronAddress": "TZ9yZ4eXa7J3vsWSa2N3hpcVka1EC6KXBc",
        "solanaAddress": "CmMGUEDoPRyYiP3kpaogDseH4s5m8XAfBJ7jx7UB3nyU",
        "createdAt": "2026-07-22T13:53:28.472Z",
        "updatedAt": "2026-07-22T13:53:28.472Z"
    },
    "message": "Wallet created successfully"
}
```

* `address` is used for EVM-compatible networks (`polygon`, `arbitrum`, `base`).
* `tronAddress` is used for the `tron` network.
* `solanaAddress` is used for the `solana` network.

***

## Get Balance

**Endpoint**

```text theme={null}
GET /v1/stable-currency/balance
```

Returns token balances for all network/token pairs, plus a `totalBalance` summary across all networks for each token. When `available` is `false`, that token is not yet supported on that network — treat the balance as `0` and do not display it to users.

**Response**

```json theme={null}
{
    "success": true,
    "data": {
        "address": "0x1568e8dde63809608c38b07ec8acb99de9cdcfce",
        "tronAddress": "TT3gMBES5wGnngdUowiKngruq72eUWEHui",
        "solanaAddress": "9xkSc4LXAeaEELk6wnMyJqcka4Z29hPB9RGeHsWFZeky",
        "totalBalance": {
            "USDT": "398",
            "USDC": "500"
        },
        "balances": [
            {
                "network": "polygon",
                "token": "USDT",
                "balance": "0",
                "available": false
            },
            {
                "network": "polygon",
                "token": "USDC",
                "balance": "0",
                "available": false
            },
            {
                "network": "arbitrum",
                "token": "USDT",
                "balance": "0",
                "available": false
            },
            {
                "network": "arbitrum",
                "token": "USDC",
                "balance": "0",
                "available": false
            },
            {
                "network": "base",
                "token": "USDT",
                "balance": "0",
                "available": true
            },
            {
                "network": "base",
                "token": "USDC",
                "balance": "0",
                "available": true
            },
            {
                "network": "tron",
                "token": "USDT",
                "balance": "0",
                "available": true
            },
            {
                "network": "tron",
                "token": "USDC",
                "balance": "500",
                "available": true
            },
            {
                "network": "solana",
                "token": "USDT",
                "balance": "398",
                "available": true
            },
            {
                "network": "solana",
                "token": "USDC",
                "balance": "0",
                "available": true
            }
        ]
    },
    "message": "Balance fetched successfully"
}
```

<Tip>
  Filter to `available: true` entries before rendering balances in your UI. Use `totalBalance` when you just need an aggregate figure per token.
</Tip>

***

## Withdraw

**Endpoint**

```text theme={null}
POST /v1/stable-currency/withdraw
```

Initiates an on-chain token transfer from the user's wallet to an external address. The transaction is recorded immediately with a `PROCESSING` status and confirmed asynchronously via webhook.

<Warning>
  A fee is deducted from every withdrawal. The `fee` amount is returned in the response and is charged in addition to the withdrawal `amount`.
</Warning>

**Request Body**

| Field       | Type     | Required | Description                                                            |
| ----------- | -------- | -------- | ---------------------------------------------------------------------- |
| `token`     | `string` | ✓        | Token to send. One of `USDT`, `USDC`                                   |
| `network`   | `string` | ✓        | Network to use. One of `polygon`, `arbitrum`, `base`, `tron`, `solana` |
| `amount`    | `string` | ✓        | Amount as a decimal string, e.g. `"50"`                                |
| `toAddress` | `string` | ✓        | Destination address, in the format expected by the chosen network      |

**Example Request**

```json theme={null}
{
  "token": "USDC",
  "network": "base",
  "amount": "100.00",
  "toAddress": "0xRecipientAddressHere"
}
```

**Response**

```json theme={null}
{
  "success": true,
  "data": {
    "id": "64f1a2b3c4d9e6f7a8b9c0d2",
    "walletId": "64f1a1c3c4d5e6f7a8b9c0d1",
    "txHash": "0xabc123...",
    "userId": "64e0f1a2b3c4d5e6f7a8b9c0",
    "token": "USDC",
    "network": "base",
    "amount": "100",
    "fee": "2",
    "type": "WITHDRAWAL",
    "status": "PENDING",
    "from": "0x6f7a5457784e52eacc1fcf14bcdc070caaaa70a0",
    "to": "0xrecipientaddresshere",
    "blockNumber": null,
    "createdAt": "2024-01-15T10:35:00.000Z",
    "updatedAt": "2024-01-15T10:35:00.000Z"
  },
  "message": "Withdrawal initiated successfully"
}
```

<Warning>
  The API validates that sufficient balance exists to cover both the `amount` and the `fee` before broadcasting. Attempting to withdraw more than the available balance returns an error.
</Warning>

***

## Transaction History

**Endpoint**

```text theme={null}
GET /v1/stable-currency/transactions
```

Returns a paginated list of all stable currency transactions (deposits and withdrawals) for the authenticated user.

**Query Parameters**

| Parameter   | Type     | Required | Description                                                        |
| ----------- | -------- | -------- | ------------------------------------------------------------------ |
| `page`      | `number` | —        | Page number. Defaults to `1`                                       |
| `limit`     | `number` | —        | Results per page. Defaults to `10`                                 |
| `tokenType` | `string` | —        | Filter by token: `USDT` or `USDC`                                  |
| `network`   | `string` | —        | Filter by network: `polygon`, `arbitrum`, `base`, `tron`, `solana` |
| `type`      | `string` | —        | Filter by type: `DEPOSIT` or `WITHDRAWAL`                          |

**Response**

```json theme={null}
{
  "success": true,
  "data": {
    "data": [ /* array of transaction objects */ ],
    "pageCount": 5,
    "pageId": 1,
    "limit": 10,
    "totalCount": 47
  },
  "message": "Crypto transactions fetched successfully"
}
```

***

## Get Single Transaction

**Endpoint**

```text theme={null}
GET /v1/stable-currency/transactions/:transactionId
```

Fetches a single transaction by its ID. The transaction must belong to the authenticated user.

**Path Parameters**

| Parameter       | Type     | Required | Description                         |
| --------------- | -------- | -------- | ----------------------------------- |
| `transactionId` | `string` | ✓        | MongoDB ObjectId of the transaction |

**Response**

```json theme={null}
{
  "success": true,
  "data": {
    "id": "64f1a2b3c4d560f7a8b9c0d2",
    "walletId": "64f1a2bh74d5e6f7a8b9c0d1",
    "txHash": "0xabc123...",
    "userId": "64e0f1a2b3c9d5e6f7a8b9c0",
    "token": "USDC",
    "network": "base",
    "amount": "100",
    "fee": "2",
    "type": "WITHDRAWAL",
    "status": "CONFIRMED",
    "from": "0x6f7a54577e9e52ebce1fcf14bcdc070caaaa70a0",
    "to": "0xrecipientaddresshere",
    "blockNumber": "12345678",
    "createdAt": "2024-01-15T10:35:00.000Z",
    "updatedAt": "2024-01-15T10:36:00.000Z"
  },
  "message": "Crypto transaction fetched successfully"
}
```

<Note>
  `fee` is only present on `WITHDRAWAL` transactions.
</Note>

***

## Dev: Fund Wallet

<Warning>
  This endpoint is only available in non-production environments. Calling it in production returns a `400` error.
</Warning>

**Endpoint**

```text theme={null}
POST /v1/stable-currency/fund-dev-wallet
```

Seeds a wallet with test tokens from the treasury wallet. Useful for simulating deposits with a real on-chain transaction. Capped at `1000` per request.

**Request Body**

| Field     | Type     | Required | Description                     |
| --------- | -------- | -------- | ------------------------------- |
| `token`   | `string` | ✓        | Token to fund: `USDT` or `USDC` |
| `network` | `string` | ✓        | Network to fund on              |
| `amount`  | `string` | ✓        | Amount to fund, max `"1000"`    |

**Example Request**

```json theme={null}
{
  "token": "USDT",
  "network": "solana",
  "amount": "1000"
}
```

**Response**

```json theme={null}
{
    "success": true,
    "data": {
        "txHash": "66a2UxE3CFTbwAsjiaxAvYJxJMYohLbyj52VFvYiL51Ksn9Js1PpSmHPqRczvBRHHHztPqfbtc7GSSPW2JhuPpm1"
    },
    "message": "Dev funded 1000 USDT on solana successfully. Wallet will be credited after on-chain confirmation."
}
```

***

## Transaction Statuses

| Status       | Description                                           |
| ------------ | ----------------------------------------------------- |
| `PROCESSING` | Transaction initiated and being processed             |
| `PENDING`    | Transaction broadcast, awaiting on-chain confirmation |
| `CONFIRMED`  | Transaction confirmed on-chain                        |