Skip to main content

​
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.
ApproachUserExchangewalletIdResult
Wronguser-123Binanceuser-123Coinbase connection overwrites Binance
Wronguser-123Coinbaseuser-123
Correctuser-123Binanceuser-123-binanceBoth connections work independently
Correctuser-123Coinbaseuser-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 neededNoYes
ReconstructableYes, rebuild from userId + exchangeNo, must persist
Exposes user IDIn the walletId stringNo
Setup complexityNoneRequires 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
);

​
Next Steps

OAuth2 Integration

Implement the full OAuth2 popup flow with React hooks

Encryption & Security

How Bluvo encrypts and isolates exchange credentials