User Identification

How to identify users when sending events to the Loyalteez API.

The Pattern

{platform}_{user_id}@loyalteez.app

This creates a deterministic wallet for each user.

Platform Examples

Platform	Pattern	Example
Discord	discord_{user_id}@loyalteez.app	discord_123456789@loyalteez.app
Telegram	telegram_{user_id}@loyalteez.app	telegram_987654321@loyalteez.app
Your Game	yourgame_{player_id}@loyalteez.app	mygame_player42@loyalteez.app
Your App	myapp_{user_id}@loyalteez.app	myapp_user_abc123@loyalteez.app
Website	mysite_{user_id}@loyalteez.app	mysite_visitor_xyz@loyalteez.app
Direct Email	user@example.com	john@example.com

Deterministic Wallets

The same identifier always maps to the same wallet:

player_123@mygame.loyalteez.app → 0xABC...
player_123@mygame.loyalteez.app → 0xABC... (same wallet)

This means:

• Users accumulate rewards over time
• No registration required
• Wallets created automatically on first reward

Best Practices

1. Use Stable Identifiers

Good:

discord_123456789@loyalteez.app  (immutable Discord ID)
mygame_player_42@loyalteez.app  (database primary key)

Bad:

discord_CoolUsername@loyalteez.app  (usernames can change)
mygame_session_abc123@loyalteez.app  (sessions are temporary)

2. Keep Platform Prefix Consistent

Always use the same prefix for your platform:

// Good - consistent prefix
const userEmail = `mygame_${playerId}@loyalteez.app`;

// Bad - inconsistent prefixes
const userEmail1 = `mygame_${playerId}@loyalteez.app`;
const userEmail2 = `game_${playerId}@loyalteez.app`;  // Different prefix!

3. Handle Special Characters

URL-encode special characters in user IDs:

// If user ID contains special characters
const safeId = encodeURIComponent(userId);
const userEmail = `myplatform_${safeId}@loyalteez.app`;

4. Consider Cross-Platform Users

If a user might be on multiple platforms:

discord_123456789@loyalteez.app  → Wallet A
telegram_987654321@loyalteez.app → Wallet B (different wallet!)

If you want unified wallets, use a consistent identifier:

myplatform_user_abc@loyalteez.app  → Same wallet everywhere

Direct Email Support

You can also use real email addresses:

john@example.com

This works when:

• User has an email on file
• You want users to access via email login

Wallet Access

Users can access their wallets via:

1. perks.loyalteez.app — Login with Discord/Telegram OAuth
2. Email magic link — For direct email identifiers
3. Partner Portal — For brand admins to view

Code Examples

Node.js

function getUserEmail(platform, userId) {
  // Normalize the user ID
  const normalizedId = String(userId).toLowerCase().trim();
  
  // Create the deterministic email
  return `${platform}_${normalizedId}@loyalteez.app`;
}

// Usage
const discordUser = getUserEmail('discord', '123456789');
// → discord_123456789@loyalteez.app

const gamePlayer = getUserEmail('mygame', 'player_42');
// → mygame_player_42@loyalteez.app

Python

def get_user_email(platform: str, user_id: str) -> str:
    """Create deterministic user email for Loyalteez."""
    normalized_id = str(user_id).lower().strip()
    return f"{platform}_{normalized_id}@loyalteez.app"

# Usage
discord_user = get_user_email('discord', '123456789')
# → discord_123456789@loyalteez.app

game_player = get_user_email('mygame', 'player_42')
# → mygame_player_42@loyalteez.app

Verification

The API will accept any valid email format. Wallets are created automatically.

To verify a user has received rewards:

1. Check balance API (if available)
2. Partner Portal Analytics — Search by user email
3. Blockchain explorer — Look up wallet address

Migration Considerations

If you change your identifier scheme:

Old: game_player42@loyalteez.app New: mygame_player_42@loyalteez.app

These create different wallets. Plan migrations carefully:

1. Stick with your original scheme
2. Or implement a migration to transfer balances

Security

• User emails are hashed for wallet derivation
• No PII is stored beyond what's needed
• Wallets are non-custodial (user controls)