API 사양 v2.3

인증 API

표준화된 GET 쿼리 인터페이스를 통해, moonpacket은 귀하의 서버에서 '보상 규칙' 및 '사용자 속성'을 적극적으로 검색합니다. 모든 논리적 판단은 moonpacket이 처리합니다.

사양 보기 라이트페이퍼 반환

상호작용 논리

전체 프로세스는 두 단계로 나뉩니다: '설치 단계'와 '실행 단계'. moonpacket은 GET 방법을 사용하여 귀하의 API에 요청을 보냅니다:

← 左右滑動查看流程 →

첫 번째 단계

1단계: 규칙 정의(구성)

⚡ 트리거 이벤트: URL이 '청구 조건 설정'에 입력되고 제출되었을 때

GET GET

RET 연산자(greater than, equal, less than...)가 포함된 규칙 정의 객체를 반환합니다.

두 번째 단계

2단계: 사용자 검증(실행 시간)

⚡ 트리거 이벤트: 사용자가 레드패킷을 청구하려고 시도할 때

GET ?user_id=...

RET 특정 사용자의 실제 속성 값을 반환합니다(일반값 또는 문자열)

💡 지원되는 연산자: `eq` (같음, 문자열/숫자 지원), `gt` (보다 큼), `gte` (보다 크거나 같음), `lt` (보다 작음), `lte` (보다 작거나 같음). 비 `eq` 연산자에 대한 값은 숫자여야 합니다.

응용 시나리오

🎮

게임파이 통합

규칙 `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
  }
}

데이터 구조 정의 (타입스크립트)

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

⚠️ 메모

● 시간 초과: API가 3초 이내에 결과를 반환할 수 있는지 확인하세요.
● 형식: JSON 구조를 엄격히 준수해 주시기 바랍니다. 그렇지 않으면 파싱 오류가 발생할 수 있습니다.

상태 코드

상태 코드	상태	설명
200	OK	요청 성공
400	Bad Request	요청 매개변수 오류(예: 형식이 잘못됨).
401	Unauthorized	인증 헤더가 없거나 키가 잘못되었습니다.
403	Forbidden	IP 제한 또는 리소스에 대한 무단 접근.
404	Not Found	사용자 ID가 존재하지 않습니다(사용자 상태 조회 시나리오).
500	Server Error	내부 서버 오류.

⚠️ 제3자 API 면책 조항

본 문서에 언급된 써드파티 플랫폼 통합 방법은 참고용입니다. 개발자는 해당 플랫폼의 최신 공식 개발자 문서를 참고하고 준수해야 합니다.