> ## Documentation Index
> Fetch the complete documentation index at: https://bluvo.mintlify.site/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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.