​
Overview

In blockchain-based loyalty programs, users often have multiple wallet addresses across different networks. Snag’s multi-wallet support allows users to connect multiple wallets to a single user group, enabling:
  • Aggregated points display - See combined point balances across all connected wallets
  • Group-based spending - Spend points from the collective balance of all linked wallets
  • Pooled token holdings - Combine NFT/token holdings for higher-tier multiplier qualification
  • Shared multiplier benefits - Access the best multipliers earned by any wallet in the group
This feature creates a seamless experience for users with multiple wallets while maintaining individual tracking for each wallet address.

​
How User Groups Work

​
Points Aggregation

While Snag treats each wallet address as a separate user, connecting wallets through a user group enables points aggregation across all wallets in that group: Example:
  • User A has 100 points in their primary wallet
  • User B has 300 points in their secondary wallet
  • When connected in the same user group, both users will see a total of 400 points

​
Shared Points Spending

All wallets in a user group share access to the combined point balance when redeeming rewards: Example:
  • User A (100 points) wants to redeem a reward costing 350 points
  • Since User A’s wallet is connected to User B’s wallet (300 points) in a group
  • User A can spend 350 points from the combined 400-point balance
  • After redemption, the system intelligently deducts points from both wallets:
    • User A’s wallet: 0 points (depleted its 100 points)
    • User B’s wallet: 50 points (depleted 250 of its 300 points)

​
Token Holdings Pooling for Multipliers

For multiplier rules based on token holdings, assets across all connected wallets are pooled to determine qualification level: Example:
  • A multiplier rule gives:
    • 1.5x multiplier for holding 10-14 NFTs
    • 2x multiplier for holding 15+ NFTs
  • User A holds 10 NFTs and User B holds 5 NFTs
  • When connected in the same group:
    • Their combined holdings (15 NFTs) qualify for the 2x multiplier
    • Both users receive the 2x multiplier benefit
Important: Token pooling only applies to multiplier-type rules, not to points-based token holding rules.

​
Multiplier Selection Logic

When multiple wallets in a group earn different multipliers for the same rule type:
  • The system selects the highest multiplier of each type
  • Multipliers are not stacked within the same multiplier type
  • Each multiplier type is counted once with the highest value available in the group
Example:
  • User A has a 1.5x multiplier for completing Discord quests
  • User B has a 2x multiplier for the same Discord quest type
  • Both users will benefit from the 2x multiplier (the highest in the group)

​
Setting Up Multi-wallet Support

​
Technical Implementation

The multi-wallet functionality works through a userGroupId property in the user’s account metadata, which connects different wallets to the same group.

​
Enabling Multi-wallet Connections

To use multi-wallet functionality:
  1. Contact Support: Multi-wallet support must be enabled by our team for your project
  2. Connection Limits: Projects can be configured to allow:
    • One additional wallet (total of 2 wallets in a group)
    • Up to 3 additional wallets (total of 4 wallets in a group)

​
User Experience

Once enabled, users can connect additional wallets to their account through the profile settings:
  1. User signs in with their primary wallet
  2. From the profile page, they select “Connect Additional Wallet”
  3. User connects their additional wallet using standard wallet connection flow
  4. The system verifies ownership and adds the wallet to the user group
  5. Points and holdings are immediately aggregated across all wallets in the group
  6. Each user in the group maintains their own User metadata that can be updated and tracked individually

​
API Endpoints for Multi-wallet Support

​
Updating User Metadata

Use the POST /api/users/metadatas endpoint to set or update user group connections. You can use either:
  • userGroupId - Snag’s internal identifier for the user group
  • userGroupExternalIdentifier - Your custom external identifier for the group
Using userGroupExternalIdentifier allows you to maintain your own mapping between user groups and your external systems: 
{
  "walletAddress": "0x123...",
  "userGroupExternalIdentifier": "YOUR_SYSTEM_GROUP_ID_12345"
}
Note: When using userGroupExternalIdentifier, Snag will create a userGroupId internally and associate this external identifier with it. This allows you to reference user groups using your own identifiers in subsequent API calls.

​
Fetching User Group Data

The GET /api/loyalty/accounts endpoint allows you to fetch points balances and other data for all wallets in a group by providing either:
  • userGroupId parameter for Snag’s internal group ID
  • userGroupExternalIdentifier parameter for your custom external identifier

​
Best Practices

  1. Authenticate Wallet Ownership: Always verify that a user owns all wallets they attempt to connect
  2. Clear User Communication: Explain to users how points aggregation works across their connected wallets
  3. Visual Indicators: Consider showing which wallet contributed what portion of the total points balance

​
Limitations

  • Maximum of 4 wallets per user group (your specific limit may be lower based on configuration)
  • Token holding pooling only applies to multiplier rules, not to points-based token holding rules
  • Leaderboard Display: Currently, leaderboards show each individual wallet as a separate entry.