Privy allows you to set custom metadata on the user object to store any app-specific metadata. This field is a generic JSON object up to 1KB in size. The JSON can contain arbitrary key-value pairs where the key is a string and value is a string, integer, or boolean (ie {username: 'name', isVerified: true, age: 23}).

Use the PrivyClient’s setCustomMetadata method to set the custom metadata field for a user by their DID. As parameters, pass the user’s DID as a string and the JSON object that you wish to set as custom metadata:

const user = await privy.setCustomMetadata('did:privy:XXXXXX', {username: 'name'});

If a matching user is found for the DID and the custom metadata object is valid, the method will return the corresponding User object with updated custom metadata. If no matching user is found, or the custom metadata input is malformed or too large (>1KB), the method will throw an error.

When using the setCustomMetadata function in TypeScript, you can specify a type generic in order to enable type inference on the method like so:

// TypeScript will throw a type error if customMetadata is not of type {key1: string}
const user = await privy.setCustomMetadata<{key1: string}>('did:privy:XXXXXX', customMetadata);

Was this page helpful?