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	[email protected]
Telegram	telegram_{user_id}@loyalteez.app	[email protected]
Your Game	yourgame_{player_id}@loyalteez.app	[email protected]
Your App	myapp_{user_id}@loyalteez.app	[email protected]
Website	mysite_{user_id}@loyalteez.app	[email protected]
Direct Email	[email protected]	[email protected]

Deterministic Wallets

The same identifier always maps to the same wallet:

[email protected] → 0xABC...
[email protected] → 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:

[email protected]  (immutable Discord ID)
[email protected]  (database primary key)

Bad:

[email protected]  (usernames can change)
[email protected]  (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:

[email protected]  → Wallet A
[email protected] → Wallet B (different wallet!)

If you want unified wallets, use a consistent identifier:

[email protected]  → Same wallet everywhere

Direct Email Support

You can also use real email addresses:

[email protected]

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');
// → [email protected]

const gamePlayer = getUserEmail('mygame', 'player_42');
// → [email protected]

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')
# → [email protected]

game_player = get_user_email('mygame', 'player_42')
# → [email protected]

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: [email protected] New: [email protected]

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)