API Specification v2.3

資格驗證 API

通過標準化的 GET 查詢接口，讓 moonpacket 主動向您的伺服器獲取「獎勵規則」與「用戶屬性」。所有的邏輯判斷由 moonpacket 處理。

查看規範返回 Litepaper

交互邏輯 (Interaction Logic)

整個流程分為「配置期」與「運行期」兩個階段。moonpacket 會使用 GET 方法向您的 API 發起請求：

← 左右滑動查看流程 →

步驟一

階段一：定義規則 (Configuration)

⚡ 觸發時機：在「領取條件設定」填入 URL 並提交時

GET <Endpoint>

RET 返回帶有運算符 (gt, eq, lt...) 的規則定義物件

步驟二

階段二：驗證用戶 (Runtime)

⚡ 觸發時機：用戶嘗試領取紅包時

GET <Endpoint>?user_id=...

RET 返回該特定用戶的實際屬性值 (純數值或字符串)

💡 運算符支援：`eq` (等於, 支援字串/數字), `gt` (大於), `gte` (大於等於), `lt` (小於), `lte` (小於等於)。非 `eq` 運算符的值必須為數字。

應用場景

🎮

GameFi 整合

定義規則 `level >= 10`。當用戶領取時，moonpacket 查詢用戶屬性，若 `level: 12` 則通過。

🆔

身份綁定獎勵

定義規則 `kyc == true`。moonpacket 查詢用戶狀態，若返回 `kyc: true` 則發放獎勵。

🚀

黑名單過濾

定義規則 `is_blacklist == false`。若 API 返回 `is_blacklist: true`，則拒絕領取。

通信範例 (GET Request)

Mode A 1. 定義規則 (Setup)

提交設定時，返回含運算符的 JSON

請求內容 (Request)

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

返回結果 (Response) (200 OK)

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

Mode B 2. 查詢狀態 (Runtime)

用戶領取時，返回純數值或字串

請求內容 (Request)

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

返回結果 (Response) (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;
  };
}

🔐 安全驗證 (Security)

為了確保請求的真實性，moonpacket 會在 Header 中包含簽名。您可以參考右側的代碼進行驗證：

必要 Headers

➜ X-API-KEY

➜ X-API-TIMESTAMP

➜ X-API-NONCE

➜ X-API-SIGNATURE

簽名算法

Signature = HMAC_SHA256(secret, body + timestamp + nonce)

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);

⚠️ 注意

● 超時：請確保 API 能在 3 秒 內返回結果。
● 格式：請嚴格遵守 JSON 結構，否則將導致解析失敗。

狀態碼 (Status Codes)

狀態碼	狀態	描述
200	OK (成功)	請求成功
400	Bad Request (錯誤請求)	請求參數錯誤（如格式不對）。
401	Unauthorized (未授權)	Authorization Header 缺失或 Key 無效。
403	Forbidden (禁止訪問)	IP 限制或無權訪問該資源。
404	Not Found (未找到)	用戶 ID 不存在 (針對查詢用戶狀態場景)。
500	Server Error (伺服器錯誤)	伺服器內部錯誤。

⚠️ 第三方 API 免責聲明

本文檔中提及的第三方平台整合方式僅供參考。請開發者務必查閱並遵循該平台最新的官方開發者文檔。