Build Your Own Integration

Note: Most users should start with our Discord Bot or Telegram Bot — they're production-ready and require no coding. This section is for developers who want to build custom integrations.

The API is Universal

Loyalteez's API is platform-agnostic. Any system that can make HTTP POST requests can integrate:

• Game servers — Reward players for achievements, playtime, events
• Mobile apps — Reward users for actions, purchases, referrals
• Websites — Reward visitors for signups, purchases, engagement
• Custom bots — Build bots for any platform
• IoT devices — Reward for sensor events, check-ins, interactions

How It Works

1. Your system detects a user action
2. POST to our API with event details + user identifier
3. We handle the rest — wallet creation, token distribution, blockchain

Your System
    ↓ HTTP POST
Loyalteez Event Handler
    ↓
Shared Services (Streaks, Leaderboards, etc.)
    ↓
Blockchain (Wallet creation, LTZ transfer)

Authentication

Method	Best For	How It Works
HMAC Signature	Server-to-server	Sign requests with your Security Key
Platform Validation	Discord, Telegram	We verify your platform credentials
Domain Validation	Websites	We verify the request origin

→ Authentication Deep-Dive

Quick Example

curl -X POST https://api.loyalteez.app/loyalteez-api/manual-event \
  -H "Content-Type: application/json" \
  -H "X-Loyalteez-Brand-Id: 0xYourBrandId" \
  -H "X-Loyalteez-Signature: <HMAC-SHA256>" \
  -H "X-Loyalteez-Timestamp: 1705862400000" \
  -d '{
    "brandId": "0xYourBrandId",
    "eventType": "quest_completed",
    "userEmail": "[email protected]",
    "metadata": {
      "platform": "your_game",
      "quest_name": "First Blood",
      "difficulty": "hard"
    }
  }'

→ More Examples (Python, Node.js, Go)

User Identification

Use the pattern: {platform}_{user_id}@loyalteez.app

Platform	Example
Discord	[email protected]
Telegram	[email protected]
Your Game	[email protected]
Email	[email protected] (direct email works too)

→ User Identification Deep-Dive

What You Get

Event Handler API

Track user actions and distribute rewards:

• POST /loyalteez-api/manual-event
• Returns transaction hash and new balance
• Automatic wallet creation on first reward

Shared Services

Platform-agnostic services for consistent experiences:

Service	Purpose
Streak Service	Track consecutive activity
Leaderboard Service	Rankings across metrics
Achievement Service	Gamified milestones
Perks Service	Redeemable rewards

Gas Relayer

Gasless transactions for perk redemption:

• Users don't pay gas fees
• Works with any frontend
• POST /relay with signed transaction

Prerequisites

1. Partner Portal Account — partners.loyalteez.app
2. Brand ID — Your wallet address (Settings → Account)
3. Security Key — For HMAC authentication (Settings → Security)
4. Events Configured — Create events in Partner Portal

Implementation Steps

1. Generate Security Key in Partner Portal
2. Create your events (event types, rewards, cooldowns)
3. Implement HMAC signing in your backend
4. Make API calls when users complete actions
5. Handle responses (success, cooldown, errors)

→ Complete Implementation Guide

Rate Limits

Limit	Value
Requests per second	100
Requests per minute	1,000
Requests per hour	10,000

Rate limits are per brand. Contact support for higher limits.

Error Handling

Common error responses:

Status	Meaning	Action
400	Invalid request	Check payload
401	Authentication failed	Check signature
404	Brand/event not found	Verify IDs
429	Rate limited	Slow down
500	Server error	Retry with backoff

→ Error Codes Reference

Next Steps

1. Authentication Guide — Implement HMAC signing
2. User Identification — Best practices
3. Code Examples — Ready-to-use code
4. API Reference — Complete API docs