Specifica API v2.3

API di Autenticazione

Attraverso un'interfaccia di query GET standardizzata, moonpacket recupera attivamente 'le regole di ricompensa' e 'gli attributi dell'utente' dal tuo server. Tutti i giudizi logici sono gestiti da moonpacket.

Visualizza specifiche Restituisci Litepaper

Logica di Interazione

L'intero processo è suddiviso in due fasi: 'Fase di Configurazione' e 'Fase di Esecuzione'. moonpacket invierà richieste alla tua API utilizzando il metodo GET:

← 左右滑動查看流程 →

Passo Uno

Fase 1: Definire Regole (Configurazione)

⚡ Evento scatenante: quando l'URL è compilato nella 'Impostazione delle Condizioni di Rivendicazione' e inviato

GET GET

RET Restituisce l'oggetto di definizione della regola con operatori (gt, eq, lt...)

Passo Due

Fase 2: Convalida utente (Runtime)

⚡ Evento attivante: quando l'utente tenta di richiedere il Red Packet

GET ?user_id=...

RET Restituisce il valore effettivo dell'attributo di quell'utente specifico (valore semplice o stringa)

💡 Operatori supportati: `eq` (uguale, supporta stringhe/numeri), `gt` (maggiore di), `gte` (maggiore o uguale a), `lt` (minore di), `lte` (minore o uguale a). I valori per operatori non-`eq` devono essere numeri.

Scenari di Applicazione

🎮

Integrazione GameFi

Definisci la regola `level >= 10`. Quando l'utente richiede, moonpacket controlla gli attributi dell'utente, se `level: 12` allora è approvato.

🆔

Ricompensa di legame identitario

Definisci la regola `kyc == true`. moonpacket verifica lo stato dell'utente e, se restituisce `kyc: true`, allora vengono distribuiti i premi.

🚀

Filtraggio blacklist

Definire la regola `is_blacklist == false`. Se l'API restituisce `is_blacklist: true`, la richiesta viene rifiutata.

Esempio di comunicazione (richiesta GET)

Mode A 1. Definisci le Regole (Impostazione)

Quando si inviano le impostazioni, restituire JSON contenente operatori.

Richiesta di contenuto

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

Restituisci Risultato (200 OK)

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

Mode B 2. Stato della Query (Runtime)

Quando l'utente richiede, restituire valori o stringhe puri.

Richiesta di contenuto

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

Restituisci Risultato (200 OK)

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

Definizione della Struttura Dati (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;
  };
}

🔐 Validazione della Sicurezza

Per garantire l'autenticità delle richieste, moonpacket includerà una firma nell'intestazione. Puoi fare riferimento al codice a destra per la convalida:

Intestazioni Necessarie

➜ X-API-KEY

➜ X-API-TIMESTAMP

➜ X-API-NONCE

➜ X-API-SIGNATURE

Algoritmo di Firma

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

⚠️ Nota

● Timeout: Assicurati che l'API possa restituire risultati entro 3 secondi.
● Formato: Si prega di attenersi rigorosamente alla struttura JSON, altrimenti si verificherà un errore di analisi.

Codici di Stato

Codice di stato	Stato	Descrizione
200	OK	Richiesta riuscita
400	Bad Request	Errore nei parametri della richiesta (ad es. formato errato).
401	Unauthorized	Header di autorizzazione mancante o chiave non valida.
403	Forbidden	Restrizione IP o accesso non autorizzato alla risorsa.
404	Not Found	ID Utente non esiste (per scenari di query dello stato dell'utente).
500	Server Error	Errore interno del server.

⚠️ Dispositivo di esenzione responsabilità API di terze parti

I metodi di integrazione per le piattaforme di terze parti menzionati in questo documento sono solo a scopo di riferimento. Gli sviluppatori dovrebbero consultare e attenersi alla documentazione ufficiale per gli sviluppatori più recente della piattaforma.