> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skyfire.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Skyfire Credits Wallet Embed SDK

The Skyfire Credits Wallet Embed SDK allows Skyfire Enterprise Customers to embed wallet funding directly into applications using a secure, hosted flow.

<br />

The SDK handles:

* Session authentication
* Wallet top-up orchestration
* Wallet balance retrieval & refresh

This enables you to embed wallet funding into your app with minimal backend work.

<br />

Use this SDK if:

* You want users to fund wallets directly inside your app.
* You prefer a hosted checkout flow instead of building your own funding UI.

<br />

***

## Installation

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

<br />

***

## Prerequisites

<br />

### 1. Become a Skyfire Enterprise Customer

To use the SDK you must be a Skyfire Enterprise Customer. This will enable you to show your end-users their wallet balances and allow them to top-up their wallets.

<br />

### 2. Whitelist your Domain

Please reach out to [support@skyfire.xyz](mailto:support@skyfire.xyz) to whitelist your domain to begin using the SDK.

* For security reasons, the embedded wallet iframe only loads on approved domains. This prevents unauthorized sites from embedding the wallet. It also ensures payment redirects and session tokens are handled safely.
* Note: You must provide the exact domain (including subdomain) where the SDK will be embedded.

<br />

***

## 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 the 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 via the Skyfire API.
4. The end-user completes payment in a new payment page.
5. The payment page redirects the end-user back to your application.
6. The SDK automatically refreshes and displays the updated wallet balance.

<br />

***

## Basic Example

```jsx
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)
    },
    customUrl: '',        // Optional override for dev environments
    environment: '',      // 'sandbox' or 'production'
    buttonText: '',       // Defaults to 'Fund Wallet'
    redirectUrl: '',      // Stripe redirect URL (defaults to app origin)
  }

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

<br />

***

## Environment Configuration

The SDK supports:

* `sandbox`
* `production`

Use the appropriate API base URL:

| Environment | Base URL                                                           |
| ----------- | ------------------------------------------------------------------ |
| Sandbox     | [https://api-sandbox.skyfire.xyz](https://api-sandbox.skyfire.xyz) |
| Production  | [https://api.skyfire.xyz](https://api.skyfire.xyz)                 |

<br />