---
title: "钱包"
description: "本指南介绍如何使用 Fystack API 创建和管理钱包。"
url: https://docs.fystack.io/zh/wallets
last_updated: 2026-11-13
---

> ## Documentation index
> Fetch the complete documentation index at: https://docs.fystack.io/llms.txt
> Use it to discover all available pages before exploring further.

# 钱包

钱包是用于管理数字资产的安全容器。Fystack 提供多种钱包类型以满足不同需求，包括 Hyper wallet 和 MPC（多方计算）钱包。

## 钱包类型

Fystack 支持两种钱包类型：

|  | Hyper | MPC |
| --- | --- | --- |
| 工作原理 | 每个工作区的密钥均从一个主种子派生（HD 派生） | 私钥被拆分为分片分布在各 Mpcium 节点上，从不在同一处组装 |
| 安全性 | 高 | 机构级，门限签名 |
| 创建速度 | 即时，立即返回 `success` | 7-15 秒 |
| 成本 | 较低 | 较高 |
| 恢复 | 从 HD 种子重新生成 | 多方恢复 |
| 适用场景 | 终端用户钱包、消费级应用、大批量生成 | 热钱包、托管、交易所和高价值钱包 |

---

## 创建钱包

**Endpoint:** `POST /wallets`

要创建新钱包，请携带所需参数向 `/wallets` endpoint 发送 POST 请求。

### 参数

- `name` (string, required): 钱包的描述性名称。
- `wallet_type` (enum: standard | mpc | hd_mpc, required): 要创建的钱包类型：
  - `standard`：**Hyper**。从加密的工作区种子进行 HD 派生。单一密钥，高吞吐量。
  - `mpc`：**MPC Cloud**。完全托管的 MPC 签名。每笔交易都由你的策略和审批决定。
  - `hd_mpc`：**Co-signed HD MPC**。添加在你的 HD 主密钥之下，并与你的服务器 Cosigner 共同签名，因此 Fystack 无法单独签名。请先[设置你的 Cosigner](https://docs.fystack.io/cosigner/installation.md)。
- `wallet_purpose` (string, default: general): 钱包的用途。必须是 `general`、`user`、`gas_tank`、`payment` 或 `one_time_use` 之一。如果设置为 `user`，该钱包将不会在门户中显示。
- `gas_sponsorship_enabled` (boolean, default: false): 为该钱包在 EVM、Solana 和 TRON 网络上的代币转账代付 gas，使钱包无需持有原生币。Gas 由工作区的 gas tank 支付，请参阅 [Gas Station](https://docs.fystack.io/zh/product/gas-station.md)。之后也可以在钱包设置中更改此项。
- `sweep_task_id` (string): 要关联到该钱包的现有[归集任务](https://docs.fystack.io/zh/product/automation.md#sweep-tasks)的 UUID。请先创建归集任务，然后从控制台的 Automation 页面复制其 ID。

### 什么是归集任务？自动将资金从新钱包中转出

归集任务会在钱包余额达到设定的美元价值时，自动将资金从该钱包转移到另一个钱包或地址，因此你无需手动归集充值。

为新钱包设置归集任务：

1. 在控制台的 **Automation > Add Sweep Task** 下 **创建归集任务**。请参阅[自动化](https://docs.fystack.io/product/automation.md#sweep-tasks)。
2. 从 Automation 页面 **复制归集任务 ID**。
3. 创建每个钱包时，**将其作为 `sweep_task_id` 传入**。

**归集任务的工作原理**

- **自动监控**：系统持续监控钱包余额
- **阈值触发**：当钱包的美元价值达到任务的最低触发值时，触发归集
- **灵活的目标地址**：资金可以归集到内部钱包，或地址簿中的外部地址

> **Info: 在多个钱包间复用同一个归集任务.** 为所有应归集到同一目标的钱包关联相同的 `sweep_task_id`。之后只需更新这一个任务，就会应用到所有关联的钱包。

> **Warning: 使用 hd_mpc 前请先设置服务器 Cosigner.** `hd_mpc` 钱包派生自一个与服务器 Cosigner 共同签名的 HD-MPC 主密钥。调用此 endpoint 之前，请先[安装并配对服务器 Cosigner](https://docs.fystack.io/zh/cosigner/installation.md)，然后在 [Fystack 控制台](https://app.fystack.io/)的创建钱包弹窗中创建 HD 主密钥。创建钱包时 Cosigner 必须在线。

### 响应

- `success` (boolean): 表示请求是否成功。
- `message` (string): 描述操作结果的消息。
- `code` (integer): 表示结果状态的数字代码（0 表示成功）。
- `data` (object): 包含钱包详细信息。
  - `wallet_id` (string): 新创建钱包的 UUID。
  - `status` (string): 钱包创建过程的当前状态。

**请求：基础钱包** `POST /wallets`

```typescript
import { FystackSDK, Environment } from "@fystack/sdk"

const apiCredentials = {
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET
}

const sdk = new FystackSDK({
  credentials: apiCredentials,
  environment: Environment.Sandbox,
  logger: true
})

await sdk.createWallet({
    name: 'Treasury wallet',
    walletType: WalletType.MPC
})
```

```bash
curl -X POST https://api.fystack.io/api/v1/wallets \
  -H "ACCESS-API-KEY: your_api_key" \
  -H "ACCESS-TIMESTAMP: 1667836889" \
  -H "ACCESS-SIGN: YourBase64EncodedSignature==" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Treasury wallet",
    "wallet_type": "mpc"
  }'
```

**请求：带归集任务** `POST /wallets`

```typescript
import { FystackSDK, Environment } from "@fystack/sdk"

const apiCredentials = {
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET
}

const sdk = new FystackSDK({
  credentials: apiCredentials,
  environment: Environment.Sandbox,
  logger: true
})

await sdk.createWallet({
    name: 'User deposit wallet',
    walletType: WalletType.Standard,
    walletPurpose: WalletPurpose.User,
    sweepTaskId: '987f6543-e21c-43b2-a654-321098765432'
})
```

```bash
curl -X POST https://api.fystack.io/api/v1/wallets \
  -H "ACCESS-API-KEY: your_api_key" \
  -H "ACCESS-TIMESTAMP: 1667836889" \
  -H "ACCESS-SIGN: YourBase64EncodedSignature==" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "User deposit wallet",
    "wallet_type": "standard",
    "wallet_purpose": "user",
    "sweep_task_id": "987f6543-e21c-43b2-a654-321098765432"
  }'
```

```json
{
  "success": true,
  "message": "success",
  "code": 0,
  "data": {
    "wallet_id": "c2b71329-34c9-45aa-89d3-ddde8b15dec5",
    "status": "pending"
  }
}
```

---

## 钱包创建状态

**Endpoint:** `GET /wallets/creation-status/:wallet_id`

钱包的创建过程是异步进行的。初始响应会包含一个 `status` 字段，其值为以下之一：

- `pending`：钱包创建过程已开始，但尚未完成。
- `success`：钱包已成功创建。
- `error`：创建钱包时出错。

> **Warning.** 对于 `standard` 类型的钱包，创建后状态会立即变为 `success`。

> **Info.** 对于 `mpc` 类型的钱包，由于需要在多个参与方之间安全地生成密钥，创建过程可能需要更长时间。

### 响应

- `wallet_id` (string): 正在创建的钱包的 UUID。
- `status` (string): 钱包创建过程的当前状态。可以是 `pending`、`success` 或 `error`。

**请求** `GET /wallets/creation-status/:wallet_id`

```bash
curl -X GET https://api.fystack.io/api/v1/wallets/creation-status/c2b71329-34c9-45aa-89d3-ddde8b15dec5 \
  -H "ACCESS-API-KEY: your_api_key" \
  -H "ACCESS-TIMESTAMP: 1667836889" \
  -H "ACCESS-SIGN: YourBase64EncodedSignature=="
```

```json
{
  "wallet_id": "c2b71329-34c9-45aa-89d3-ddde8b15dec5",
  "status": "pending"
}
```

---

## 列出所有钱包

**Endpoint:** `GET /workspaces/:workspace_id/wallets`

此 endpoint 用于获取工作区中所有钱包的分页列表。

### 参数

- `wallet_type` (string): 按类型筛选钱包。
- `limit` (integer): 限制返回的钱包数量。
- `offset` (integer): 开始返回结果之前要跳过的钱包数量。

**请求** `GET /workspaces/:workspace_id/wallets`

```typescript
import { FystackSDK, Environment } from "@fystack/sdk"

const apiCredentials = {
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET
}

const sdk = new FystackSDK({
  credentials: apiCredentials,
  environment: Environment.Sandbox,
  logger: true
})

const wallets = await sdk.getWallets()
console.log('wallets', wallets)
```

```bash
curl -X GET https://api.fystack.io/api/v1/workspaces/123e4567-e89b-12d3-a456-426614174000/wallets \
  -H "ACCESS-API-KEY: your_api_key" \
  -H "ACCESS-TIMESTAMP: 1667836889" \
  -H "ACCESS-SIGN: YourBase64EncodedSignature=="
```

```json
[
  {
    "id": "7f00773a-abbd-434b-b322-7b4016b3ff4a",
    "name": "MPC wallet",
    "role": "wallet_admin",
    "wallet_type": "mpc",
    "value_usd": "0",
    "top_assets": [],
    "wallet_purpose": "general"
  },
  {
    "id": "8a91b223-4c9f-5ffc-0f1g-235787cfc3f1",
    "name": "Hyper wallet",
    "role": "wallet_admin",
    "wallet_type": "standard",
    "value_usd": "0",
    "top_assets": [],
    "wallet_purpose": "general"
  }
]
```

## 获取充值地址

**Endpoint:** `GET /wallets/:wallet_id/deposit-address`

此 endpoint 返回指定钱包和资产的充值地址。

### 查询参数

- `asset_id` (string): 要获取充值地址的资产的 UUID。
- `address_type` (string): 要生成的区块链地址类型。必须是以下之一：`evm`、`sol`、`tron` 或 `btc`。

### 响应

- `success` (boolean): 表示请求是否成功。
- `data` (object): 包含充值地址详细信息。
  - `asset_id` (string): 资产的 UUID。
  - `address` (string): 用于充值的区块链地址。
  - `qr_code` (string): 充值地址二维码图片的 URL。

> **Info.** 如果省略 `address_type`，Fystack 会尽可能根据所请求的资产选择地址类型。

**请求** `GET /wallets/:wallet_id/deposit-address`

```typescript
import { FystackSDK, Environment } from "@fystack/sdk"

const apiCredentials = {
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET
}

const sdk = new FystackSDK({
  credentials: apiCredentials,
  environment: Environment.Sandbox,
  logger: true
})

const response = await sdk.getDepositAddress(
  "c2b71329-34c9-45aa-89d3-ddde8b15dec5",
  AddressType.Evm
)

// Get Solana deposit address
const response = await sdk.getDepositAddress(
  "c2b71329-34c9-45aa-89d3-ddde8b15dec5",
  AddressType.Solana
)

// Get Tron deposit address
const response = await sdk.getDepositAddress(
  "c2b71329-34c9-45aa-89d3-ddde8b15dec5",
  AddressType.Tron
)
```

```bash
curl -X GET "https://api.fystack.io/api/v1/wallets/c2b71329-34c9-45aa-89d3-ddde8b15dec5/deposit-address?address_type=evm" \
  -H "ACCESS-API-KEY: your_api_key" \
  -H "ACCESS-TIMESTAMP: 1667836889" \
  -H "ACCESS-SIGN: YourBase64EncodedSignature=="
```

```json
{
  "success": true,
  "message": "success",
  "code": 0,
  "data": {
    "address": "0xA793457d84CFD255Ed68295984300C4f799E759F",
    "qr_code": "https://quickchart.io/qr?size=300&margin=2&text=0xA793457d84CFD255Ed68295984300C4f799E759F"
  }
}
```

---

## 获取钱包资产概览

**Endpoint:** `GET /wallets/:wallet_id/overview`

此 endpoint 返回钱包资产及其余额、有效冻结、美元价格和网络详情。可用于展示钱包资产组合。已隐藏的钱包资产和已禁用的网络不包含在内。

### 路径参数

- `wallet_id` (string (uuid)): 钱包的 UUID。

### 查询参数

- `offset` (integer): 要跳过的记录数。必须介于 0 到 100000 之间。
- `limit` (integer): 要返回的最大记录数。必须介于 0 到 1000 之间。省略此参数或将其设为 0 将返回所有匹配记录。
- `is_native_only` (boolean): 设置为 `true` 时仅返回原生资产。
- `search` (string): 按资产名称或符号搜索。最多 100 个字符。
- `sort_by` (string): 按 `balance`、`price_usd` 或 `value_usd` 排序。省略时按名称排序。
- `sort_order` (string): 排序方向：`asc` 或 `desc`。提供 `sort_by` 时默认为 `asc`。
- `min_value_usd` (number): 仅返回美元总价值不低于该金额的资产。必须大于或等于 0。
- `network_ids` (array of strings (uuid)): 按网络 UUID 筛选。重复该查询参数即可包含多个网络。

### 响应

- `success` (boolean): 表示请求是否成功。
- `message` (string): 描述操作结果的消息。
- `code` (integer): 表示结果状态的数字代码（0 表示成功）。
- `data` (array): 匹配的钱包资产。没有匹配的资产时返回空数组。
  - `balance` (string): 资产总余额，以十进制字符串形式返回。
  - `on_hold` (string): 有效冻结所占用的金额，以十进制字符串形式返回。
  - `available_balance` (string): 可用余额：总余额减去有效冻结金额。
  - `price_usd` (string): 资产的美元单价，以十进制字符串形式返回。
  - `value_usd` (string): 总余额乘以美元价格的结果，以十进制字符串形式返回。
  - `asset` (object): 资产详情，包括其 UUID、名称、符号、小数位数和网络 ID。资产字段请参阅[资产](https://docs.fystack.io/zh/assets.md)。
  - `network` (object): 网络详情：`id`、`name`、`chain_id`、`logo_url`，以及 `explorer_tx`（如有）。

**请求** `GET /wallets/:wallet_id/overview`

```bash
curl -X GET "https://api.fystack.io/api/v1/wallets/c2b71329-34c9-45aa-89d3-ddde8b15dec5/overview?sort_by=value_usd&sort_order=desc&limit=20" \
  -H "ACCESS-API-KEY: your_api_key" \
  -H "ACCESS-TIMESTAMP: 1667836889" \
  -H "ACCESS-SIGN: YourBase64EncodedSignature=="
```

```json
{
  "success": true,
  "message": "success",
  "code": 0,
  "data": [
    {
      "balance": "125",
      "on_hold": "25",
      "available_balance": "100",
      "asset": {
        "id": "bf130274-e80c-43f3-aac3-c7dbfcbd74cd",
        "name": "USDC (Binance-Peg USD Coin)",
        "symbol": "USDC",
        "decimals": 18,
        "logo_url": "https://bscscan.com/token/images/centre-usdc_28.png",
        "address": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
        "asset_type": "erc20",
        "is_native": false,
        "address_type": "evm",
        "network_id": "c03b242f-5091-499c-86c5-78dbc47ed719",
        "price_usd": "1"
      },
      "price_usd": "1",
      "value_usd": "125",
      "network": {
        "id": "c03b242f-5091-499c-86c5-78dbc47ed719",
        "name": "BNB Mainnet",
        "chain_id": 56,
        "logo_url": "https://s2.coinmarketcap.com/static/img/coins/64x64/1839.png",
        "explorer_tx": "https://bscscan.com/tx/%s"
      }
    }
  ]
}
```

---

## 获取钱包余额

**Endpoint:** `GET /wallets/:wallet_id/balances`

此 endpoint 返回钱包资产余额的扁平列表，附带资产和网络标识符。可用于按精确符号、资产 ID 或网络查询余额。已隐藏的钱包资产和已禁用的网络不包含在内。

### 路径参数

- `wallet_id` (string (uuid)): 钱包的 UUID。

### 查询参数

- `offset` (integer): 要跳过的记录数。必须介于 0 到 100000 之间。
- `limit` (integer): 要返回的最大记录数。必须介于 0 到 1000 之间。省略此参数或将其设为 0 将返回所有匹配记录。
- `symbol` (array of strings): 按精确的资产符号筛选，例如 `USDC`。匹配不区分大小写。每个符号必须包含 1 到 20 个字母或数字。
- `asset_id` (array of strings (uuid)): 按资产 UUID 筛选。
- `network_id` (array of strings (uuid)): 按网络 UUID 筛选。
- `network_code` (array of strings): 按精确的网络代码筛选，例如 `BSC_MAINNET`。匹配不区分大小写。每个代码必须包含 1 到 50 个字符。请使用[网络](https://docs.fystack.io/zh/networks.md)中的 `internal_code`。

> **Info.** 重复某个查询参数即可提供多个值，例如 `symbol=USDC&symbol=USDT`。同一筛选条件中的多个值只需匹配其一即可。不同的筛选条件会组合生效，因此符号和网络筛选条件必须同时匹配。

### 响应

- `success` (boolean): 表示请求是否成功。
- `message` (string): 描述操作结果的消息。
- `code` (integer): 表示结果状态的数字代码（0 表示成功）。
- `data` (array): 匹配的钱包资产。没有匹配的资产时返回空数组。
  - `wallet_id` (string (uuid)): 钱包的 UUID。
  - `asset_id` (string (uuid)): 资产的 UUID。
  - `symbol` (string): 资产符号。
  - `asset_name` (string): 资产名称。
  - `asset_logo` (string): 资产图标的 URL。
  - `network_id` (string (uuid)): 网络的 UUID。
  - `network_code` (string): 网络的内部代码。
  - `network_name` (string): 网络名称。
  - `network_logo` (string): 网络图标的 URL。
  - `balance` (string): 资产总余额，以十进制字符串形式返回。
  - `on_hold` (string): 有效冻结所占用的金额，以十进制字符串形式返回。
  - `available_balance` (string): 可用余额：总余额减去有效冻结金额。
  - `price_usd` (string): 资产的美元单价，以十进制字符串形式返回。
  - `value_usd` (string): 总余额乘以美元价格的结果，以十进制字符串形式返回。

**请求** `GET /wallets/:wallet_id/balances`

```bash
curl -X GET "https://api.fystack.io/api/v1/wallets/c2b71329-34c9-45aa-89d3-ddde8b15dec5/balances?symbol=USDC&symbol=USDT&network_code=BSC_MAINNET&limit=20" \
  -H "ACCESS-API-KEY: your_api_key" \
  -H "ACCESS-TIMESTAMP: 1667836889" \
  -H "ACCESS-SIGN: YourBase64EncodedSignature=="
```

```json
{
  "success": true,
  "message": "success",
  "code": 0,
  "data": [
    {
      "wallet_id": "c2b71329-34c9-45aa-89d3-ddde8b15dec5",
      "asset_id": "bf130274-e80c-43f3-aac3-c7dbfcbd74cd",
      "symbol": "USDC",
      "asset_name": "USDC (Binance-Peg USD Coin)",
      "asset_logo": "https://bscscan.com/token/images/centre-usdc_28.png",
      "network_id": "c03b242f-5091-499c-86c5-78dbc47ed719",
      "network_code": "BSC_MAINNET",
      "network_name": "BNB Mainnet",
      "network_logo": "https://s2.coinmarketcap.com/static/img/coins/64x64/1839.png",
      "balance": "125",
      "on_hold": "25",
      "available_balance": "100",
      "price_usd": "1",
      "value_usd": "125"
    }
  ]
}
```

---

## 按资产 ID 获取钱包余额

**Endpoint:** `GET /wallets/:wallet_id/balance/:asset_id`

此 endpoint 返回钱包中单个资产的总余额。如需获取有效冻结和可用余额，请使用[获取钱包余额](#get-wallet-balances)。

### 路径参数

- `wallet_id` (string (uuid)): 钱包的 UUID。
- `asset_id` (string (uuid)): 资产的 UUID。

### 响应

- `success` (boolean): 表示请求是否成功。
- `message` (string): 描述操作结果的消息。
- `code` (integer): 表示结果状态的数字代码（0 表示成功）。
- `data` (string): 所请求资产的总余额，以十进制字符串形式返回。

**请求** `GET /wallets/:wallet_id/balance/:asset_id`

```bash
curl -X GET "https://api.fystack.io/api/v1/wallets/c2b71329-34c9-45aa-89d3-ddde8b15dec5/balance/bf130274-e80c-43f3-aac3-c7dbfcbd74cd" \
  -H "ACCESS-API-KEY: your_api_key" \
  -H "ACCESS-TIMESTAMP: 1667836889" \
  -H "ACCESS-SIGN: YourBase64EncodedSignature=="
```

```json
{
  "success": true,
  "message": "success",
  "code": 0,
  "data": "125"
}
```