13 KiB

Raw Blame History Unescape Escape

红包 API 接口文档

Base URL: /redpacket
协议: HTTP POST，Content-Type: application/json
认证: 请求头携带 token: <JWT令牌>（标注需要登录的接口）

统一响应结构
{
  "errCode": 0,
  "errMsg": "ok",
  "errDlt": "",
  "data": { }
}
errCode 为 0 表示成功，非 0 表示错误。

1. 创建红包订单

POST /redpacket/create_order
需要登录。创建一条待上链的红包订单，返回业务 ID（bizID）供后续链上交易关联。

请求体

{
  "chainType": "EVM",
  "chainID": 1,
  "contractAddress": "0xAbCd...",
  "creatorWallet": "0x1234...",
  "groupID": "group_001",
  "scopeType": "GROUP",
  "receiverUserID": "",
  "receiverUserIDs": [],
  "packetType": 0,
  "token": "0x0000000000000000000000000000000000000000",
  "totalAmount": "1000000000000000000",
  "totalShares": 10,
  "expiryAt": 1800000000,
  "remark": "新年快乐"
}

字段	类型	必填	说明
`chainType`	string	必填	链类型，仅支持 `"EVM"` 或 `"TRON"`
`chainID`	int64	可选	链 ID；为 0 时从链客户端自动获取
`contractAddress`	string	可选	合约地址；为空时从链客户端自动获取
`creatorWallet`	string	必填	创建者钱包地址
`scopeType`	string	可选	范围类型：`GROUP`（群组）/`DIRECT`（定向）/`PUBLIC`（公开），默认 `PUBLIC`
`groupID`	string	GROUP 时必填	群组 ID（`scopeType=GROUP` 时必须提供）
`receiverUserID`	string	transfer 时必填	接收者用户 ID（`packetType=2` 且 `scopeType=DIRECT` 时必须提供）
`receiverUserIDs`	[]string	DIRECT + fixed/random 时必填	多接收者用户 ID 列表（`scopeType=DIRECT` 且 `packetType=0/1` 时使用）
`packetType`	int32	必填	红包类型：`0`=均分红包，`1`=随机红包，`2`=转账红包
`token`	string	可选	ERC20 代币合约地址；为空表示原生代币
`totalAmount`	string	必填	总金额（最小单位整数字符串，如 wei），必须为正整数
`totalShares`	int32	必填（packetType 0/1）	红包份数；均分/随机红包 >0 且 ≤10000；转账红包固定为 1
`expiryAt`	int64	可选	过期时间（Unix 时间戳秒）；0 表示不过期；必须为将来时间
`remark`	string	可选	备注

packetType 规则说明：

0（均分）：scopeType 必须为 GROUP，totalAmount 必须被 totalShares 整除
1（随机）：scopeType 必须为 GROUP，totalAmount ≥ totalShares
2（转账）：scopeType 必须为 DIRECT，totalShares 必须为 1，receiverUserID 必须提供，不能转给自己

响应体

{
  "errCode": 0,
  "errMsg": "ok",
  "data": {
    "bizID": "550e8400-e29b-41d4-a716-446655440000"
  }
}

字段	类型	说明
`bizID`	string	业务订单 ID，用于链上交易完成后提交回调

2. 红包创建回调（链上确认）

POST /redpacket/created_callback
需要登录。链上交易广播后，由创建者提交交易哈希以激活红包。仅创建者可调用。

请求体

{
  "bizID": "550e8400-e29b-41d4-a716-446655440000",
  "txHash": "0xabc123...",
  "packetID": "",
  "groupID": "",
  "scopeType": "",
  "receiverUserID": "",
  "receiverUserIDs": []
}

字段	类型	必填	说明
`bizID`	string	必填	创建订单时返回的业务 ID
`txHash`	string	必填	链上交易哈希
`packetID`	string	条件必填	链上红包 ID；链客户端离线时必须手动提供
`groupID`	string	可选	覆盖订单的群组 ID（不填则继承订单值）
`scopeType`	string	可选	覆盖订单的范围类型
`receiverUserID`	string	可选	覆盖单一接收者
`receiverUserIDs`	[]string	可选	覆盖多接收者列表

响应体

{
  "errCode": 0,
  "errMsg": "ok",
  "data": {}
}

3. 查询红包详情

POST /redpacket/detail

请求体

{
  "packetID": "12345"
}

字段	类型	必填	说明
`packetID`	string	必填	链上红包 ID

响应体

{
  "errCode": 0,
  "errMsg": "ok",
  "data": {
    "record": {
      "bizID": "550e8400-...",
      "chainType": "EVM",
      "packetID": "12345",
      "chainID": 1,
      "contractAddress": "0xAbCd...",
      "creatorUserID": "user_001",
      "creatorWallet": "0x1234...",
      "groupID": "group_001",
      "scopeType": "GROUP",
      "receiverUserID": "",
      "receiverUserIDs": [],
      "packetType": 0,
      "token": "0x0000000000000000000000000000000000000000",
      "totalAmount": "1000000000000000000",
      "totalShares": 10,
      "claimedAmount": "300000000000000000",
      "claimedShares": 3,
      "expiryAt": 1800000000,
      "txHash": "0xabc123...",
      "status": "ACTIVE",
      "createdAt": 1715500000,
      "updatedAt": 1715500100
    },
    "claims": [
      {
        "packetID": "12345",
        "userID": "user_002",
        "claimerWallet": "0x5678...",
        "authNonce": "1715500050000000000",
        "claimTxHash": "0xdef456...",
        "claimedAmount": "100000000000000000",
        "blockNumber": 19000000,
        "status": "CONFIRMED",
        "createdAt": 1715500050,
        "updatedAt": 1715500060
      }
    ]
  }
}

record 字段说明：

字段	类型	说明
`status`	string	红包状态：`PENDING` / `ACTIVE` / `COMPLETED` / `REFUNDED` / `EXPIRED`
`totalAmount`	string	总金额（最小单位）
`claimedAmount`	string	已领金额
`totalShares` / `claimedShares`	int32	总份数 / 已领份数

4. 申请领取签名

POST /redpacket/issue_claim_sign
需要登录。领取红包前，先获取服务端签名用于链上验证。会校验领取资格（是否群成员/好友、是否已领取、红包状态等）。

请求体

{
  "packetID": "12345",
  "claimer": "0x5678...",
  "randomSeed": ""
}

字段	类型	必填	说明
`packetID`	string	必填	链上红包 ID
`claimer`	string	必填	领取者钱包地址
`randomSeed`	string	可选	随机种子（十进制整数字符串）；为空或 `"0"` 时服务端自动生成

响应体

{
  "errCode": 0,
  "errMsg": "ok",
  "data": {
    "authNonce": "1715500050000000000",
    "deadline": 1715500350,
    "signature": "0xaabbcc...",
    "randomSeed": "8765309000000"
  }
}

字段	类型	说明
`authNonce`	string	认证随机数（传给合约）
`deadline`	int64	签名过期时间（Unix 时间戳，约 5 分钟后）
`signature`	string	服务端签名（0x 前缀十六进制，65 字节）
`randomSeed`	string	使用的随机种子

5. 提交领取结果

POST /redpacket/claim_result
需要登录。链上领取交易广播后提交，服务端解析链上事件并更新领取记录。

请求体

{
  "packetID": "12345",
  "claimer": "0x5678...",
  "txHash": "0xdef456..."
}

字段	类型	必填	说明
`packetID`	string	必填	链上红包 ID
`claimer`	string	必填	领取者钱包地址
`txHash`	string	必填	领取交易哈希

响应体

{
  "errCode": 0,
  "errMsg": "ok",
  "data": {}
}

6. 申请退款

POST /redpacket/request_refund
需要登录。仅创建者可调用，红包到期后提交链上退款交易。

请求体

{
  "packetID": "12345"
}

字段	类型	必填	说明
`packetID`	string	必填	链上红包 ID（红包必须已到期）

响应体

{
  "errCode": 0,
  "errMsg": "ok",
  "data": {
    "txHash": "0xghi789...",
    "status": "PENDING"
  }
}

字段	类型	说明
`txHash`	string	退款交易哈希
`status`	string	`PENDING`（退款交易已提交）或 `REFUNDED`（已退款）

7. 查询退款记录

POST /redpacket/get_refund

请求体

{
  "packetID": "12345"
}

字段	类型	必填	说明
`packetID`	string	必填	链上红包 ID

响应体

{
  "errCode": 0,
  "errMsg": "ok",
  "data": {
    "packetID": "12345",
    "refundTo": "0x1234...",
    "txHash": "0xghi789...",
    "amount": "700000000000000000",
    "createdAt": 1715600000
  }
}

字段	类型	说明
`refundTo`	string	退款目标钱包地址
`amount`	string	退款金额（最小单位）
`createdAt`	int64	退款记录创建时间（Unix 时间戳）

8. 发起钱包绑定挑战

POST /redpacket/wallet_bind/challenge
需要登录。生成一条待用户签名的消息，用于将钱包地址绑定到当前用户账户（EVM 使用 EIP-4361 SIWE，TRON 使用 signMessageV2）。

请求体

{
  "chainType": "EVM",
  "chainID": 1,
  "walletAddress": "0x5678...",
  "domain": "myapp.example.com",
  "uri": "https://myapp.example.com/wallet-bind"
}

字段	类型	必填	说明
`chainType`	string	必填	链类型，`"EVM"` 或 `"TRON"`
`walletAddress`	string	必填	待绑定的钱包地址
`chainID`	int64	可选	链 ID（EVM 时建议提供）
`domain`	string	可选	应用域名，默认 `"redpacket"`
`uri`	string	可选	应用 URI，默认 `"https://redpacket.local/wallet-bind"`

响应体

{
  "errCode": 0,
  "errMsg": "ok",
  "data": {
    "challengeID": "aaaa-bbbb-cccc-dddd",
    "userID": "user_001",
    "chainType": "EVM",
    "chainID": 1,
    "wallet": "0x5678...",
    "protocol": "siwe-eip4361",
    "signMethod": "personal_sign",
    "nonce": "xxxx-yyyy-zzzz",
    "message": "myapp.example.com wants you to sign in with your Ethereum account:\n0x5678...\n\nBind wallet ...",
    "issuedAt": "2026-05-12T08:39:00Z",
    "expiresAt": "2026-05-12T08:49:00Z"
  }
}

字段	类型	说明
`challengeID`	string	挑战 ID，确认绑定时使用
`message`	string	待签名的完整消息文本
`protocol`	string	EVM: `siwe-eip4361`；TRON: `tron-signmessagev2`
`signMethod`	string	EVM: `personal_sign`；TRON: `signMessageV2`
`expiresAt`	string	挑战过期时间（RFC3339，10 分钟有效期）

9. 确认钱包绑定

POST /redpacket/wallet_bind/confirm
提交用户对挑战消息的签名，服务端验证后完成钱包绑定。挑战有效期 10 分钟。

请求体

{
  "challengeID": "aaaa-bbbb-cccc-dddd",
  "signature": "0xaabbccdd..."
}

字段	类型	必填	说明
`challengeID`	string	必填	挑战 ID（来自 `/wallet_bind/challenge`）
`signature`	string	必填	钱包签名（0x 前缀十六进制，65 字节）

响应体

{
  "errCode": 0,
  "errMsg": "ok",
  "data": {
    "userID": "user_001",
    "chainType": "EVM",
    "chainID": 1,
    "walletAddress": "0x5678...",
    "status": "ACTIVE",
    "verifiedAt": "2026-05-12T08:42:00Z"
  }
}

字段	类型	说明
`status`	string	绑定状态，成功时为 `ACTIVE`
`verifiedAt`	string	绑定验证时间（RFC3339）

10. 查询钱包绑定信息

POST /redpacket/wallet_bind/detail
需要登录。查询当前登录用户在指定链上的活跃钱包绑定。

请求体

{
  "chainType": "EVM",
  "walletAddress": "0x5678..."
}

字段	类型	必填	说明
`chainType`	string	必填	链类型，`"EVM"` 或 `"TRON"`
`walletAddress`	string	可选	钱包地址过滤条件

响应体

{
  "errCode": 0,
  "errMsg": "ok",
  "data": {
    "userID": "user_001",
    "chainType": "EVM",
    "chainID": 1,
    "walletAddress": "0x5678...",
    "status": "ACTIVE",
    "challengeID": "aaaa-bbbb-cccc-dddd",
    "verifiedAt": "2026-05-12T08:42:00Z"
  }
}

附录：公共枚举值

枚举	可选值	说明
`chainType`	`EVM` / `TRON`	区块链类型
`scopeType`	`GROUP` / `DIRECT` / `PUBLIC`	红包范围
`packetType`	`0` / `1` / `2`	均分 / 随机 / 转账
红包 `status`	`PENDING` / `ACTIVE` / `COMPLETED` / `REFUNDED` / `EXPIRED`	红包状态
领取 `status`	`PENDING` / `CONFIRMED` / `FAILED`	领取记录状态
钱包绑定 `status`	`ACTIVE`	绑定状态（查询时只返回活跃绑定）

实现参考

路由：internal/api/router.go（/redpacket 分组）
HTTP 处理：internal/api/redpacket.go
Proto 定义：protocol/redpacket/redpacket.proto
RPC 实现：internal/rpc/redpacket/service.go、internal/rpc/redpacket/wallet.go

13 KiB Raw Blame History Unescape Escape