---
title: "Manage user groups"
description: "Learn how to handle multiple wallet addresses per user using Snag's user group feature for seamless multi-wallet support"
keywords: ["user groups loyalty", "user segmentation Web3", "loyalty cohorts", "targeted rewards"]
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://docs.snagsolutions.io/llms.txt). Append `.md` to any page URL for its markdown version.

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

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

### 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

<Warning>
  **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".
</Warning>

## 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:

<RequestExample>

```bash cURL
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"
  }'
```

</RequestExample>

<ResponseExample>

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

</ResponseExample>

### Using the Snag SDK

```javascript
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:

<RequestExample>

```bash cURL
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"
  }'
```

</RequestExample>

<ResponseExample>

```json Success
{
  "message": "Success"
}
```

</ResponseExample>

```javascript
// 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:

```javascript
// 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

<Steps>
  <Step title="Enable user groups">
    Enable the user group feature in your Snag dashboard by navigating to **Customisation → User Profiles** and enabling multiple wallet connections.
  </Step>
  <Step title="Create users">
    Create individual users for each wallet address using the metadata endpoint.

    ```javascript
    await client.users.createMetadata({
      walletAddress: '0x1234567890abcdef1234567890abcdef12345678'
    });
    ```
  </Step>
  <Step title="Connect to groups">
    Connect each wallet to the appropriate user group.

    ```javascript
    await client.users.connect({
      organizationId: 'your-org-id',
      walletAddress: '0x1234567890abcdef1234567890abcdef12345678',
      walletType: 'evm',
      websiteId: 'your-website-id'
    });
    ```
  </Step>
  <Step title="Verify synchronization">
    Check that metadata is synced across all wallets in the group.
  </Step>
</Steps>

## Best Practices

<Tip>
  **Group Management**: Create user groups based on your application's needs - typically one group per user identity.
</Tip>

<Tip>
  **Wallet Types**: Always specify the correct wallet type when connecting users to ensure proper chain support.
</Tip>

<Tip>
  **Metadata Updates**: When updating user metadata, the changes will automatically sync across all wallets in the group.
</Tip>

<Warning>
  **Disconnection Impact**: When disconnecting a wallet from a group, the wallet becomes a standalone user and loses access to shared metadata and loyalty benefits.
</Warning>

## 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

<Info>
  For more details on how user groups work with the loyalty system, see our [Multi Wallet Support](https://docs.snagsolutions.io/loyalty/multi-wallet-support) guide.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Error: 'This website does not support multiple wallet connections, please contact support'">
    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.
  </Accordion>
</AccordionGroup>

## Next Steps

Now that you understand user groups, learn how to:

<Card title="Connect Social Accounts" icon="share" href="/loyalty/development/connect-social-accounts">
  Integrate social media platforms with your users for enhanced loyalty features.
</Card>

{' '}