Skip to main content

Linking wallets

Your user does not just have one wallet. Your UX should not be constrained to a given wallet they use.

Privy enables you to securely alias user ids so you can associate user wallets and other identifiers together in a privacy-preserving way. This enables you to query the same data across multiple identifiers if those identifiers are known to belong to the same user. However, those links are never stored explicitly. That means Privy itself cannot see what identifiers belong to the same user.

This aliasing allows you to provide a unified user experience for a user across multiple wallets.

Linking wallets with privy-node

For example, to link wallet address 0x456 to 0x123:

import {PrivyClient} from '@privy-io/privy-node';

const client = new PrivyClient(process.env.PRIVY_API_KEY, process.env.PRIVY_API_SECRET);
const userId = '0x123';
const alias = '0x456';
aliasBundle = await client.link(userId, alias);
// Returns {userId: "0x123", aliases: ["0x456"]}.
console.log(aliasBundle);

Note that in order to link an alias to a userId, user data must already exist for the given userId. Once an alias is linked, it can be used in place of the user id for any calls requiring a user id:

const userId = '0x123';
// Save email for user.
await client.put(userId, 'email', 'hi@privy.io');

const alias = '0x456';
// Update email for user.
await client.put(alias, 'email', 'hello@privy.io');

// Returns "hello@privy.io" for 0x123's email.
const email = await client.get(userId, 'email');
// Returns "hello@privy.io" for 0x456's email.
const email = await client.get(alias, 'email');

Refer to the API reference for more details on the link method.

Wallet linking is transitive. This means aliases are interchangeable in Privy calls, including for permissions or when creating new aliases. Here's an example.

const userId = '0x123';
const alias1 = '0x456';
const alias2 = '0x789';
// Returns {userId: "0x123", ["0x456"]}.
const aliasBundle1 = await client.link(userId, alias1);
// Returns {userId: "0x123", ["0x456", "0x789"]}.
aliasBundle = await client.link(alias1, alias2);

Listing user aliases

Developers can get back user aliases with the getAliases call. From the above example:

const userId = '0x123';
const alias = '0x456';
// Returns {userId: "0x123", aliases: ["0x456", "0x789"].
const aliasBundle1 = await client.getAliases(userId);
// Returns {userId: "0x123", aliases: ["0x456", "0x789"].
const aliasBundle2 = await client.getAliases(alias);

Deleting user aliases

An alias can be removed by delinking it from the userId :

const userId = '0x123';
const alias = '0x456';
// Deletes the alias.
await privyNode.delink(userId, alias);
// Attempting to use the alias will now fail:
await privyData.fetchData(alias, 'email'); // FAILS.