Skip to main content
In Snag, each wallet address represents an individual user. To support users with multiple wallets, we provide a User Group feature that allows you to connect multiple wallet addresses together, treating them as a single user across your loyalty system.

​
Understanding User Groups

A user group can contain multiple users (wallet addresses) and syncs all user metadata, including social handles, across all connected wallets.

​
Why User Groups?

  • Multiple Wallets: Users often have wallets on different chains (Ethereum, Polygon, Solana, etc.)
  • Shared Identity: All wallets in a group share the same social accounts and metadata
  • Unified Loyalty: Points, badges, and rewards are tracked across all wallets in the group
  • Seamless Experience: Users don’t need to reconnect social accounts for each wallet
Enable User Groups First: Before using the user group feature, you must enable it in your Snag dashboard. Navigate to Customisation → User Profiles and enable multiple wallet connections. If this feature is not enabled, the POST /api/users/connect endpoint will return an error: “This website does not support multiple wallet connections, please contact support”.

​
Creating and Managing User Groups

​
Connecting a User to a Group

Use the POST /api/users/connect endpoint to add a wallet address to a user group: 
curl -X POST 'https://admin.snagsolutions.io/api/users/connect' \
  -H 'x-api-key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "organizationId": "123e4567-e89b-12d3-a456-426614174001",
    "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "walletType": "evm",
    "websiteId": "123e4567-e89b-12d3-a456-426614174000"
  }'

{
  "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2023-10-01T12:34:56Z",
  "updatedAt": "2023-10-05T15:30:00Z"
}

​
Using the Snag SDK

import SnagSolutions from '@snagsolutions/sdk'

const client = new SnagSolutions({
  apiKey: 'your-api-key-here',
})

// Connect a user to a group
const response = await client.users.connect({
  organizationId: '123e4567-e89b-12d3-a456-426614174001',
  walletAddress: '0x1234567890abcdef1234567890abcdef12345678',
  walletType: 'evm',
  websiteId: '123e4567-e89b-12d3-a456-426614174000',
})

console.log('User connected to group:', response.id)

​
Disconnecting a User from a Group

To remove a wallet address from a user group, use the POST /api/users/disconnect endpoint: 
curl -X POST 'https://admin.snagsolutions.io/api/users/disconnect' \
  -H 'x-api-key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "userId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "websiteId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
  }'

{
  "message": "Success"
}

// Disconnect a user from a group
const response = await client.users.disconnect({
  organizationId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
  userId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
  websiteId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
})

console.log('User disconnected:', response.message)

​
Supported Wallet Types

When connecting users to groups, specify the wallet type:
  • evm - Ethereum and EVM-compatible chains
  • svm - Solana Virtual Machine
  • ton - The Open Network
  • sui - Sui blockchain
  • cosmos - Cosmos ecosystem chains

​
Metadata Synchronization

When a user/wallet address is connected to a group, all user metadata including social handles gets synced across all users in that group: 
// Example: User has wallets on Ethereum and Polygon
const ethereumWallet = '0x1234567890abcdef1234567890abcdef12345678'
const polygonWallet = '0xabcdef1234567890abcdef1234567890abcdef12'

// Connect both wallets to the same group
await client.users.connect({
  organizationId: 'your-org-id',
  walletAddress: ethereumWallet,
  walletType: 'evm',
  websiteId: 'your-website-id',
})

await client.users.connect({
  organizationId: 'your-org-id',
  walletAddress: polygonWallet,
  walletType: 'evm',
  websiteId: 'your-website-id',
})

// Now both wallets share the same social accounts and metadata

​
User Group Workflow

1

Enable user groups

Enable the user group feature in your Snag dashboard by navigating to Customisation → User Profiles and enabling multiple wallet connections.
2

Create users

Create individual users for each wallet address using the metadata endpoint.
await client.users.createMetadata({
  walletAddress: '0x1234567890abcdef1234567890abcdef12345678'
});
3

Connect to groups

Connect each wallet to the appropriate user group.
await client.users.connect({
  organizationId: 'your-org-id',
  walletAddress: '0x1234567890abcdef1234567890abcdef12345678',
  walletType: 'evm',
  websiteId: 'your-website-id'
});
4

Verify synchronization

Check that metadata is synced across all wallets in the group.

​
Best Practices

Group Management: Create user groups based on your application’s needs - typically one group per user identity.
Wallet Types: Always specify the correct wallet type when connecting users to ensure proper chain support.
Metadata Updates: When updating user metadata, the changes will automatically sync across all wallets in the group.
Disconnection Impact: When disconnecting a wallet from a group, the wallet becomes a standalone user and loses access to shared metadata and loyalty benefits.

​
Integration with Loyalty System

User groups work seamlessly with Snag’s loyalty system:
  • Points Tracking: Loyalty points are tracked across all wallets in a group
  • Rule Completion: Social account connections and other rule completions apply to all wallets
  • Rewards: Badges and rewards are shared across the entire group
  • Leaderboards: Users appear as a single entity regardless of which wallet they use
For more details on how user groups work with the loyalty system, see our Multi Wallet Support guide.

​
Troubleshooting

If you receive this error when calling the POST /api/users/connect endpoint, it means the user group feature is not enabled for your website.Solution:
  1. Navigate to your Snag dashboard
  2. Go to Customisation → User Profiles
  3. Enable the multiple wallet connections feature
  4. Retry your API call
Once enabled, you’ll be able to connect multiple wallet addresses to user groups without encountering this error.

​
Next Steps

Now that you understand user groups, learn how to:

Connect Social Accounts

Integrate social media platforms with your users for enhanced loyalty features.