Wallet Id

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

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.

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:

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:

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

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
);

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

Get Started

Learn

SDK

More

Overview

The Common Mistake

The Simple Pattern

Alternative: Random UUID

Trade-offs

Code Examples

Next Steps

OAuth2 Integration

Encryption & Security

​Overview

​The Common Mistake

​The Simple Pattern

​Alternative: Random UUID

​Trade-offs

​Code Examples

​Next Steps

OAuth2 Integration

Encryption & Security

Overview

The Common Mistake

The Simple Pattern

Alternative: Random UUID

Trade-offs

Code Examples

Next Steps