Ronin Waypoint Web SDK

Overview

The Ronin Waypoint Web SDK lets developers integrate the account and wallet features of the Ronin Waypoint service into browser-based games developed with JavaScript or TypeScript. After the integration, users can sign in to your game with their Ronin Waypoint account and connect their keyless wallet for instant in-game transactions.

The SDK provides the RoninWaypointWallet, an EIP-1193-compatible wallet provider, letting developers use the standard JavaScript Ethereum libraries, such as Ethers.js, web3.js, or viem.

GitHub repository: skymavis/waypoint-js.

Try Ronin Waypoint in the playground

Experience Ronin Waypoint in the Ronin Waypoint playground. After creating a keyless wallet, fund it with testnet RON tokens from the Ronin Faucet. For a more detailed explanation, see the User journey page.

Features

• Authorize users: let users sign in to your app with Ronin Waypoint to connect their keyless wallet and an optional externally owned account (EOA) wallet.
• Send transactions: transfer RON, ERC-20 tokens, and make contract calls for in-game transactions.
• Sign messages and typed data: prove ownership of a wallet or sign structured data.

Prerequisites

Tools and libraries:

• Node.js v20 or later.
• npm or yarn for package installation.
• Next.js v14 or later.
• To run the demo app, pnpm v8 or later.

Permissions:

• 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.
• A client ID that you can find in the Developer Console under Products > Waypoint Service > CLIENT ID (APPLICATION ID).
• A redirect URI registered in the Developer Console under Products > Waypoint Service > REDIRECT URI.

For more information about the initial setup, see Get started.

Steps

Step 1. Install the SDK

To install the SDK, use the following command:

npm install @sky-mavis/waypoint
# or
yarn add @sky-mavis/waypoint
# or
pnpm install @sky-mavis/waypoint

Step 2. Initialize the SDK

From the SDK, import RoninWaypointWallet and pass the required parameters to create a wallet provider for interacting with Ronin Waypoint.

import { RoninWaypointWallet } from "@sky-mavis/waypoint"

const idWalletProvider = RoninWaypointWallet.create({
  // Replace with the client ID from the Developer Console
  clientId: "<YOUR_CLIENT_ID>",
  // Specify the chain ID: 2021 for Saigon testnet, 2020 for Ronin mainnet
  chainId: chainId,
})

Parameters:

• clientId: the client ID registered in the Developer Console.
• chainId: the ID of the Ronin chain you want to connect to. Use 2021 for the Saigon testnet and 2020 for the Ronin mainnet.

Step 3. Authorize a user

Initializes the authorization process, allowing a user to sign in or sign up for a Ronin Waypoint account, and connect their wallet. Returns an ID token and the user's keyless wallet address. Two methods are available for authorizing users: popup (default) and redirect. See the popup code example and redirect code example.

For projects with a backend system, you can use this function for authorization. If you only need to interact with the user's keyless wallet, you can skip this step.

import { authorize } from "@sky-mavis/waypoint"

const result = await authorize({
  clientId: "<YOUR_CLIENT_ID>",
  /* redirectUrl: "http://localhost/authorize/waypoint" // If you use the redirect flow */
})

console.debug(result); // { accessToken: '<id_token>', address: '<user_address>' }

Parameters:

• clientId: the client ID registered in the Developer Console.

Returns a promise that resolves to an object containing:

• accessToken: the ID token that contains encoded user information.
• address: the user's keyless wallet address.

Step 4. Validate the ID token

After receiving the ID token from the authorization response, validate it and issue an access token to allow access to your server's resources. For more information, see Validate ID token.

Step 5. Interact with the wallet

After the user connects their wallet, you can interact with it using the wallet provider. The provider is compatible with the EIP-1193 standard, allowing you to use common Ethereum libraries to interact with the blockchain.

Ethers.js (v5)

import * as ethers from "ethers"

const provider = new ethers.providers.Web3Provider(provider)

web3.js

import Web3 from "web3"

const web3 = new Web3(provider)

viem

import { createWalletClient, custom } from "viem"
import { saigon } from "viem/chains"

const walletClient = createWalletClient({ chain: saigon, transport: custom(provider) })

Standalone usage

You can also use the SDK for standalone wallet operations:

const accounts = await provider.request<string[]>({ method: "eth_requestAccounts" });

if (accounts.length) {
  const balance = await provider.request<string>({
    method: "eth_getBalance",
    params: [accounts[0], "latest"]
  });
  console.log("Account Balance:", balance);
}

Step 6. Test and verify the integration

To verify that your integration is working, test the features in your app by authorizing users and interacting with their wallets. For more use cases and code examples, refer to the playground source code.

Reference

FAQ

Where can I find the client ID?

To find your app's client ID, open the Developer Console, then click Waypoint Service, and then in the Client credentials section, locate the CLIENT ID (APPLICATION ID) field.

Where can I find the chain ID?

The chain ID is 2020 for the Ronin mainnet and 2021 for the Saigon testnet.

Can I use the Web SDK to call functions on smart contracts?

Yes, you can. The RoninWaypointWallet provider is compatible with the EIP-1193 standard. This means you can use the contract call functions provided by any JavaScript or TypeScript Ethereum interface:

• Web3.js contract methods
• ethers.js Contract API
• viem Contract Instances