> ## 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.

# Accounts

> Merchant account management, balances, ledger transactions, and fund transfers

# Account APIs

Manage merchant accounts (WALLET and MARGIN types), query balances, view ledger transactions, and execute fund transfers.

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

***

## Assets (Account Info)

Returns all merchant accounts with balances.

```bash theme={null}
POST /api/v2.1/fincard/virtual/account/info
```

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

**Response `data[]`:**

| Field              | Type       | Description                |
| ------------------ | ---------- | -------------------------- |
| `accountId`        | String     | Account ID                 |
| `accountName`      | String     | Account name               |
| `accountType`      | String     | `WALLET` or `MARGIN`       |
| `currency`         | String     | Currency (e.g. `USD`)      |
| `totalBalance`     | BigDecimal | Total balance              |
| `availableBalance` | BigDecimal | Available balance          |
| `frozenBalance`    | BigDecimal | Frozen balance             |
| `digital`          | Long       | Decimal places for display |

<Accordion title="Example Response">
  ```json theme={null}
  {
    "success": true,
    "code": 200,
    "msg": "Success",
    "data": [
      {
        "accountId": "19847563867367666",
        "accountName": "wallet9023",
        "accountType": "WALLET",
        "currency": "USD",
        "totalBalance": 100,
        "availableBalance": 100,
        "frozenBalance": 0,
        "digital": 2
      }
    ]
  }
  ```
</Accordion>

***

## Account List

Paginated list of accounts with optional type filter.

```bash theme={null}
POST /api/v2.1/fincard/virtual/account/list
```

**Request:**

| Field       | Type    | Required | Description                    |
| ----------- | ------- | -------- | ------------------------------ |
| `accountId` | Long    | No       | Filter by account ID           |
| `type`      | String  | No       | `WALLET` or `MARGIN`           |
| `pageNum`   | Integer | Yes      | Page number (default 1)        |
| `pageSize`  | Integer | Yes      | Page size (default 10, max 10) |

**Response `data`:** `{ total: Long, records: [...] }` — records same shape as Account Info.

***

## Single Account Query

Query a single account by ID.

```bash theme={null}
POST /api/v2.1/fincard/virtual/account/single/query
```

**Request:**

| Field       | Type | Required | Description |
| ----------- | ---- | -------- | ----------- |
| `accountId` | Long | Yes      | Account ID  |

**Response `data[]`:** Same shape as Account Info.

***

## Ledger Transactions

Query financial transaction history for an account.

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

**Request:**

| Field       | Type    | Required | Description                       |
| ----------- | ------- | -------- | --------------------------------- |
| `pageNum`   | Integer | Yes      | Page number (default 1)           |
| `pageSize`  | Integer | Yes      | Page size (default 10, max 100)   |
| `orderNo`   | String  | No       | Filter by transaction ID          |
| `accountId` | Long    | No       | Filter by account                 |
| `bizType`   | String  | No       | Transaction type (see below)      |
| `startTime` | Long    | No       | Start time (ms). Max 30-day range |
| `endTime`   | Long    | No       | End time (ms)                     |

**Transaction Types (`bizType`):**

| Value                         | Description                          |
| ----------------------------- | ------------------------------------ |
| `chain_deposit`               | Wallet chain deposit                 |
| `chain_withdraw`              | Wallet chain withdrawal              |
| `card_purchase`               | Card purchase (create fee + deposit) |
| `card_deposit`                | Card deposit                         |
| `card_withdraw`               | Card withdraw                        |
| `card_cancel`                 | Card cancel                          |
| `card_auth_fee_patch`         | Card authorization fee               |
| `card_auth_cross_board_patch` | Card cross-border fee                |
| `gt_transfer`                 | Global transfer                      |
| `gt_transfer_refund`          | Global transfer refund               |
| `fixed`                       | Adjustment                           |
| `card_overdraft_statement`    | Card overdraft bill                  |

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

| Field           | Type       | Description                |
| --------------- | ---------- | -------------------------- |
| `txId`          | Long       | Internal transaction ID    |
| `accountId`     | String     | Account ID                 |
| `amount`        | BigDecimal | Amount                     |
| `beforeBalance` | BigDecimal | Balance before transaction |
| `afterBalance`  | BigDecimal | Balance after transaction  |
| `orderNo`       | String     | Transaction ID             |
| `bizType`       | String     | Transaction type           |
| `direction`     | String     | `IN` or `OUT`              |
| `remark`        | String     | Remark                     |
| `createTime`    | Long       | Millisecond timestamp      |

<Accordion title="Example Response">
  ```json theme={null}
  {
    "success": true,
    "code": 200,
    "msg": "SUCCESS",
    "data": {
      "total": 34,
      "records": [
        {
          "txId": 517581,
          "accountId": "1979009257233215490",
          "currency": "USD",
          "amount": "4.08",
          "beforeBalance": "99327.04375",
          "afterBalance": "99322.96375",
          "orderNo": "C2C_UZS_2025122307584616966",
          "bizType": "gt_transfer",
          "direction": "OUT",
          "remark": "Global transfer",
          "createTime": 1766480100874
        }
      ]
    }
  }
  ```
</Accordion>

***

## Create Shared Account

Create a new MARGIN account for shared card mode.

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

**Request:**

| Field         | Type   | Required | Description  |
| ------------- | ------ | -------- | ------------ |
| `accountName` | String | Yes      | Account name |

**Response `data[]`:** The created account (same shape as Account Info).

***

## Fund Transfer

Transfer or collect funds between accounts.

```bash theme={null}
POST /api/v2.1/fincard/virtual/account/transfer
```

**Request:**

| Field             | Type       | Required | Description                      |
| ----------------- | ---------- | -------- | -------------------------------- |
| `type`            | String     | Yes      | `TRANSFER` or `COLLECTION`       |
| `merchantOrderNo` | String     | Yes      | Client transaction ID `[20..40]` |
| `amount`          | BigDecimal | Yes      | Amount                           |
| `payerAccountId`  | Long       | Yes      | Payer account (typically WALLET) |
| `payeeAccountId`  | Long       | Yes      | Payee account (typically MARGIN) |
| `remark`          | String     | No       | Remark                           |

**Response `data`:** `true` (boolean)

<Note>
  Use this to fund a MARGIN account before creating shared (BUDGET\_CARD) cards linked to it.
</Note>

***

## Wallet Deposit (Deprecated)

<Warning>
  **Deprecated.** Use the [Wallet v2 APIs](/baas/api/reference/fincard-virtual/wallet) instead.
</Warning>

Create a wallet deposit order. Returns deposit address and amount.

```bash theme={null}
POST /api/v2.1/fincard/virtual/account/walletDeposit
```

**Request:**

| Field    | Type       | Required | Description                  |
| -------- | ---------- | -------- | ---------------------------- |
| `chain`  | String     | No       | `TRC20` (default) or `BEP20` |
| `amount` | BigDecimal | Yes      | Deposit amount               |

**Response `data`:**

| Field                    | Type       | Description                             |
| ------------------------ | ---------- | --------------------------------------- |
| `orderNo`                | String     | Transaction ID                          |
| `userInputDepositAmount` | BigDecimal | Input amount                            |
| `actualDepositAmount`    | BigDecimal | Actual amount (with decimal adjustment) |
| `currency`               | String     | `USDT`                                  |
| `chain`                  | String     | Network chain                           |
| `toAddress`              | String     | Wallet deposit address                  |
| `createTime`             | Long       | Order time (ms)                         |
| `expireSecond`           | Long       | Validity period (seconds)               |

***

## Wallet Deposit Transactions (Deprecated)

<Warning>
  **Deprecated.** Use the [Wallet v2 Transaction History](/baas/api/reference/fincard-virtual/wallet) instead.
</Warning>

```bash theme={null}
POST /api/v2.1/fincard/virtual/account/walletDepositTransaction
```

Paginated query for wallet deposit transactions. Response: `{ total, records[] }`.