KeystoneProvider

Not yet released. The packages on this page are not published to npm yet, so the install commands below will not resolve. The documented interface is stable and the code exists; only publication is outstanding. To use KeyStone from a frontend today, call the REST API or the TypeScript SDK, which is published. Contact us if you need early access.

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

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"`)

Staging is the environment to integrate against today. https://api-staging.keystoneos.xyz is live and serves testnet settlements. The production host is reserved and not yet serving; requests to it will fail. api-dev is for KeyStone-internal use and does not resolve publicly.

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 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:

<KeystoneProvider sessionToken={prodToken} environment="production">
  <ProductionDashboard />
</KeystoneProvider>

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

Overview

Backend SDKs

Frontend Library

Tools

Import

Usage

Props

Environment Values

ActionDelegates

What It Creates

Multiple Providers

​Import

​Usage

​Props

​Environment Values

​ActionDelegates

​What It Creates

​Multiple Providers

Import

Usage

Props

Environment Values

ActionDelegates

What It Creates

Multiple Providers