📘

The users mentioned in this doc doesn't refer to normal users. They refer to the Merchants or Game Studios or developers that have integrated SphereOne. They are adding these wallets on their users' behalf.

🚧

This functionality is only available in the WebSDK at the moment.

Add External Wallet

Upon the initial sign-in of a new user, SphereOne automatically generates wallets for them, streamlining the user experience and facilitating immediate transactions.

Existing users can effortlessly utilize these automatically created SphereOne Wallets to conduct various transactions within the platform.

Recovering External Wallets into SphereOne

Methodology: External wallets can be recovered into SphereOne, providing additional flexibility and options for fund management.

Procedure: - This can be accomplished through the SphereOne Wallet site, utilizing a method akin to that of Metamask.

Benefit: Recovering an external wallet within SphereOne enables the platform to draw funds from it, enhancing transactional capabilities.

Adding an External Wallet without Recovery

User Preference: In instances where users prefer not to recover their wallet into SphereOne but desire to designate the wallet as a destination for funds (e.g., via an on-ramp provider), this is permissible.

Implementation: Users can add an external wallet into SphereOne utilizing the WebSDK, ensuring that the wallet can receive funds without being fully recovered into the SphereOne ecosystem.

Access: - Wallets added by this method will have a read-only access. This means that SphereOne can only view the wallet's balances and cannot pull funds for actual payment. Instead, with read-only access, the added wallet can only be referenced as the receiver or destination in a payment flow.

We will briefly discuss how to add a wallet by the SphereOne WebSDK. The steps to initialize the SphereOne WebSDK can be found here: SphereOne WebSDK.

But a quick recap:

To install the SphereOne WebSDK via npm/yarn, or get the latest updates:

npm install github:SphereGlobal/WebSDK#main

Initializing the WebSDK:

import WebSDK, { LoginBehavior } from "websdk";

const clientId = "your-client-id";
const redirectUri = "your-website-redirect-uri";
const apiKey = "your-merchant-api-key";

export const sphereoneSdk = new WebSDK(clientId, redirectUri, apiKey, LoginBehavior.REDIRECT);

Login with the WebSDK:

import { sphereoneSdk } from "./your-implementation-file";

// login function for button onClick
const login = async () => {
  try {
    await sphereoneSdk.login();
  } catch (e: any) {
    console.error(e);
  }
};

Listening to the Authentication Result:

import { sphereoneSdk } from "./your-implementation-file";

// something to track user's sign-in state with SphereOne on client-side
const [isLoggedIn, setIsLoggedIn] = useState(false);

// hook to listen for authentication response
useEffect(() => {
  const handleAuth = async () => {
    const authResult: any = await sphereoneSdk.handleCallback();
    if (authResult.access_token) {
      const { access_token, profile } = authResult;
      setIsLoggedIn(true); // handle authentication with your database
    } else {
      setIsLoggedIn(false);
    }
  };
  handleAuth();
}, []);

// login function for button onClick
const login = async () => {
  try {
    await sphereoneSdk.login();
  } catch (e: any) {
    console.error(e);
  }
};

Adding an external wallet to WebSDK still requires the user to be authenticated. This way, SphereOne can identify the user to add the wallet.

To add an external wallet to SphereOne, we need to call WebSDK's method: addWallet().

import { sphereoneSdk } from "./your-implementation-file";
import { SupportedChains } from "websdk";

// ...

const addWallet = async () => {
  try {
    await sphereoneSdk.addWallet({
      walletAddress: "0xb79b86C766708bF861a83FA308107F712345678", // example EVM-based wallet address
      chains: [SupportedChains.BINANCE] // adding BINANCE CHAIN only
      label: "MY WALLET" // optional
    });
  } catch (e: any) {
    console.error(e);
  }
}

By calling addWallet(), user would need:

• walletAddress - The external wallet they wished to add into SphereOne.
• chains - The list of blockchains that this external wallet can be used for. User can leverage the SupportedChains enum within the WebSDK.
• label - Optional name or title that user may want to add to their external wallet to identify itself from other wallets.

Create Charge

In instances where there is a necessity to create a charge for an external wallet (i.e., a wallet not within your SphereOne account), the isDirectTransfer field can be utilized within the createCharge endpoint in the SDK, and also specifying a toAddress in the requestBody of `createCharge.

The toAddress indicates the destination wallet address that will be receiving the payment. If not specified, then it is the standard createCharge and payment flows, where the destination wallet address is determined based on the merchant-api-key set into the SDK.

Below is an example of creating a charge, with the isDirectTransfer field set to true.

const charge = await sphereoneSdk.createCharge({
  chargeData: {
    chain: SupportedChains.SOLANA,
    symbol: "SOL",
    tokenAddress: "So11111111111111111111111111111111111111112",
    successUrl: "https://your-website.com/success",
    cancelUrl: "https://your-website.com/cancel",
    items: [
      {
        name: "Your Item",
        image: "https://your-image-url.somewhere.com",
        amount: 0.9, // amount of the individual item
        quantity: 1
      }
    ],
    toAddress: "0x53107F751291E57120230EFb50B0B67Da7D5bDF2", // the wallet that will receive the tokens
    amount: 0.9 // amount of tokens you are sending
  },
  isDirectTransfer: true // isDirectTransfer: this means that you are sending the tokens to the toAddress and not to your wallet in SphereOne account
});

With this flag set, you can create a charge with your merchant-api-key and send the tokens to any another wallet address.

To do so remember that you need a Product Api Key that is only for merchants that have completed our KYB process.

From here, calling payCharge should follow the same steps as before.