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

# KeystoneProvider

> Top-level context provider for KeyStone Elements.

## Import

```tsx theme={null}
import { KeystoneProvider } from '@keystoneos/react';
```

## Usage

```tsx theme={null}
<KeystoneProvider
  sessionToken={token}
  environment="production"
  onTokenExpired={async () => {
    const res = await fetch('/api/keystone/session', { method: 'POST' });
    return (await res.json()).token;
  }}
  actionDelegates={{
    onDepositRequired: async (leg, info) => {
      const result = await platformApi.deposit(info);
      return { txHash: result.txHash };
    },
  }}
>
  <YourApp />
</KeystoneProvider>
```

## Props

| Prop              | Type                    | Required | Default        | Description                                            |
| ----------------- | ----------------------- | -------- | -------------- | ------------------------------------------------------ |
| `sessionToken`    | `string`                | Yes      | -              | Session token JWT from your backend.                   |
| `environment`     | `string`                | No       | `"production"` | Environment name or custom API URL.                    |
| `onTokenExpired`  | `() => Promise<string>` | No       | -              | Called when token expires. Return a fresh token.       |
| `actionDelegates` | `ActionDelegates`       | No       | -              | Callback handlers for deposits and approvals (Tier 2). |
| `children`        | `ReactNode`             | Yes      | -              | Your application content.                              |

### Environment Values

| Value           | API URL                                          |
| --------------- | ------------------------------------------------ |
| `"production"`  | `https://api.keystoneos.xyz`                     |
| `"staging"`     | `https://api-staging.keystoneos.xyz`             |
| `"development"` | `https://api-dev.keystoneos.xyz`                 |
| Custom URL      | Any URL string (e.g., `"http://localhost:8000"`) |

### ActionDelegates

| Delegate             | Parameters            | Return                | Description                                 |
| -------------------- | --------------------- | --------------------- | ------------------------------------------- |
| `onDepositRequired`  | `(leg, depositInfo)`  | `Promise<{ txHash }>` | Called when a deposit needs to be executed. |
| `onApprovalRequired` | `(leg, approvalInfo)` | `Promise<{ txHash }>` | Called when a token approval is needed.     |

See [Action Delegates](/elements/action-delegates) for the full integration guide.

## What It Creates

The provider initializes these internal services:

| Service               | Purpose                                       |
| --------------------- | --------------------------------------------- |
| `SessionTokenManager` | Token lifecycle, auto-refresh, auth headers   |
| `EventBus`            | Real-time settlement state subscriptions      |
| `DepositOrchestrator` | Multi-step deposit flow with delegate routing |

All hooks in `@keystoneos/react` read from this context. Using a hook outside the provider throws an error.

## Multiple Providers

You can nest providers for different environments (e.g., showing production and staging data side-by-side), but this is unusual:

```tsx theme={null}
<KeystoneProvider sessionToken={prodToken} environment="production">
  <ProductionDashboard />
</KeystoneProvider>

<KeystoneProvider sessionToken={stagingToken} environment="staging">
  <StagingDashboard />
</KeystoneProvider>
```