Handle wallets in a user account
Overview
This guide walks you through the ways to handle the different wallets associated with a user's Ronin Waypoint account, which includes keyless and EOA wallets.
About user wallets
A user's Ronin Waypoint account includes the following information:
{
"account.wallet.default":"wallet.secondary", // Default wallet for the account
"account.wallet.identity":"0x123...", // Keyless wallet address
"account.wallet.identity.has_backup":"true", // Indicates if the keyless wallet has a backup
"account.wallet.secondary":"0x456...", // Optional EOA wallet linked to the account
"profile.name":"Lunacian" // User's profile name
}
Key | Description | Use case |
---|---|---|
account.wallet.default | The default wallet for the user's account as set by the user on the account management page. | Use this wallet as the primary wallet for the user's account. |
account.wallet.identity | A keyless wallet that the user created during the Ronin Waypoint onboarding process, or by using email and password or social login options in the Ronin Wallet mobile app or browser extension. | Treat this wallet as the user's spending account for in-game transactions and purchases, enabling the user to purchase, swap, and mint assets across Ronin games. It also supports actions like collecting daily check-ins and sending tokens or NFTs to other users. |
account.wallet.identity.has_backup | Indicates if a shard of the keyless wallet is backed up to the Sky Mavis server. | The service will prompt the user to continue the setup process if the wallet isn't backed up. |
account.wallet.secondary | An optional EOA (externally owned account) wallet—a seed phrase Ronin Wallet that is present if the user linked it to their Ronin Waypoint account. | Treat this wallet as the user's savings account for staking tokens or NFTs for rewards and governance, and storing valuable assets. |
profile.name | The user's display name that appears in games such as Axie Infinity. | Use this name to personalize the user experience. |
Ways to set up a keyless wallet
If the user doesn't have a keyless account.wallet.identity
wallet, they can set it up in one of the following ways:
- By going through the Ronin Waypoint onboarding process on the waypoint.roninchain.com page. You can read more about this process on the About user journey page.
- By going through the onboarding process in a game or dApp that supports Ronin Waypoint. For example, Axie Classic or the Ronin Wallet mobile app or browser extension. For information on using the Ronin Wallet, see Creating Wallet with Email Address or Social Account.
Ways to link an EOA wallet
The user can link an account.wallet.secondary
address to their Ronin Waypoint account by connecting it on the account management page. After linking, the user can't disconnect the wallet for the next 30 days. Similarly, if a user recently disconnected a Ronin Wallet address from their account, they can't reconnect the wallet to another account for the next 30 days. The user can, however, reconnect it to the old account immediately, as long as the account isn't linked to a different wallet yet.
Setting a default wallet
The user has the option to set either keyless or EOA wallet as the default wallet for their account on the account management page. The keyless wallet is the default wallet if the user doesn't link an EOA wallet.
Prerequisites
- An app created in the Developer Console.
- Permission to use the Sky Mavis Account service. Request in the Developer Console under your app > App Permission > Sky Mavis Account (OAuth 2.0) > Request Access.
- The user ID of the Ronin Waypoint account whose information you want to retrieve. You can retrieve this ID from the
sub
claim in the ID token after the user connects their Ronin Waypoint account to your app.
Steps
Step 1. Retrieve user account details
To retrieve user information and wallet addresses, send a GET request to the user profile endpoint with the user ID.
Make sure to send the request server-side to protect your API key from being exposed and misused.
Request:
curl --location 'https://api-gateway.skymavis.com/account/v2/rpc/get-user-profile/{user_id}' \
--header 'X-api-key: {YOUR_API_KEY}' \
--header 'X-app-id: {YOUR_APP_ID}'
Parameters:
{user_id}
: the user ID of the account you want to retrieve information for. For example,1eda5fc0-76e1-6de4-8449-b3a0fde29125
.{YOUR_API_KEY}
: your app's API key from the Developer Console.{YOUR_APP_ID}
: your app's unique ID from the Developer Console.
Response:
{
"account.wallet.default":"wallet.secondary", // Default wallet for the account
"account.wallet.identity":"0x123", // Keyless wallet address
"account.wallet.identity.has_backup":"true", // Indicates if the keyless wallet has a backup
"account.wallet.secondary":"0x456...", // Optional EOA wallet linked to the account
"profile.name":"Lunacian" // User's profile name
}
Step 2. Handle wallets
Depending on the number of wallet addresses associated with a Ronin Waypoint account, you can choose one of the following implementations:
Number of wallet addresses | Suggested implementation |
---|---|
One address | Query this wallet for all transactions and authentication needs. |
Two addresses | Choose one of the following:
|