API Specification v2.3

Authentication API

Through a standardised GET query interface, moonpacket actively retrieves 'reward rules' and 'user attributes' from your server. All logical judgements are handled by moonpacket.

View Specification Return Litepaper

Interaction Logic

The entire process is divided into two phases: 'Setup Phase' and 'Runtime Phase'. moonpacket will send requests to your API using the GET method:

← 左右滑動查看流程 →

Step One

Phase one: Define rules (Configuration)

⚡ Trigger timing: when entering the URL in the 'Claim Conditions Settings' and submitting it

GET GET

RET Returns a rule definition object with operators (gt, eq, lt...)

Step Two

Phase Two: Validate User (Runtime)

⚡ Trigger Timing: User attempts to claim the Red Packet

GET ?user_id=...

RET Return the actual attribute values of this specific user (pure numbers or strings)

💡 Supported Operators: `eq` (equals, supports strings/numbers), `gt` (greater than), `gte` (greater than or equal to), `lt` (less than), `lte` (less than or equal to). Values for non-`eq` operators must be numbers.

Application Scenarios

🎮

GameFi Integration

Define the rule `level >= 10`. When the user claims, moonpacket checks the user's attributes; if `level: 12` then it is approved.

🆔

Identity Binding Reward

Define the rule `kyc == true`. moonpacket checks the user status, and if it returns `kyc: true`, then rewards are distributed.

🚀

Blacklist Filtering

Define rule `is_blacklist == false`. If the API returns `is_blacklist: true`, the claim will be rejected.

Communication Example (GET Request)

Mode A 1. Define Rules (Setup)

When submitting settings, return JSON containing operators.

Request Content

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

Return Result (200 OK)

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

Mode B 2. Query Status (Runtime)

When the user claims, return pure values or strings.

Request Content

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

Return Result (200 OK)

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

Data Structure Definition (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 Validation

To ensure the authenticity of requests, moonpacket will include a signature in the header. You can refer to the code on the right for validation:

Necessary Headers

➜ X-API-KEY

➜ X-API-TIMESTAMP

➜ X-API-NONCE

➜ X-API-SIGNATURE

Signature Algorithm

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

⚠️ Note

● Timeout: Ensure the API can return results within 3 seconds.
● Format: Please strictly adhere to JSON structure; otherwise, it will lead to parsing failure.

Status Codes

Status Code	Status	Description
200	OK	Request successful
400	Bad Request	Request parameters are incorrect (e.g. incorrect format).
401	Unauthorized	Authorization Header is missing or Key is invalid.
403	Forbidden	IP restrictions or no permission to access this resource.
404	Not Found	User ID does not exist (for querying user status scenarios).
500	Server Error	Internal server error.

⚠️ Third-Party API Disclaimer

The integration methods for third-party platforms mentioned in this document are for reference only. Developers should consult and adhere to the latest official developer documentation of the platform.