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

# Crypto Wallet

> Cryptocurrency wallet addresses, supported coins, and deposit/withdrawal transactions

# Crypto Wallet APIs (v2)

Manage cryptocurrency wallet addresses for funding your merchant account. Supports USDT on TRC20 and BEP20 chains.

<Info>
  **Base URL:** `POST /api/v2.1/fincard/virtual/wallet/v2/...`
</Info>

***

## Coin List

Query all supported coins and blockchain networks.

```bash theme={null}
POST /api/v2.1/fincard/virtual/wallet/v2/coins
```

**Request:** `{}` (empty body)

**Response `data[]`:**

| Field                | Type    | Description                                       |
| -------------------- | ------- | ------------------------------------------------- |
| `coinKey`            | String  | Unique coin identifier (e.g. `USDT_TRC20`)        |
| `chain`              | String  | Blockchain network (e.g. `TRC20`, `BEP20`)        |
| `coinFullName`       | String  | Full name (e.g. `Tether`)                         |
| `coinName`           | String  | Short name (e.g. `USDT`)                          |
| `showCoinDecimal`    | Integer | Display decimal places                            |
| `coinDecimal`        | Integer | Transaction decimal places                        |
| `blockChainShowName` | String  | Display name (e.g. `Tron (TRC20)`)                |
| `browser`            | String  | Blockchain explorer URL template for addresses    |
| `txRefUrl`           | String  | Blockchain explorer URL template for transactions |
| `contractAddress`    | String  | Smart contract address                            |
| `enableDeposit`      | Boolean | Deposits enabled                                  |
| `enableWithdraw`     | Boolean | Withdrawals enabled                               |
| `confirmations`      | Integer | Required block confirmations                      |
| `enabled`            | Boolean | Coin is active                                    |

<Accordion title="Example Response">
  ```json theme={null}
  {
    "success": true,
    "code": 200,
    "msg": "SUCCESS",
    "data": [
      {
        "coinKey": "USDT_TRC20",
        "chain": "TRC20",
        "coinFullName": "Tether",
        "coinName": "USDT",
        "showCoinDecimal": 6,
        "coinDecimal": 6,
        "blockChainShowName": "Tron (TRC20)",
        "browser": "https://tronscan.org/#/address/{address}",
        "txRefUrl": "https://tronscan.org/#/transaction/{txHash}",
        "contractAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
        "enableDeposit": true,
        "enableWithdraw": true,
        "confirmations": 38,
        "enabled": true
      }
    ]
  }
  ```
</Accordion>

***

## Create Wallet Address

Generate a new deposit address for a specific coin and chain.

```bash theme={null}
POST /api/v2.1/fincard/virtual/wallet/v2/create
```

**Request:**

| Field     | Type   | Required | Description                                        |
| --------- | ------ | -------- | -------------------------------------------------- |
| `coinKey` | String | Yes      | Coin key from Coin List (must have `enabled=true`) |

**Response `data`:**

| Field      | Type   | Description               |
| ---------- | ------ | ------------------------- |
| `coinKey`  | String | Coin key                  |
| `chain`    | String | Blockchain network        |
| `coinName` | String | Coin name                 |
| `address`  | String | Generated deposit address |

<Accordion title="Example Response">
  ```json theme={null}
  {
    "success": true,
    "code": 200,
    "msg": "SUCCESS",
    "data": {
      "coinKey": "USDT_BEP20",
      "chain": "BEP20",
      "coinName": "USDT",
      "address": "0xAAac5f0d8133424d86D5Ef3f170E0420e561125f"
    }
  }
  ```
</Accordion>

<Note>
  You can also generate wallet addresses from the dashboard. Each `coinKey` has one address per merchant.
</Note>

***

## Wallet Address List

Query all generated wallet deposit addresses.

```bash theme={null}
POST /api/v2.1/fincard/virtual/wallet/v2/addressList
```

**Request:** `{}` (empty body)

**Response `data[]`:** Same shape as Create Wallet Address response.

***

## Wallet Transaction History

Query crypto deposit and withdrawal transaction history.

```bash theme={null}
POST /api/v2.1/fincard/virtual/wallet/v2/transaction
```

**Request:**

| Field                | Type   | Required | Description                                        |
| -------------------- | ------ | -------- | -------------------------------------------------- |
| `pageNum`            | Long   | Yes      | Page number (default 1)                            |
| `pageSize`           | Long   | Yes      | Page size (default 10, max 100)                    |
| `coinKey`            | String | No       | Filter by coin key                                 |
| `coinName`           | String | No       | Filter by coin name                                |
| `txHash`             | String | No       | Filter by on-chain tx hash                         |
| `sourceAddress`      | String | No       | Filter by source address                           |
| `destinationAddress` | String | No       | Filter by destination address                      |
| `orderNo`            | String | No       | Filter by platform tx ID                           |
| `type`               | String | No       | `DEPOSIT` or `WITHDRAW`                            |
| `status`             | String | No       | `wait_process` / `processing` / `success` / `fail` |
| `startTime`          | Long   | No       | Start time (ms). Max 90-day range                  |
| `endTime`            | Long   | No       | End time (ms)                                      |

**Response `data`:** `{ total, records[] }`

| Field                | Type       | Description                                        |
| -------------------- | ---------- | -------------------------------------------------- |
| `orderNo`            | String     | Platform transaction ID                            |
| `coinKey`            | String     | Coin key                                           |
| `coinName`           | String     | Coin name                                          |
| `block`              | Integer    | Block height                                       |
| `sourceAddress`      | String     | Source address                                     |
| `destinationAddress` | String     | Destination address                                |
| `txHash`             | String     | On-chain transaction hash                          |
| `txAmount`           | BigDecimal | On-chain amount                                    |
| `transactionTime`    | Long       | Chain transaction time (ms)                        |
| `confirmTime`        | Long       | Chain confirmation time (ms)                       |
| `feeRate`            | BigDecimal | Platform fee rate (`1` = 1%)                       |
| `fee`                | BigDecimal | Platform fee amount                                |
| `fixedFee`           | BigDecimal | Platform fixed fee                                 |
| `receivedAmount`     | BigDecimal | Net received amount                                |
| `receivedCurrency`   | String     | Received currency (e.g. `USD`)                     |
| `type`               | String     | `DEPOSIT` or `WITHDRAW`                            |
| `status`             | String     | `wait_process` / `processing` / `success` / `fail` |
| `message`            | String     | Remark                                             |
| `createTime`         | Long       | Order create time (ms)                             |
| `updateTime`         | Long       | Order update time (ms)                             |

<Accordion title="Example Response">
  ```json theme={null}
  {
    "success": true,
    "code": 200,
    "msg": "SUCCESS",
    "data": {
      "total": 5,
      "records": [
        {
          "orderNo": "CND2031235349498847232",
          "coinKey": "USDT_TRC20",
          "block": 80817428,
          "sourceAddress": "TK4ykR48cQQoyFcZ5N4xZCbsBaHcg6n3gJ",
          "destinationAddress": "TReJ9YfvmpPTXuq3kzQneXDco1fQprqZ9v",
          "txHash": "1c19a9635e8c11c6b7be0e402017e81e64e9f7f1ad1a10e1ea1304955745b434",
          "coinName": "USDT",
          "txAmount": "9",
          "feeRate": "1.5",
          "fee": "0.135",
          "fixedFee": "0",
          "receivedAmount": "8.86",
          "receivedCurrency": "USD",
          "type": "DEPOSIT",
          "status": "success",
          "createTime": 1773119220000,
          "updateTime": 1773119220000
        }
      ]
    }
  }
  ```
</Accordion>

<Warning>
  If `status=fail`, it is **not necessarily final**. The platform may manually resolve failed deposits to `success`.
</Warning>