> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bluvo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallet Id

> How to generate and manage walletIds, one per user per exchange

## Overview

A `walletId` is a string you provide to Bluvo to identify a specific user-exchange connection. You control the format, it just needs to be **unique per user per exchange pair**. Every API call that touches a wallet (balances, quotes, withdrawals) is scoped to this identifier.

## The Common Mistake

<Warning>
  A `walletId` is **not** a user ID. Each walletId maps to a single set of encrypted exchange credentials. Reusing the same walletId for two exchanges will **overwrite** the first connection.
</Warning>

| Approach    | User     | Exchange | walletId            | Result                                 |
| ----------- | -------- | -------- | ------------------- | -------------------------------------- |
| **Wrong**   | user-123 | Binance  | `user-123`          | Coinbase connection overwrites Binance |
| **Wrong**   | user-123 | Coinbase | `user-123`          |                                        |
| **Correct** | user-123 | Binance  | `user-123-binance`  | Both connections work independently    |
| **Correct** | user-123 | Coinbase | `user-123-coinbase` |                                        |

If a user connects three exchanges, you need **three** distinct walletIds, one for each connection.

## The Simple Pattern

The easiest approach is a deterministic format that combines your user ID with the exchange name:

```typescript theme={null}
const walletId = `${userId}-${exchange}`;
// "user-123-binance", "user-123-coinbase", "user-123-kraken"
```

This is the recommended default. It's stateless, reconstructable from data you already have, and requires no additional database lookups.

### Alternative: Random UUID

If you prefer not to encode user IDs into the walletId, generate a `crypto.randomUUID()` per connection and store the mapping in your database:

```typescript theme={null}
const walletId = crypto.randomUUID();
// "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
// Store: { userId, exchange, walletId } in your DB
```

### Trade-offs

|                  | Deterministic (`userId-exchange`)   | Random UUID              |
| ---------------- | ----------------------------------- | ------------------------ |
| DB lookup needed | No                                  | Yes                      |
| Reconstructable  | Yes, rebuild from userId + exchange | No, must persist         |
| Exposes user ID  | In the walletId string              | No                       |
| Setup complexity | None                                | Requires a mapping table |

For most integrations, the deterministic pattern is the simplest path forward.

## Code Examples

<CodeGroup>
  ```typescript Server-side (SDK) theme={null}
  import { createClient } from "@bluvo/sdk-ts";

  const client = createClient({
    orgId: process.env.BLUVO_ORG_ID!,
    projectId: process.env.BLUVO_PROJECT_ID!,
    apiKey: process.env.BLUVO_API_KEY!,
  });

  // One walletId per user per exchange
  const userId = "user-123";
  const exchange = "binance";
  const walletId = `${userId}-${exchange}`;

  const { workflowRunId } = await client.wallet.connect(
    exchange,
    walletId
  );
  ```

  ```typescript Client-side (React hook) theme={null}
  "use client";

  import { useBluvoFlow } from "@bluvo/react";

  // Generate a walletId for the selected exchange
  function getWalletId(userId: string, exchange: string) {
    return `${userId}-${exchange}`;
  }

  export default function ConnectExchange({ userId }: { userId: string }) {
    const flow = useBluvoFlow({ /* ...config */ });

    const [selectedExchange, setSelectedExchange] = React.useState("");

    const handleConnect = () => {
      flow.startWithdrawalFlow({
        exchange: selectedExchange,
        walletId: getWalletId(userId, selectedExchange),
      });
    };

    // ...render UI based on flow state
  }
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="OAuth2 Integration" icon="lock" href="/learn/oauth2-integration">
    Implement the full OAuth2 popup flow with React hooks
  </Card>

  <Card title="Encryption & Security" icon="shield-halved" href="/learn/security">
    How Bluvo encrypts and isolates exchange credentials
  </Card>
</CardGroup>