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"
}
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

​
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

Create users

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

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'
});
3

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.

​
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.