Skip to main content

​
Installation

npm install @keystoneos/sdk
View on npm | Source on GitHub
Requires Node.js 20+. Zero runtime dependencies (uses built-in fetch and crypto).

​
Initialize

import { KeystoneClient } from "@keystoneos/sdk";

const client = new KeystoneClient({
  clientId: process.env.KEYSTONE_CLIENT_ID!,
  clientSecret: process.env.KEYSTONE_CLIENT_SECRET!,
  environment: "production",
});
Auth0 M2M tokens are fetched automatically and cached in memory. Tokens refresh 60 seconds before expiry to avoid interruptions.

​
Configuration

OptionTypeDefaultDescription
clientIdstringrequiredAuth0 M2M client ID
clientSecretstringrequiredAuth0 M2M client secret
environmentstring"production""development", "staging", or "production"
baseUrlstringper environmentOverride API base URL
auth0TokenUrlstringper environmentOverride Auth0 token endpoint
auth0Audiencestringper environmentOverride Auth0 audience
maxRetriesnumber3Max retry attempts on 429/5xx
retryBaseDelaynumber500Base delay in ms for exponential backoff
timeoutnumber30000Request timeout in ms

​
Environment URLs

EnvironmentAPI URL
"production"https://api.keystoneos.xyz
"staging"https://api-staging.keystoneos.xyz
"development"https://api-dev.keystoneos.xyz

​
Resources

The client exposes typed resource namespaces: 
client.instructions   // Submit, get, list, cancel bilateral instructions
client.settlements    // Create, get, list, events, compliance decisions
client.templates      // List and get settlement templates (read-only)
client.webhooks       // CRUD + test, rotate secret, delivery logs, signature verification
client.environments   // CRUD + deactivate platform environments
client.compliance     // Convenience wrapper for compliance decisions

​
Idempotency Keys

Always use idempotency keys for create/submit operations. The SDK provides a helper: 
const key = client.generateIdempotencyKey(); // UUIDv4

// Safe to retry - same key returns existing resource, no double-creation
const settlement = await client.settlements.create({
  idempotencyKey: key,
  // ...
});

​
Pagination

All list methods return PaginatedResponse<T>: 
interface PaginatedResponse<T> {
  items: T[];
  total: number;
  limit: number;
  offset: number;
}

// Iterate through all pages
let offset = 0;
const limit = 50;

while (true) {
  const page = await client.settlements.list({ limit, offset });
  for (const settlement of page.items) {
    process(settlement);
  }
  offset += limit;
  if (offset >= page.total) break;
}