Credits Wallet Embed SDK

Skyfire's Credits Wallet Embed SDK lets Skyfire Enterprise Customers embed wallet funding directly into their own application, through a secure, hosted flow. The SDK handles:

• Session authentication
• Wallet top-up orchestration
• Wallet balance retrieval and refresh

Use this SDK if you want end users to fund their wallets directly inside your app, and you'd rather use a hosted checkout flow than build your own funding UI.

Installation

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

Prerequisites

1. Become a Skyfire Enterprise Customer

The SDK is available to Skyfire Enterprise Customers. Enterprise status lets you show end users their wallet balances and let them top up their wallets.

2. Whitelist your domain

The embedded wallet iframe only loads on approved domains. This prevents unauthorized sites from embedding the wallet, and ensures payment redirects and session tokens are handled safely.

Provide the exact domain, including subdomain, where the SDK will be embedded.

Please reach out to [email protected] to whitelist your domain before using the SDK.

How it works

1. Your backend uses a Skyfire Enterprise Admin User API key and the user ID of your Skyfire Enterprise end user to request a session token from Skyfire.
2. The SDK uses that session token to fetch the end user's Buyer Agent balance.
3. When the end user clicks the top-up button, the SDK requests a payment checkout URL from the Skyfire API.
4. The end user completes payment on that checkout page.
5. The checkout page redirects the end user back to your application.
6. The SDK refreshes and displays the updated wallet balance automatically.

Basic example

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

const ENTERPRISE_ADMIN_API_KEY = 'your-enterprise-admin-key'
const ENV = 'sandbox' // or 'production'

const BASE_URLS = {
  sandbox: 'https://api-sandbox.skyfire.xyz',
  production: 'https://api.skyfire.xyz',
}

const baseUrl = BASE_URLS[ENV]

async function functionToGetSkyfireUserSession(userId: string) {
  const sessionTokenUrl = `${baseUrl}/api/v1/visa/skyfire-session-token`

  const res = await fetch(sessionTokenUrl, {
    method: 'POST',
    body: JSON.stringify({
      userId: userId,
    }),
    headers: {
      'Content-Type': 'application/json',
      'skyfire-api-key': ENTERPRISE_ADMIN_API_KEY,
    },
  })

  return await res.json()
}

export default function App() {
  const options: EmbeddedIframeOptions = {
    fetchClientSecret: () => functionToGetSkyfireUserSession('user-id'),
    onEvent: async (type: unknown, data: unknown) => {
      console.log('USDC flow event:', type, data)
    },
    environment: ENV,   // 'sandbox' or 'production'
    customUrl: '',      // Optional override for dev environments
    buttonText: '',     // Defaults to 'Fund Wallet' if left empty
    redirectUrl: '',    // Defaults to your app's origin if left empty
  }

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

Environment configuration

The SDK supports two environments, sandbox and production, each with its own API base URL: