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.
KeyStone provides two types of client libraries, each designed for a different part of your stack:
Backend SDKs vs Frontend Packages
| Backend SDKs | Frontend Packages |
|---|
| Packages | @keystoneos/sdk (TypeScript), keystoneos (Python) | @keystoneos/react, @keystoneos/elements-core |
| Runs in | Your server (Node.js, Python backend) | Your user’s browser (React app) |
| Authentication | M2M credentials (client_id + client_secret) | Session tokens (short-lived, scoped JWTs) |
| Purpose | Full API access - create settlements, manage webhooks, handle compliance | Display settlement data, collect user decisions, trigger deposits |
| Credentials | Must be kept secret (never in browser) | Safe for browser (scoped, short-lived, revocable) |
Backend SDKs
For server-side integration. Use M2M credentials to access the full API.
TypeScript / Node.js
@keystoneos/sdk - Node.js 20+, zero dependencies. Handles auth, retries, idempotency, and webhook verification.
Python
keystoneos - Python 3.10+, async and sync clients. Full Pydantic models for all types.
What the SDKs handle
| Feature | Details |
|---|
| Authentication | Auth0 M2M token fetch, caching, and automatic refresh before expiry |
| Retries | Exponential backoff with jitter on 429 and 5xx. Respects Retry-After headers |
| Idempotency | Built-in generateIdempotencyKey() for safe retries on creation endpoints |
| Webhook verification | HMAC-SHA256 signature verification with timing-safe comparison |
| Type safety | Full TypeScript types / Pydantic models for all request and response objects |
| Pagination | Typed paginated responses with items, total, limit, offset |
Frontend Integration
Embed settlement UI into your platform’s web app. The frontend packages use session tokens (created by your backend) for scoped API access.
React Hooks
@keystoneos/react - Headless hooks for settlements, instructions, deposits. Bring your own UI.
Server Setup
@keystoneos/node - The backend side of the frontend integration: session tokens and webhook verification.
Components
KeystoneProvider - Wrap your app to enable all hooks.
What the frontend integration covers
| Layer | Package | What it does |
|---|
| Your backend | @keystoneos/node | Creates session tokens, verifies webhook signatures |
| Your frontend | @keystoneos/react | React hooks for settlements, instructions, deposits, templates |
| Core | @keystoneos/elements-core | Framework-agnostic primitives (auth, events, state machine) |
When to use what
| Scenario | Use |
|---|
| Create settlements from your backend | @keystoneos/sdk |
| Handle webhooks on your server | @keystoneos/sdk or @keystoneos/node |
| Show settlement status to traders in your web app | @keystoneos/react |
| Let traders submit instructions from your web app | @keystoneos/react |
| Create session tokens for your frontend | @keystoneos/node |
| Build a non-React frontend | @keystoneos/elements-core |
| Call the API from a language without an SDK | Raw HTTP (cURL, httpx, fetch) |
Quick comparison
import { KeystoneClient } from "@keystoneos/sdk";
// M2M auth - for your backend
const client = new KeystoneClient({
clientId: process.env.KEYSTONE_CLIENT_ID!,
clientSecret: process.env.KEYSTONE_CLIENT_SECRET!,
});
const instruction = await client.instructions.submit({
templateSlug: "dvp-bilateral",
role: "seller",
party: { externalReference: "ACC-001", walletAddress: "0x..." },
legs: [
{ legType: "asset_delivery", instrumentId: "0xTokenAddress", quantity: "1000000", direction: "deliver", chainId: 11155111 },
{ legType: "payment", instrumentId: "0xUSDCAddress", quantity: "1000000", direction: "receive", chainId: 11155111 },
],
timeoutAt: new Date(Date.now() + 86400000).toISOString(),
idempotencyKey: client.generateIdempotencyKey(),
});
