API 规范 v2.3

身份验证API

通过标准化的GET查询接口，moonpacket主动从您的服务器获取“奖励规则”和“用户属性”。所有逻辑判断都由moonpacket处理。

查看规格返回轻论文

Interaction Logic

整个过程分为两个阶段：‘设置阶段’和‘运行阶段’。moonpacket将使用GET方法向您的API发送请求：

← 左右滑動查看流程 →

第一步

阶段一：定义规则 (Configuration)

⚡ 触发时机：在「领取条件设定」填入 URL 并提交时

GET GET

RET 返回带有运算符 (gt, eq, lt...) 的规则定义物件

第二步

阶段二：验证用户 (Runtime)

⚡ 触发时机：用户尝试领取红包时

GET ?user_id=...

RET 返回该特定用户的实际属性值 (纯数值或字符串)

💡 支持的操作符：`eq`（等于，支持字符串/数字），`gt`（大于），`gte`（大于或等于），`lt`（小于），`lte`（小于或等于）。非`eq`操作符的值必须为数字。

应用场景

🎮

GameFi Integration

定义规则 `level >= 10`。当用户领取时，moonpacket 查询用户属性，若 `level: 12` 则通过。

🆔

身份绑定奖励

定义规则 `kyc == true`。 moonpacket 查询用户状态，若返回 `kyc: true` 则发放奖励。

🚀

黑名单过滤

定义规则 `is_blacklist == false`。若 API 返回 `is_blacklist: true`，则拒绝领取。

通信示例（GET请求）

Mode A 1. 定义规则（设置）

提交设置时，返回包含操作员的 JSON。

请求内容

GET /check HTTP/1.1
Host: api.your-game.com
Content-Type: application/json
X-API-KEY: 1234567890
X-API-TIMESTAMP: 1698765432
X-API-NONCE: 987654
X-API-SIGNATURE: 5d41402abc4b2a76b9719d911017c592...

# No user_id = Get Rules

返回结果 (200 OK)

{
  "data": {
    "level": {
      "gt": 99
    },
    "status": {
      "eq": "active"
    },
    "is_blacklist": {
      "eq": false
    }
  }
}

Mode B 2. 查询状态（运行时）

当用户领取时，返回纯值或字符串。

请求内容

GET /check?user_id=666666666 HTTP/1.1
Host: api.your-game.com
Content-Type: application/json
X-API-KEY: 1234567890
X-API-TIMESTAMP: 1698765432
X-API-NONCE: 123456
X-API-SIGNATURE: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6...

# With user_id = Get User Status

返回结果 (200 OK)

{
  "data": {
    "level": 100,
    "status": "active",
    "is_blacklist": false
  }
}

数据结构定义（TypeScript）

types.d.ts

// Step 1: Rules Definition
interface RulesResponse {
  data: {
    [key: string]: {
      eq?: string | number | boolean;
      gt?: number;
      gte?: number;
      lt?: number;
      lte?: number;
    };
  };
}

// Step 2: User Status
interface UserStatusResponse {
  data: {
    [key: string]: string | number | boolean;
  };
}

🔐 安全验证

为了确保请求的真实性，moonpacket将在头部包含一个签名。您可以参考右侧的代码进行验证：

必要的头部

➜ X-API-KEY

➜ X-API-TIMESTAMP

➜ X-API-NONCE

➜ X-API-SIGNATURE

签名算法

签名 = HMAC_SHA256(密钥, 请求体 + 时间戳 + 随机数)

verify.ts

import crypto from "crypto";

// 1. Generate Signature
function generateSignature(
  apiSecret: string,
  body: object,
  timestamp: number,
  nonce?: string
) {
  const payload = JSON.stringify(body) + timestamp + (nonce || "");
  return crypto.createHmac("sha256", apiSecret).update(payload).digest("hex");
}

// Client Usage Example
const apiKey = "client123";
const apiSecret = "mysecretkey";
const body = { /* Query Params or Body */ }; 
const timestamp = Date.now();
const nonce = crypto.randomBytes(8).toString("hex");

const signature = generateSignature(apiSecret, body, timestamp, nonce);

console.log({ apiKey, timestamp, nonce, signature });

// 2. Verify Signature
function verifySignature(
  apiSecret: string,
  body: object,
  timestamp: number,
  nonce: string,
  signature: string
) {
  const expected = generateSignature(apiSecret, body, timestamp, nonce);
  return expected === signature;
}

// Verification Result
const isValid = verifySignature(apiSecret, body, timestamp, nonce, signature);
console.log("Is Valid:", isValid);

⚠️ Note

● 超时：确保API可以在3秒内返回结果。
● 格式：请严格遵守JSON结构，否则将导致解析失败。

Status Codes

状态码	状态	Description
200	OK	请求成功
400	Bad Request	请求参数错误（如格式不对）。
401	Unauthorized	Authorization Header 缺失或 Key 无效。
403	Forbidden	IP 限制或无权访问该资源。
404	Not Found	用户 ID 不存在 (针对查询用户状态场景)。
500	Server Error	伺服器内部错误。

⚠️ 第三方API免责声明

本文档中提到的第三方平台集成方法仅供参考。开发者应查阅并遵循该平台最新的官方开发者文档。