Staking 目录与交易

本页补充质押模块用户侧核心接口的用途、入参、出参与示例，阅读层级与详细设计文档保持一致。

`GET /api/v1/staking/products`

用途

获取质押产品目录，用于产品列表页、筛选页和推荐卡片区域。

Query 参数

参数	类型	必填	说明	示例
`chainId`	Integer	否	链 ID 过滤	`8453`
`productType`	String	否	产品类型，如 `aggregated`、`vault`	`vault`
`riskLevel`	String	否	风险等级过滤	`medium`
`assetSymbol`	String	否	申购资产符号	`USDC`
`status`	String	否	产品状态过滤	`active`

响应字段

字段路径	类型	说明	示例
`data.items`	Array	产品列表	`[]`
`data.items[].id`	String	产品 ID	`base_usdc_nexfi_vault`
`data.items[].name`	String	产品名称	`NexFi USDC Yield Vault`
`data.items[].productType`	String	产品类型	`vault`
`data.items[].chainId`	Integer	链 ID	`8453`
`data.items[].assetSymbol`	String	申购资产符号	`USDC`
`data.items[].apy`	Number	当前 APY	`7.25`
`data.items[].tvlUsd`	Number	TVL 美元估值	`1200000`
`data.items[].riskLevel`	String	风险等级	`medium`
`data.items[].status`	String	产品状态	`active`

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "items": [
      {
        "id": "base_usdc_nexfi_vault",
        "name": "NexFi USDC Yield Vault",
        "productType": "vault",
        "chainId": 8453,
        "assetSymbol": "USDC",
        "apy": 7.25,
        "tvlUsd": 1200000,
        "riskLevel": "medium",
        "status": "active"
      }
    ]
  }
}

`GET /api/v1/staking/products/{id}`

用途

获取单个质押产品详情，用于产品详情页和交易确认页。

Path 参数

参数	类型	必填	说明	示例
`id`	String	是	产品 ID	`base_usdc_nexfi_vault`

典型响应字段

字段路径	类型	说明	示例
`data.id`	String	产品 ID	`base_usdc_nexfi_vault`
`data.name`	String	产品名称	`NexFi USDC Yield Vault`
`data.protocolName`	String	底层协议或金库名称	`NexFi Vault`
`data.productType`	String	产品类型	`vault`
`data.chainId`	Integer	链 ID	`8453`
`data.assetSymbol`	String	申购资产	`USDC`
`data.apy`	Number	APY	`7.25`
`data.tvlUsd`	Number	TVL	`1200000`
`data.minDeposit`	String	最小申购金额	`100`
`data.exitModel`	String	退出方式说明	`ERC-4626 redeem`
`data.riskLevel`	String	风险等级	`medium`
`data.status`	String	状态	`active`

`GET /api/v1/staking/positions`

用途

获取用户质押持仓列表，用于资产页收益分区、持仓列表页和详情页汇总。

Query 参数

参数	类型	必填	说明	示例
`walletAddress`	String	是	钱包地址	`0xabc...`
`chainId`	Integer	否	链过滤	`8453`
`status`	String	否	持仓状态过滤	`active`

典型响应字段

字段路径	类型	说明	示例
`data.items`	Array	持仓列表	`[]`
`data.items[].positionId`	String	持仓 ID	`pos_001`
`data.items[].productId`	String	关联产品 ID	`base_usdc_nexfi_vault`
`data.items[].walletAddress`	String	钱包地址	`0xabc...`
`data.items[].principalAmount`	String	本金	`1000`
`data.items[].shareAmount`	String	份额数量	`998.12`
`data.items[].estimatedValueUsd`	Number	预估美元价值	`1008.2`
`data.items[].unclaimedRewardUsd`	Number	未领取收益估值	`8.2`
`data.items[].status`	String	持仓状态	`active`

`GET /api/v1/staking/orders`

用途

获取用户质押订单列表，用于订单历史和交易追踪。

Query 参数

参数	类型	必填	说明	示例
`walletAddress`	String	是	钱包地址	`0xabc...`
`status`	String	否	订单状态过滤	`confirmed`
`orderType`	String	否	订单类型，如 `subscribe`、`redeem`	`subscribe`
`limit`	Integer	否	返回条数	`20`

典型响应字段

字段路径	类型	说明	示例
`data.items`	Array	订单列表	`[]`
`data.items[].orderId`	String	平台订单号	`stk_20260511_0001`
`data.items[].productId`	String	产品 ID	`base_usdc_nexfi_vault`
`data.items[].orderType`	String	订单类型	`subscribe`
`data.items[].status`	String	订单状态	`pending_chain`
`data.items[].amount`	String	金额	`1000`
`data.items[].txHash`	String \| Null	链上交易哈希	`0x123...`
`data.items[].updatedAt`	String	更新时间	`2026-05-11T10:00:00.000Z`

`POST /api/v1/staking/transactions/build`

用途

根据产品和动作类型构建质押交易参数，客户端据此发起本地签名。

Body 参数

参数	类型	必填	说明	示例
`productId`	String	是	产品 ID	`base_usdc_nexfi_vault`
`orderType`	String	是	订单类型：`subscribe` 或 `redeem`	`subscribe`
`walletAddress`	String	是	钱包地址	`0xabc...`
`amount`	String	是	申购或赎回金额	`1000`

请求示例

{
  "productId": "base_usdc_nexfi_vault",
  "orderType": "subscribe",
  "walletAddress": "0xabc...",
  "amount": "1000"
}

响应字段

字段路径	类型	说明	示例
`data.buildId`	String	交易构建结果 ID	`build_20260511_0001`
`data.chainId`	Integer	交易所在链	`8453`
`data.to`	String	目标合约地址	`0xvault...`
`data.value`	String	原生币转账值	`0`
`data.data`	String	calldata	`0xb6b55f25...`
`data.gasLimit`	String	建议 Gas Limit	`280000`
`data.warnings`	Array	风险提示	`[]`
`data.sharesPreview`	String	Vault 产品预估份额	`998.12`
`data.feePreview`	String	预估费用	`1.50`
`data.vaultAddress`	String	Vault 地址	`0xvault...`

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "buildId": "build_20260511_0001",
    "chainId": 8453,
    "to": "0xvault000000000000000000000000000000000001",
    "value": "0",
    "data": "0xb6b55f25",
    "gasLimit": "280000",
    "warnings": ["APY is estimated and not guaranteed"],
    "sharesPreview": "998.12",
    "feePreview": "1.50",
    "vaultAddress": "0xvault000000000000000000000000000000000001"
  }
}

`POST /api/v1/staking/orders`

用途

在客户端拿到交易参数并准备签名前后，创建平台订单用于后续状态追踪。

Body 参数

参数	类型	必填	说明	示例
`buildId`	String	是	交易构建 ID	`build_20260511_0001`
`productId`	String	是	产品 ID	`base_usdc_nexfi_vault`
`walletAddress`	String	是	钱包地址	`0xabc...`
`orderType`	String	是	订单类型	`subscribe`
`amount`	String	是	金额	`1000`
`txHash`	String	是	链上交易哈希	`0x123...`

典型响应字段

字段路径	类型	说明	示例
`data.orderId`	String	平台订单号	`stk_20260511_0001`
`data.status`	String	初始状态	`pending_chain`

`GET /api/v1/staking/orders/{id}`

用途

查询单笔质押订单详情。

Path 参数

参数	类型	必填	说明	示例
`id`	String	是	平台订单号	`stk_20260511_0001`

典型响应字段

字段路径	类型	说明	示例
`data.orderId`	String	订单号	`stk_20260511_0001`
`data.productId`	String	产品 ID	`base_usdc_nexfi_vault`
`data.orderType`	String	订单类型	`subscribe`
`data.status`	String	订单状态	`confirmed`
`data.txHash`	String \| Null	交易哈希	`0x123...`
`data.updatedAt`	String	更新时间	`2026-05-11T10:00:00.000Z`

`GET /api/v1/staking/vaults/{id}/preview`

用途

对 Vault 产品执行申购或赎回预估，供用户确认份额、到账资产和预期收益变化。

Path / Query 参数

参数	类型	必填	说明	示例
`id`	String	是	Vault 产品 ID	`base_usdc_nexfi_vault`
`assets`	String	否	申购资产金额，和 `shares` 二选一	`1000`
`shares`	String	否	赎回份额，和 `assets` 二选一	`998.12`

典型响应字段

字段路径	类型	说明	示例
`data.assets`	String	输入资产金额	`1000`
`data.sharesPreview`	String	预估份额	`998.12`
`data.withdrawAssetsPreview`	String	预估赎回到账资产	`999.50`
`data.feePreview`	String	预估费用	`1.50`
`data.pricePerShare`	String	当前份额净值	`1.0019`

业务说明

assets 与 shares 只能传一个，否则应返回参数错误。
Vault 预估用于展示，不应作为最终成交结果承诺。
APY、TVL、持仓收益等指标可能是最终一致数据，前端需提示“数据更新时间”。

概览

钱包

跨链桥

质押

量化

钱包 API 参考

跨链桥 API 参考

质押 API 参考

量化 API 参考

Documentation Index

​Staking 目录与交易

​GET /api/v1/staking/products

​用途

​Query 参数

​响应字段

​响应示例

​GET /api/v1/staking/products/{id}

​用途

​Path 参数

​典型响应字段

​GET /api/v1/staking/positions

​用途

​Query 参数

​典型响应字段

​GET /api/v1/staking/orders

​用途

​Query 参数

​典型响应字段

​POST /api/v1/staking/transactions/build

​用途

​Body 参数

​请求示例

​响应字段

​响应示例

​POST /api/v1/staking/orders

​用途

​Body 参数

​典型响应字段

​GET /api/v1/staking/orders/{id}

​用途

​Path 参数

​典型响应字段

​GET /api/v1/staking/vaults/{id}/preview

​用途

​Path / Query 参数

​典型响应字段

​业务说明

Staking 目录与交易

`GET /api/v1/staking/products`

用途

Query 参数

响应字段

响应示例

`GET /api/v1/staking/products/{id}`

用途

Path 参数

典型响应字段

`GET /api/v1/staking/positions`

用途

Query 参数

典型响应字段

`GET /api/v1/staking/orders`

用途

Query 参数

典型响应字段

`POST /api/v1/staking/transactions/build`

用途

Body 参数

请求示例

响应字段

响应示例

`POST /api/v1/staking/orders`

用途

Body 参数

典型响应字段

`GET /api/v1/staking/orders/{id}`

用途

Path 参数

典型响应字段

`GET /api/v1/staking/vaults/{id}/preview`

用途

Path / Query 参数

典型响应字段

业务说明