Skip to main content

​
Introduction

Usernames are ENS-compatible identifiers for every World App user, ensuring consistency and easy recognition. For example, when displaying transaction history, show the username instead of the wallet address to make it more user-friendly and private. The usernames service is public, docs can be found here. This will be mostly useful for more advanced use cases.

​
How to get it

To get the user’s username you can either complete Wallet Auth and access the username/profile picture url from MiniKit directly:
Or you can request it manually, using the getUserByAddress method on MiniKit:
You can also look a user up by their username with getUserByUsername:
Both methods return an object with walletAddress, username, and profilePictureUrl properties. The SDK type marks username and profilePictureUrl as optional; callers must also handle null profile values at runtime.
The two lookup methods handle unknown users differently:
  • getUserByAddress(address) preserves the supplied walletAddress. When the service returns no profile, username and profilePictureUrl are null.
  • getUserByUsername(username) maps the service’s unknown-user 404 response to an object whose properties are undefined.
Check for a username before using profile data; a truthy walletAddress alone does not mean a profile exists. These unknown-user responses resolve normally, but network or JSON parsing failures can still reject the promise.
MiniKit.getUserInfo is also available as an alias of getUserByAddress (same signature, same behavior). Other ways involve querying the usernames service.