Skip to main content

​
Import

import { KeystoneProvider } from '@keystoneos/react';

​
Usage

<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

PropTypeRequiredDefaultDescription
sessionTokenstringYes-Session token JWT from your backend.
environmentstringNo"production"Environment name or custom API URL.
onTokenExpired() => Promise<string>No-Called when token expires. Return a fresh token.
actionDelegatesActionDelegatesNo-Callback handlers for deposits and approvals (Tier 2).
childrenReactNodeYes-Your application content.

​
Environment Values

ValueAPI URL
"production"https://api.keystoneos.xyz
"staging"https://api-staging.keystoneos.xyz
"development"https://api-dev.keystoneos.xyz
Custom URLAny URL string (e.g., "http://localhost:8000")

​
ActionDelegates

DelegateParametersReturnDescription
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 for the full integration guide.

​
What It Creates

The provider initializes these internal services:
ServicePurpose
SessionTokenManagerToken lifecycle, auto-refresh, auth headers
EventBusReal-time settlement state subscriptions
DepositOrchestratorMulti-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: 
<KeystoneProvider sessionToken={prodToken} environment="production">
  <ProductionDashboard />
</KeystoneProvider>

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