Manage user groups

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

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

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

await client.users.createMetadata({
  walletAddress: '0x1234567890abcdef1234567890abcdef12345678'
});

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

Best Practices

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

Troubleshooting

Next Steps

Now that you understand user groups, learn how to: