9.2 KiB

Raw Blame History

Wallet Service API 文档

概述

本文档描述 Wallet Service 的所有 HTTP API 接口。服务基础路径: /api/v1

认证

除标注为 公开 的接口外，所有接口都需要 JWT Bearer Token 认证：

Authorization: Bearer <jwt_token>

JWT Payload 结构：

{
  "sub": "用户ID",
  "seq": 1001,
  "exp": 1700000000
}

响应格式

成功响应

{
  "success": true,
  "data": { ... },
  "timestamp": "2024-01-01T00:00:00.000Z"
}

错误响应

{
  "success": false,
  "code": "ERROR_CODE",
  "message": "错误描述",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

1. 健康检查

GET /api/v1/health

检查服务健康状态。

认证: 公开

响应示例:

{
  "success": true,
  "data": {
    "status": "ok",
    "service": "wallet-service",
    "timestamp": "2024-01-01T00:00:00.000Z"
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}

2. 钱包接口

GET /api/v1/wallet/my-wallet

查询当前用户的钱包信息。

认证: 需要

响应示例:

{
  "success": true,
  "data": {
    "walletId": "1",
    "userId": "12345",
    "balances": {
      "usdt": { "available": 1000.5, "frozen": 0 },
      "dst": { "available": 0, "frozen": 0 },
      "bnb": { "available": 0.1, "frozen": 0 },
      "og": { "available": 0, "frozen": 0 },
      "rwad": { "available": 100, "frozen": 0 }
    },
    "hashpower": 500,
    "rewards": {
      "pendingUsdt": 50,
      "pendingHashpower": 100,
      "pendingExpireAt": "2024-01-02T00:00:00.000Z",
      "settleableUsdt": 200,
      "settleableHashpower": 400,
      "settledTotalUsdt": 1000,
      "settledTotalHashpower": 2000,
      "expiredTotalUsdt": 50,
      "expiredTotalHashpower": 100
    },
    "status": "ACTIVE"
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}

字段说明:

字段	类型	描述
walletId	string	钱包ID
userId	string	用户ID
balances.{coin}.available	number	可用余额
balances.{coin}.frozen	number	冻结余额
hashpower	number	当前算力
rewards.pendingUsdt	number	待领取USDT奖励
rewards.pendingHashpower	number	待领取算力奖励
rewards.pendingExpireAt	string	待领取奖励过期时间
rewards.settleableUsdt	number	可结算USDT
rewards.settleableHashpower	number	可结算算力
rewards.settledTotalUsdt	number	已结算USDT累计
rewards.settledTotalHashpower	number	已结算算力累计
rewards.expiredTotalUsdt	number	已过期USDT累计
rewards.expiredTotalHashpower	number	已过期算力累计
status	string	钱包状态: ACTIVE, FROZEN

POST /api/v1/wallet/claim-rewards

领取待领取的奖励，将其转为可结算状态。

认证: 需要

请求体: 无

响应示例:

{
  "success": true,
  "data": {
    "message": "Rewards claimed successfully"
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}

错误码:

错误码	HTTP状态	描述
NO_PENDING_REWARDS	400	没有待领取的奖励
WALLET_FROZEN	403	钱包已冻结

POST /api/v1/wallet/settle

结算可结算的USDT奖励为指定币种。

认证: 需要

请求体:

{
  "usdtAmount": 100,
  "settleCurrency": "BNB"
}

字段	类型	必填	描述
usdtAmount	number	是	结算USDT金额 (>0)
settleCurrency	string	是	结算目标币种: BNB, USDT, DST, OG, RWAD

响应示例:

{
  "success": true,
  "data": {
    "settlementOrderId": "12345"
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}

错误码:

错误码	HTTP状态	描述
INSUFFICIENT_BALANCE	400	可结算余额不足
WALLET_FROZEN	403	钱包已冻结
VALIDATION_ERROR	400	参数验证失败

3. 流水接口

GET /api/v1/wallet/ledger/my-ledger

查询当前用户的账本流水记录。

认证: 需要

查询参数:

参数	类型	必填	默认值	描述
page	number	否	1	页码 (>=1)
pageSize	number	否	20	每页数量 (1-100)
entryType	string	否	-	流水类型过滤
assetType	string	否	-	资产类型过滤
startDate	string	否	-	开始日期 (ISO8601)
endDate	string	否	-	结束日期 (ISO8601)

entryType 可选值:

DEPOSIT_KAVA - KAVA链充值
DEPOSIT_BSC - BSC链充值
PLANT_PAYMENT - 认种支付
REWARD_PENDING - 奖励待领取
REWARD_TO_SETTLEABLE - 奖励转可结算
REWARD_SETTLED - 奖励已结算
REWARD_EXPIRED - 奖励已过期
WITHDRAWAL - 提现
ADMIN_ADJUST - 管理员调整

assetType 可选值:

USDT, DST, BNB, OG, RWAD, HASHPOWER

响应示例:

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "1001",
        "entryType": "DEPOSIT_KAVA",
        "amount": 100,
        "assetType": "USDT",
        "balanceAfter": 1100,
        "refOrderId": null,
        "refTxHash": "0x1234...5678",
        "memo": "Deposit from KAVA",
        "createdAt": "2024-01-01T10:00:00.000Z"
      },
      {
        "id": "1002",
        "entryType": "PLANT_PAYMENT",
        "amount": -50,
        "assetType": "USDT",
        "balanceAfter": 1050,
        "refOrderId": "order_123",
        "refTxHash": null,
        "memo": "Plant payment",
        "createdAt": "2024-01-01T11:00:00.000Z"
      }
    ],
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "totalPages": 5
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}

字段说明:

字段	类型	描述
id	string	流水ID
entryType	string	流水类型
amount	number	金额 (正入账/负支出)
assetType	string	资产类型
balanceAfter	number	操作后余额
refOrderId	string	关联订单号
refTxHash	string	关联交易哈希
memo	string	备注
createdAt	string	创建时间

4. 充值接口 (内部服务)

POST /api/v1/wallet/deposit

处理链上充值确认后的入账。

认证: 公开 (仅限内部服务调用)

请求体:

{
  "userId": "12345",
  "amount": 100,
  "chainType": "KAVA",
  "txHash": "0x1234567890abcdef..."
}

字段	类型	必填	描述
userId	string	是	用户ID
amount	number	是	充值金额 (>0)
chainType	string	是	链类型: KAVA, BSC
txHash	string	是	交易哈希 (唯一)

响应示例:

{
  "success": true,
  "data": {
    "message": "Deposit processed successfully"
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}

错误码:

错误码	HTTP状态	描述
DUPLICATE_TRANSACTION	409	重复交易 (txHash已存在)
VALIDATION_ERROR	400	参数验证失败

错误码汇总

错误码	HTTP状态	描述
VALIDATION_ERROR	400	参数验证失败
UNAUTHORIZED	401	未认证
FORBIDDEN	403	无权限
NOT_FOUND	404	资源不存在
DUPLICATE_TRANSACTION	409	重复交易
INSUFFICIENT_BALANCE	400	余额不足
WALLET_FROZEN	403	钱包已冻结
WALLET_NOT_FOUND	404	钱包不存在
NO_PENDING_REWARDS	400	没有待领取的奖励
INTERNAL_ERROR	500	内部错误

Swagger 文档

启动服务后访问: http://localhost:3000/api-docs

调用示例

cURL

# 获取钱包信息
curl -X GET "http://localhost:3000/api/v1/wallet/my-wallet" \
  -H "Authorization: Bearer <token>"

# 领取奖励
curl -X POST "http://localhost:3000/api/v1/wallet/claim-rewards" \
  -H "Authorization: Bearer <token>"

# 结算奖励
curl -X POST "http://localhost:3000/api/v1/wallet/settle" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"usdtAmount": 100, "settleCurrency": "BNB"}'

# 查询流水
curl -X GET "http://localhost:3000/api/v1/wallet/ledger/my-ledger?page=1&pageSize=10" \
  -H "Authorization: Bearer <token>"

# 充值入账 (内部服务)
curl -X POST "http://localhost:3000/api/v1/wallet/deposit" \
  -H "Content-Type: application/json" \
  -d '{"userId": "12345", "amount": 100, "chainType": "KAVA", "txHash": "0x..."}'

JavaScript (Fetch)

// 获取钱包信息
const response = await fetch('/api/v1/wallet/my-wallet', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});
const data = await response.json();

// 结算奖励
const settleResponse = await fetch('/api/v1/wallet/settle', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    usdtAmount: 100,
    settleCurrency: 'BNB'
  })
});

9.2 KiB Raw Blame History

Wallet Service API 文档

概述

认证

响应格式

成功响应

错误响应

1. 健康检查

GET /api/v1/health

2. 钱包接口

GET /api/v1/wallet/my-wallet

POST /api/v1/wallet/claim-rewards

POST /api/v1/wallet/settle

3. 流水接口

GET /api/v1/wallet/ledger/my-ledger

4. 充值接口 (内部服务)

POST /api/v1/wallet/deposit

错误码汇总

Swagger 文档

调用示例

cURL

JavaScript (Fetch)

9.2 KiB

Raw Blame History