URL: /paas/fincard-virtual/wallet

---
title: 'Crypto Wallet'
description: '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
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
{
  "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
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
{
  "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
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
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
{
  "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>