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. That way, you can provide a unified user experience for a user across multiple wallets.

For the API reference, view the method signatures in Github.

Linking wallets with privy-node​

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

const privyNode = new PrivyNode(process.env.PRIVY_API_KEY, process.env.PRIVY_API_SECRET);
const userId = '0x123';
const alias = '0x456';
aliasBundle = await privyNode.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');

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 privyNode.link(userId, alias1);
// Returns {userId: "0x123", ["0x456", "0x789"]}.
aliasBundle = await privyNode.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 privyNode.getAliases(userId);
// Returns {userId: "0x123", aliases: ["0x456", "0x789"].
const aliasBundle2 = await privyNode.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.