Coin Wallet Embed SDK

Your organization can use Skyfire's Coin Wallet Embed SDK to let your organization users fund their coin wallets from inside your own application. By default, organization users fund their wallets in the Skyfire Dashboard. With the SDK, they view their balance and add funds through a secure, hosted flow embedded in your application, without your organization building its own funding interface.

The SDK handles:

Authenticating the organization user's session
Running the funding checkout
Retrieving and refreshing the wallet balance

Before you start: This page is written for your organization's administrators. It assumes Skyfire has onboarded your organization and that you have an administrator user API key. Skyfire must also add your domain to its allowlist, because the embedded wallet loads only on approved domains. Send the exact domain, including any subdomain, to [email protected].

1. Install the SDK

npm install @skyfire-xyz/usdc-wallet-embed-sdk

2. Request a session token from your backend

When an organization user opens the page that hosts the embedded wallet, the SDK needs a session token for that user. Your backend requests the session token from Skyfire, and returns it to the SDK. Keep this request on your backend. Never expose an administrator user API key to the browser.

POST /api/v1/auth/skyfire-session-token, with an administrator user API key and the organization user's ID. The response is the session token, as a string.

const BASE_URL = 'https://api.skyfire.xyz' // or https://api-sandbox.skyfire.xyz

export async function getSkyfireSessionToken(userId: string) {
  const res = await fetch(`${BASE_URL}/api/v1/auth/skyfire-session-token`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'skyfire-api-key': process.env.ORG_ADMIN_API_KEY!,
    },
    body: JSON.stringify({ userId }),
  })
  return res.text()
}

A session token expires after 5 minutes. The SDK requests a new one whenever it needs to, so always fetch a fresh token rather than caching one.

3. Embed the wallet in your frontend

Wrap the EmbeddedIframe component in an EmbeddedIframeProvider, and point fetchClientSecret at your backend route.

import { EmbeddedIframeProvider, EmbeddedIframe, EmbeddedIframeOptions } from '@skyfire-xyz/usdc-wallet-embed-sdk'

export default function Wallet({ userId }: { userId: string }) {
  const options: EmbeddedIframeOptions = {
    fetchClientSecret: async () =>
      (await fetch(`/internal/skyfire-wallet-session?userId=$USERID`, { method: 'POST' })).text(),
    onEvent: async (type: unknown, data: unknown) => {
      console.log('Wallet event:', type, data)
    },
    environment: 'sandbox', // or 'production'
  }

  return (
    <EmbeddedIframeProvider options={options}>
      <EmbeddedIframe />
    </EmbeddedIframeProvider>
  )
}

Option	Required	Description
`fetchClientSecret`	Yes	A function that returns a fresh session token from your backend.
`onEvent`	Yes	A function the SDK calls when a wallet event occurs, such as a completed payment.
`environment`	Yes	`sandbox` or `production`. Must match the environment your backend requests session tokens from.
`buttonText`	No	The funding button's label. Defaults to `Fund Wallet`.
`redirectUrl`	No	Where the checkout page sends the organization user after payment. Defaults to your application's origin.
`customUrl`	No	Overrides the SDK's base URL, for development environments.

For the base URL of each environment, see Environments.

4. Organization users fund their wallets

Once the wallet is embedded, the SDK runs the funding flow for each organization user:

The SDK uses the session token to display the organization user's wallet balance.
The organization user selects the funding button. The SDK opens a Skyfire checkout page.
The organization user completes payment. The checkout page redirects them to redirectUrl.
The SDK refreshes the balance automatically, and calls onEvent.