钱包

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

钱包类型

Fystack 支持两种钱包类型：

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

创建钱包

POST
/wallets

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

参数

  • Name
    name
    Type
    string
    Required
    required
    Description

    钱包的描述性名称。

  • Name
    wallet_type
    Type
    enum: standard | mpc | hd_mpc
    Required
    required
    Description

    要创建的钱包类型：

    • standard：Hyper。从加密的工作区种子进行 HD 派生。单一密钥，高吞吐量。
    • mpc：MPC Cloud。完全托管的 MPC 签名。每笔交易都由你的策略和审批决定。
    • hd_mpc：Co-signed HD MPC。添加在你的 HD 主密钥之下，并与你的服务器 Cosigner 共同签名，因此 Fystack 无法单独签名。请先设置你的 Cosigner。
  • Name
    wallet_purpose
    Type
    string
    Default
    default:general
    Description

    钱包的用途。必须是 general、user、gas_tank、payment 或 one_time_use 之一。如果设置为 user，该钱包将不会在门户中显示。

  • Name
    gas_sponsorship_enabled
    Type
    boolean
    Default
    default:false
    Description

    为该钱包在 EVM、Solana 和 TRON 网络上的代币转账代付 gas，使钱包无需持有原生币。Gas 由工作区的 gas tank 支付，请参阅 Gas Station。之后也可以在钱包设置中更改此项。

  • Name
    sweep_task_id
    Type
    string
    Description

    要关联到该钱包的现有归集任务的 UUID。请先创建归集任务，然后从控制台的 Automation 页面复制其 ID。

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

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

为新钱包设置归集任务：

  1. 在控制台的 Automation > Add Sweep Task 下 创建归集任务。请参阅自动化。
  2. 从 Automation 页面 复制归集任务 ID。
  3. 创建每个钱包时，将其作为 sweep_task_id 传入。

归集任务的工作原理

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

在多个钱包间复用同一个归集任务

为所有应归集到同一目标的钱包关联相同的 sweep_task_id。之后只需更新这一个任务，就会应用到所有关联的钱包。

使用 hd_mpc 前请先设置服务器 Cosigner

hd_mpc 钱包派生自一个与服务器 Cosigner 共同签名的 HD-MPC 主密钥。调用此 endpoint 之前，请先安装并配对服务器 Cosigner，然后在 Fystack 控制台的创建钱包弹窗中创建 HD 主密钥。创建钱包时 Cosigner 必须在线。

响应

  • Name
    success
    Type
    boolean
    Description

    表示请求是否成功。

  • Name
    message
    Type
    string
    Description

    描述操作结果的消息。

  • Name
    code
    Type
    integer
    Description

    表示结果状态的数字代码（0 表示成功）。

  • Name
    data
    Type
    object
    Description

    包含钱包详细信息。

  • Name
    wallet_id
    Type
    string
    Description

    新创建钱包的 UUID。

  • Name
    status
    Type
    string
    Description

    钱包创建过程的当前状态。

请求：基础钱包

POST
/wallets
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
})

请求：带归集任务

POST
/wallets
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'
})

Response

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

钱包创建状态

GET
/wallets/creation-status/{wallet_id}

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

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

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

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

响应

  • Name
    wallet_id
    Type
    string
    Description

    正在创建的钱包的 UUID。

  • Name
    status
    Type
    string
    Description

    钱包创建过程的当前状态。可以是 pending、success 或 error。

请求

GET
/wallets/creation-status/:wallet_id
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=="

Response

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

列出所有钱包

GET
/workspaces/{workspace_id}/wallets

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

参数

  • Name
    wallet_type
    Type
    string
    Description

    按类型筛选钱包。

  • Name
    limit
    Type
    integer
    Description

    限制返回的钱包数量。

  • Name
    offset
    Type
    integer
    Description

    开始返回结果之前要跳过的钱包数量。

请求

GET
/workspaces/:workspace_id/wallets
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)

Response

200
[
  {
    "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"
  }
]

获取充值地址

GET
/wallets/{wallet_id}/deposit-address

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

查询参数

  • Name
    asset_id
    Type
    string
    Description

    要获取充值地址的资产的 UUID。

  • Name
    address_type
    Type
    string
    Description

    要生成的区块链地址类型。必须是以下之一：evm、sol、tron 或 btc。

响应

  • Name
    success
    Type
    boolean
    Description

    表示请求是否成功。

  • Name
    data
    Type
    object
    Description

    包含充值地址详细信息。

  • Name
    asset_id
    Type
    string
    Description

    资产的 UUID。

  • Name
    address
    Type
    string
    Description

    用于充值的区块链地址。

  • Name
    qr_code
    Type
    string
    Description

    充值地址二维码图片的 URL。

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

请求

GET
/wallets/:wallet_id/deposit-address
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
)

Response

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

获取钱包资产概览

GET
/wallets/{wallet_id}/overview

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

路径参数

  • Name
    wallet_id
    Type
    string (uuid)
    Description

    钱包的 UUID。

查询参数

  • Name
    offset
    Type
    integer
    Description

    要跳过的记录数。必须介于 0 到 100000 之间。

  • Name
    limit
    Type
    integer
    Description

    要返回的最大记录数。必须介于 0 到 1000 之间。省略此参数或将其设为 0 将返回所有匹配记录。

  • Name
    is_native_only
    Type
    boolean
    Description

    设置为 true 时仅返回原生资产。

  • Name
    search
    Type
    string
    Description

    按资产名称或符号搜索。最多 100 个字符。

  • Name
    sort_by
    Type
    string
    Description

    按 balance、price_usd 或 value_usd 排序。省略时按名称排序。

  • Name
    sort_order
    Type
    string
    Description

    排序方向：asc 或 desc。提供 sort_by 时默认为 asc。

  • Name
    min_value_usd
    Type
    number
    Description

    仅返回美元总价值不低于该金额的资产。必须大于或等于 0。

  • Name
    network_ids
    Type
    array of strings (uuid)
    Description

    按网络 UUID 筛选。重复该查询参数即可包含多个网络。

响应

  • Name
    success
    Type
    boolean
    Description

    表示请求是否成功。

  • Name
    message
    Type
    string
    Description

    描述操作结果的消息。

  • Name
    code
    Type
    integer
    Description

    表示结果状态的数字代码（0 表示成功）。

  • Name
    data
    Type
    array
    Description

    匹配的钱包资产。没有匹配的资产时返回空数组。

  • Name
    balance
    Type
    string
    Description

    资产总余额，以十进制字符串形式返回。

  • Name
    on_hold
    Type
    string
    Description

    有效冻结所占用的金额，以十进制字符串形式返回。

  • Name
    available_balance
    Type
    string
    Description

    可用余额：总余额减去有效冻结金额。

  • Name
    price_usd
    Type
    string
    Description

    资产的美元单价，以十进制字符串形式返回。

  • Name
    value_usd
    Type
    string
    Description

    总余额乘以美元价格的结果，以十进制字符串形式返回。

  • Name
    asset
    Type
    object
    Description

    资产详情，包括其 UUID、名称、符号、小数位数和网络 ID。资产字段请参阅资产。

  • Name
    network
    Type
    object
    Description

    网络详情：id、name、chain_id、logo_url，以及 explorer_tx（如有）。

请求

GET
/wallets/:wallet_id/overview
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=="

Response

200
{
  "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"
      }
    }
  ]
}

获取钱包余额

GET
/wallets/{wallet_id}/balances

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

路径参数

  • Name
    wallet_id
    Type
    string (uuid)
    Description

    钱包的 UUID。

查询参数

  • Name
    offset
    Type
    integer
    Description

    要跳过的记录数。必须介于 0 到 100000 之间。

  • Name
    limit
    Type
    integer
    Description

    要返回的最大记录数。必须介于 0 到 1000 之间。省略此参数或将其设为 0 将返回所有匹配记录。

  • Name
    symbol
    Type
    array of strings
    Description

    按精确的资产符号筛选，例如 USDC。匹配不区分大小写。每个符号必须包含 1 到 20 个字母或数字。

  • Name
    asset_id
    Type
    array of strings (uuid)
    Description

    按资产 UUID 筛选。

  • Name
    network_id
    Type
    array of strings (uuid)
    Description

    按网络 UUID 筛选。

  • Name
    network_code
    Type
    array of strings
    Description

    按精确的网络代码筛选，例如 BSC_MAINNET。匹配不区分大小写。每个代码必须包含 1 到 50 个字符。请使用网络中的 internal_code。

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

响应

  • Name
    success
    Type
    boolean
    Description

    表示请求是否成功。

  • Name
    message
    Type
    string
    Description

    描述操作结果的消息。

  • Name
    code
    Type
    integer
    Description

    表示结果状态的数字代码（0 表示成功）。

  • Name
    data
    Type
    array
    Description

    匹配的钱包资产。没有匹配的资产时返回空数组。

  • Name
    wallet_id
    Type
    string (uuid)
    Description

    钱包的 UUID。

  • Name
    asset_id
    Type
    string (uuid)
    Description

    资产的 UUID。

  • Name
    symbol
    Type
    string
    Description

    资产符号。

  • Name
    asset_name
    Type
    string
    Description

    资产名称。

  • Name
    asset_logo
    Type
    string
    Description

    资产图标的 URL。

  • Name
    network_id
    Type
    string (uuid)
    Description

    网络的 UUID。

  • Name
    network_code
    Type
    string
    Description

    网络的内部代码。

  • Name
    network_name
    Type
    string
    Description

    网络名称。

  • Name
    network_logo
    Type
    string
    Description

    网络图标的 URL。

  • Name
    balance
    Type
    string
    Description

    资产总余额，以十进制字符串形式返回。

  • Name
    on_hold
    Type
    string
    Description

    有效冻结所占用的金额，以十进制字符串形式返回。

  • Name
    available_balance
    Type
    string
    Description

    可用余额：总余额减去有效冻结金额。

  • Name
    price_usd
    Type
    string
    Description

    资产的美元单价，以十进制字符串形式返回。

  • Name
    value_usd
    Type
    string
    Description

    总余额乘以美元价格的结果，以十进制字符串形式返回。

请求

GET
/wallets/:wallet_id/balances
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=="

Response

200
{
  "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 获取钱包余额

GET
/wallets/{wallet_id}/balance/{asset_id}

此 endpoint 返回钱包中单个资产的总余额。如需获取有效冻结和可用余额，请使用获取钱包余额。

路径参数

  • Name
    wallet_id
    Type
    string (uuid)
    Description

    钱包的 UUID。

  • Name
    asset_id
    Type
    string (uuid)
    Description

    资产的 UUID。

响应

  • Name
    success
    Type
    boolean
    Description

    表示请求是否成功。

  • Name
    message
    Type
    string
    Description

    描述操作结果的消息。

  • Name
    code
    Type
    integer
    Description

    表示结果状态的数字代码（0 表示成功）。

  • Name
    data
    Type
    string
    Description

    所请求资产的总余额，以十进制字符串形式返回。

请求

GET
/wallets/:wallet_id/balance/:asset_id
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=="

Response

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