|
|
# 红包 API 接口文档
|
|
|
|
|
|
**Base URL:** `/redpacket`
|
|
|
**协议:** HTTP POST，`Content-Type: application/json`
|
|
|
**认证:** 请求头携带 `token: <JWT令牌>`（标注需要登录的接口）
|
|
|
|
|
|
> **统一响应结构**
|
|
|
>
|
|
|
> ```json
|
|
|
> {
|
|
|
> "errCode": 0,
|
|
|
> "errMsg": "ok",
|
|
|
> "errDlt": "",
|
|
|
> "data": { }
|
|
|
> }
|
|
|
> ```
|
|
|
>
|
|
|
> `errCode` 为 `0` 表示成功，非 0 表示错误。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 1. 创建红包订单
|
|
|
|
|
|
**POST** `/redpacket/create_order`
|
|
|
需要登录。创建一条待上链的红包订单，返回业务 ID（bizID）供后续链上交易关联。
|
|
|
|
|
|
### 请求体
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"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` 必须提供，不能转给自己
|
|
|
|
|
|
### 响应体
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"errCode": 0,
|
|
|
"errMsg": "ok",
|
|
|
"data": {
|
|
|
"bizID": "550e8400-e29b-41d4-a716-446655440000"
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
| 字段 | 类型 | 说明 |
|
|
|
|------|------|------|
|
|
|
| `bizID` | string | 业务订单 ID，用于链上交易完成后提交回调 |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 2. 红包创建回调（链上确认）
|
|
|
|
|
|
**POST** `/redpacket/created_callback`
|
|
|
需要登录。链上交易广播后，由创建者提交交易哈希以激活红包。仅创建者可调用。
|
|
|
|
|
|
### 请求体
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"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 | 可选 | 覆盖多接收者列表 |
|
|
|
|
|
|
### 响应体
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"errCode": 0,
|
|
|
"errMsg": "ok",
|
|
|
"data": {}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 3. 查询红包详情
|
|
|
|
|
|
**POST** `/redpacket/detail`
|
|
|
|
|
|
### 请求体
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"packetID": "12345"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| `packetID` | string | **必填** | 链上红包 ID |
|
|
|
|
|
|
### 响应体
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"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`
|
|
|
需要登录。领取红包前，先获取服务端签名用于链上验证。会校验领取资格（是否群成员/好友、是否已领取、红包状态等）。
|
|
|
|
|
|
### 请求体
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"packetID": "12345",
|
|
|
"claimer": "0x5678...",
|
|
|
"randomSeed": ""
|
|
|
}
|
|
|
```
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| `packetID` | string | **必填** | 链上红包 ID |
|
|
|
| `claimer` | string | **必填** | 领取者钱包地址 |
|
|
|
| `randomSeed` | string | 可选 | 随机种子（十进制整数字符串）；为空或 `"0"` 时服务端自动生成 |
|
|
|
|
|
|
### 响应体
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"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`
|
|
|
需要登录。链上领取交易广播后提交，服务端解析链上事件并更新领取记录。
|
|
|
|
|
|
### 请求体
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"packetID": "12345",
|
|
|
"claimer": "0x5678...",
|
|
|
"txHash": "0xdef456..."
|
|
|
}
|
|
|
```
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| `packetID` | string | **必填** | 链上红包 ID |
|
|
|
| `claimer` | string | **必填** | 领取者钱包地址 |
|
|
|
| `txHash` | string | **必填** | 领取交易哈希 |
|
|
|
|
|
|
### 响应体
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"errCode": 0,
|
|
|
"errMsg": "ok",
|
|
|
"data": {}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 6. 申请退款
|
|
|
|
|
|
**POST** `/redpacket/request_refund`
|
|
|
需要登录。仅创建者可调用，红包到期后提交链上退款交易。
|
|
|
|
|
|
### 请求体
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"packetID": "12345"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| `packetID` | string | **必填** | 链上红包 ID（红包必须已到期） |
|
|
|
|
|
|
### 响应体
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"errCode": 0,
|
|
|
"errMsg": "ok",
|
|
|
"data": {
|
|
|
"txHash": "0xghi789...",
|
|
|
"status": "PENDING"
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
| 字段 | 类型 | 说明 |
|
|
|
|------|------|------|
|
|
|
| `txHash` | string | 退款交易哈希 |
|
|
|
| `status` | string | `PENDING`（退款交易已提交）或 `REFUNDED`（已退款） |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 7. 查询退款记录
|
|
|
|
|
|
**POST** `/redpacket/get_refund`
|
|
|
|
|
|
### 请求体
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"packetID": "12345"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| `packetID` | string | **必填** | 链上红包 ID |
|
|
|
|
|
|
### 响应体
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"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）。
|
|
|
|
|
|
### 请求体
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"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"` |
|
|
|
|
|
|
### 响应体
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"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 分钟。
|
|
|
|
|
|
### 请求体
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"challengeID": "aaaa-bbbb-cccc-dddd",
|
|
|
"signature": "0xaabbccdd..."
|
|
|
}
|
|
|
```
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| `challengeID` | string | **必填** | 挑战 ID（来自 `/wallet_bind/challenge`） |
|
|
|
| `signature` | string | **必填** | 钱包签名（0x 前缀十六进制，65 字节） |
|
|
|
|
|
|
### 响应体
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"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`
|
|
|
需要登录。查询当前登录用户在指定链上的活跃钱包绑定。
|
|
|
|
|
|
### 请求体
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"chainType": "EVM",
|
|
|
"walletAddress": "0x5678..."
|
|
|
}
|
|
|
```
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|------|------|------|------|
|
|
|
| `chainType` | string | **必填** | 链类型，`"EVM"` 或 `"TRON"` |
|
|
|
| `walletAddress` | string | 可选 | 钱包地址过滤条件 |
|
|
|
|
|
|
### 响应体
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"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`
|
