# KeyStone OS

> Developer documentation for KeyStone OS - bilateral atomic settlement infrastructure for tokenized real-world assets (RWAs).

## Docs

- [Get activity log entry](https://docs.keystoneos.xyz/api-reference/activity/get-activity-log-entry.md): Retrieve a single activity log entry by ID.
- [List activity logs](https://docs.keystoneos.xyz/api-reference/activity/list-activity-logs.md): List activity log entries for the current platform with optional filtering. Pass environment_id to scope to a specific environment. Results are ordered by most recent first.
- [Find stuck settlements](https://docs.keystoneos.xyz/api-reference/admin/find-stuck-settlements.md): Find settlements that may need admin attention. Returns non-terminal settlements that are past their timeout or have not been updated recently. Ordered by staleness (longest stuck first).
- [Force a manual state transition](https://docs.keystoneos.xyz/api-reference/admin/force-a-manual-state-transition.md): Escape hatch for forcing a settlement into any valid template state. This bypasses normal transition rules but validates that the target state exists in the template. Requires explicit confirmation.
- [Force-rollback a settlement](https://docs.keystoneos.xyz/api-reference/admin/force-rollback-a-settlement.md): Forcefully transition a settlement to ROLLED_BACK. Uses row-level locking to prevent concurrent mutations. If the settlement is already in a terminal state, returns success idempotently.
- [Get compliance check details](https://docs.keystoneos.xyz/api-reference/admin/get-compliance-check-details.md): Get full details of a compliance check with participant, wallet, and settlement context.
- [Get environment details](https://docs.keystoneos.xyz/api-reference/admin/get-environment-details.md): Get full details of a specific environment.
- [Get health stats for a specific provider](https://docs.keystoneos.xyz/api-reference/admin/get-health-stats-for-a-specific-provider.md): Returns detailed health information for a single registered provider. Useful for investigating issues with a specific integration.
- [Get platform details](https://docs.keystoneos.xyz/api-reference/admin/get-platform-details.md): Get full details of a platform including environment count.
- [Get settlement details](https://docs.keystoneos.xyz/api-reference/admin/get-settlement-details.md): Get full details of any settlement including parties and context.
- [Get settlement event trail](https://docs.keystoneos.xyz/api-reference/admin/get-settlement-event-trail.md): Get the full audit trail of state transitions for a settlement. Events are ordered by sequence number.
- [Get settlement pipeline state distribution](https://docs.keystoneos.xyz/api-reference/admin/get-settlement-pipeline-state-distribution.md): Returns the current count of settlements per state across all platforms, with totals for in-flight and terminal settlements.
- [Get settlement throughput and funnel metrics](https://docs.keystoneos.xyz/api-reference/admin/get-settlement-throughput-and-funnel-metrics.md): Returns throughput statistics (finalized/rolled-back counts, average finalization time) and a funnel showing how many settlements entered each key state during the period.
- [Get state transition counts for Sankey visualization](https://docs.keystoneos.xyz/api-reference/admin/get-state-transition-counts-for-sankey-visualization.md): Returns transition counts between states for the given period. Powers the Sankey diagram showing how settlements flow through the pipeline.
- [List activity logs across all platforms](https://docs.keystoneos.xyz/api-reference/admin/list-activity-logs-across-all-platforms.md): Cross-platform activity log listing for support investigations. Supports filtering by platform, environment, type, category, severity, actor, resource, date range, and text search.
- [List all platforms](https://docs.keystoneos.xyz/api-reference/admin/list-all-platforms.md): List all platforms with pagination and filtering. Includes environment count per platform.
- [List compliance checks across all platforms](https://docs.keystoneos.xyz/api-reference/admin/list-compliance-checks-across-all-platforms.md): Cross-platform compliance check listing with filtering by status, provider, platform, settlement, or participant.
- [List failed webhook deliveries](https://docs.keystoneos.xyz/api-reference/admin/list-failed-webhook-deliveries.md): Convenience endpoint for finding failed webhook deliveries across all platforms. Pre-filtered to success=false. Primary tool for debugging 'webhooks not arriving' issues.
- [List platform environments](https://docs.keystoneos.xyz/api-reference/admin/list-platform-environments.md): List all environments for a specific platform with pagination.
- [List provider health status](https://docs.keystoneos.xyz/api-reference/admin/list-provider-health-status.md): Returns detailed health information for all registered external providers including circuit breaker state, call counts, last error, and configuration. The overall_status field summarizes system health: healthy (all closed), degraded (any half_open), or unhealthy (any open).
- [List settlements across all platforms](https://docs.keystoneos.xyz/api-reference/admin/list-settlements-across-all-platforms.md): Search and filter settlements across all platforms and environments. Supports filtering by platform, environment, state, template, date range, and idempotency key search.
- [List webhook delivery logs across all platforms](https://docs.keystoneos.xyz/api-reference/admin/list-webhook-delivery-logs-across-all-platforms.md): Cross-platform webhook delivery log listing for debugging integration issues. Supports filtering by platform, environment, endpoint, success/failure, and event type.
- [List webhook endpoints across all platforms](https://docs.keystoneos.xyz/api-reference/admin/list-webhook-endpoints-across-all-platforms.md): Cross-platform webhook endpoint overview for identifying misconfigured webhooks. Excludes secrets from the response.
- [Override compliance for a settlement](https://docs.keystoneos.xyz/api-reference/admin/override-compliance-for-a-settlement.md): Admin override for a settlement stuck in COMPLIANCE_CHECKING with flagged checks. Approve to advance the settlement past compliance, or reject to move it to the failure state. Requires an auditable reason.
- [Re-enqueue the settlement engine](https://docs.keystoneos.xyz/api-reference/admin/re-enqueue-the-settlement-engine.md): Re-enqueue the settlement engine to retry advancing the settlement from its current state. Only valid for non-terminal settlements.
- [Update environment](https://docs.keystoneos.xyz/api-reference/admin/update-environment.md): Update environment configuration. Supports activation/deactivation, webhook settings, and settlement timeout defaults.
- [Update platform](https://docs.keystoneos.xyz/api-reference/admin/update-platform.md): Update platform settings including status. Suspending a platform prevents new settlement creation but does not cancel active settlements.
- [Get dashboard metrics](https://docs.keystoneos.xyz/api-reference/dashboard/get-dashboard-metrics.md): Returns an operational overview for the current environment: settlement counts by state, compliance check results, and recent activity count (last 24 hours).
- [Create environment](https://docs.keystoneos.xyz/api-reference/environments/create-environment.md): Create a new environment for the current platform. Provide the Auth0 M2M client_id that will be used for API access in this environment.
- [Deactivate environment](https://docs.keystoneos.xyz/api-reference/environments/deactivate-environment.md): Deactivate an environment. This prevents API access via the environment's credentials but preserves all data. Use PATCH to reactivate.
- [Get environment](https://docs.keystoneos.xyz/api-reference/environments/get-environment.md): Get details of a specific environment.
- [List environments](https://docs.keystoneos.xyz/api-reference/environments/list-environments.md): List environments for the current platform with pagination.
- [Update environment](https://docs.keystoneos.xyz/api-reference/environments/update-environment.md): Update environment configuration. Supports webhook settings, settlement defaults, and activation status.
- [Cancel instruction](https://docs.keystoneos.xyz/api-reference/instructions/cancel-instruction.md): Cancel a pending settlement instruction. Only instructions with status 'pending_match' can be cancelled.
- [Get instruction](https://docs.keystoneos.xyz/api-reference/instructions/get-instruction.md): Retrieve a settlement instruction by ID.
- [List instructions](https://docs.keystoneos.xyz/api-reference/instructions/list-instructions.md): List settlement instructions for the current environment. Optionally filter by status.
- [Submit settlement instruction](https://docs.keystoneos.xyz/api-reference/instructions/submit-settlement-instruction.md): Submit one side of a bilateral settlement instruction. If trade_reference is null, a new reference is generated (first party). If a matching pending instruction exists with the same trade_reference, automatic matching is attempted. On successful match, a settlement is created immediately. This endpo…
- [Cancel invitation](https://docs.keystoneos.xyz/api-reference/invitations/cancel-invitation.md): Cancel a pending invitation. The invitation link will no longer be valid.
- [Create invitation](https://docs.keystoneos.xyz/api-reference/invitations/create-invitation.md): Create an invitation to join the current platform's organization.
- [Create invitation (admin)](https://docs.keystoneos.xyz/api-reference/invitations/create-invitation-admin.md): Create an invitation for a platform as a Keystone admin. Typically used to onboard the first platform admin after platform registration.
- [List invitations](https://docs.keystoneos.xyz/api-reference/invitations/list-invitations.md): List all pending invitations for the current platform's organization.
- [List available roles](https://docs.keystoneos.xyz/api-reference/members/list-available-roles.md): List all roles available for assigning to platform members.
- [List members](https://docs.keystoneos.xyz/api-reference/members/list-members.md): List all members of the current platform's organization, including their roles.
- [Remove member](https://docs.keystoneos.xyz/api-reference/members/remove-member.md): Remove a member from the organization. You cannot remove yourself.
- [Update member roles](https://docs.keystoneos.xyz/api-reference/members/update-member-roles.md): Replace a member's roles within the organization. All current roles are removed and replaced with the provided role_ids. You cannot change your own roles.
- [API Reference](https://docs.keystoneos.xyz/api-reference/overview.md): Complete REST API documentation for KeyStone OS.
- [Complete onboarding](https://docs.keystoneos.xyz/api-reference/platforms/complete-onboarding.md): Mark the platform's initial onboarding as complete. Idempotent - calling this when onboarding is already complete returns the platform unchanged.
- [Get my platform](https://docs.keystoneos.xyz/api-reference/platforms/get-my-platform.md): Return the platform associated with the current token.
- [Register platform](https://docs.keystoneos.xyz/api-reference/platforms/register-platform.md): Register a new platform with a development environment. Creates an Auth0 Organization and a corresponding database record. The provided auth0_client_id is used as the M2M credential for the initial development environment.
- [Update platform settings](https://docs.keystoneos.xyz/api-reference/platforms/update-platform-settings.md): Update account-level settings for the current platform. Only provided fields are changed. Environment-specific config (webhooks, settlement defaults) is managed via /platforms/me/environments/{env_id}.
- [Add allowed IP range](https://docs.keystoneos.xyz/api-reference/security/add-allowed-ip-range.md): Add a CIDR range to the environment's IP allowlist. M2M requests from IPs outside the allowlist will be rejected.
- [List allowed IP ranges](https://docs.keystoneos.xyz/api-reference/security/list-allowed-ip-ranges.md)
- [Remove allowed IP range](https://docs.keystoneos.xyz/api-reference/security/remove-allowed-ip-range.md)
- [Get template](https://docs.keystoneos.xyz/api-reference/settlement-templates/get-template.md): Retrieve a settlement template by UUID.
- [List templates](https://docs.keystoneos.xyz/api-reference/settlement-templates/list-templates.md): List available settlement templates with pagination. Only active templates are returned.
- [Get settlement](https://docs.keystoneos.xyz/api-reference/settlements/get-settlement.md): Retrieve a settlement by UUID, including its current state and parties.
- [Initiate settlement](https://docs.keystoneos.xyz/api-reference/settlements/initiate-settlement.md): Create a new settlement. Validates the template and parties, then creates the settlement in the template's initial state. The settlement engine is enqueued automatically to advance through the template's action chain. The request is idempotent - sending the same idempotency_key returns the existing…
- [List settlement events](https://docs.keystoneos.xyz/api-reference/settlements/list-settlement-events.md): List state-change events for a settlement in chronological order. Each event includes the state transition, timestamp, and a SHA-256 content hash.
- [List settlements](https://docs.keystoneos.xyz/api-reference/settlements/list-settlements.md): List settlements for the current environment with pagination. Optionally filter by state.
- [Submit compliance decision](https://docs.keystoneos.xyz/api-reference/settlements/submit-compliance-decision.md): Submit a manual compliance decision for a settlement awaiting compliance review. Used by the platform's compliance officer after reviewing a FLAGGED settlement.
- [Create webhook endpoint](https://docs.keystoneos.xyz/api-reference/webhooks/create-webhook-endpoint.md): Register a new webhook endpoint. The secret is only returned in this response.
- [Delete webhook endpoint](https://docs.keystoneos.xyz/api-reference/webhooks/delete-webhook-endpoint.md)
- [Get webhook endpoint](https://docs.keystoneos.xyz/api-reference/webhooks/get-webhook-endpoint.md)
- [List delivery logs](https://docs.keystoneos.xyz/api-reference/webhooks/list-delivery-logs.md): View recent delivery attempts for a webhook endpoint.
- [List webhook endpoints](https://docs.keystoneos.xyz/api-reference/webhooks/list-webhook-endpoints.md)
- [Rotate webhook secret](https://docs.keystoneos.xyz/api-reference/webhooks/rotate-webhook-secret.md): Generate a new secret. The previous secret remains valid for 24 hours to allow for a graceful rollover.
- [Send test webhook](https://docs.keystoneos.xyz/api-reference/webhooks/send-test-webhook.md): Send a test event to verify the endpoint is reachable.
- [Update webhook endpoint](https://docs.keystoneos.xyz/api-reference/webhooks/update-webhook-endpoint.md)
- [KeystoneProvider](https://docs.keystoneos.xyz/components/keystone-provider.md): Top-level context provider for KeyStone Elements.
- [Compliance](https://docs.keystoneos.xyz/concepts/compliance.md): Off-chain screening, on-chain attestation, contract-enforced gate.
- [Cross-Platform Settlements](https://docs.keystoneos.xyz/concepts/cross-platform.md): How settlements span multiple platforms with bilateral instruction matching.
- [Glossary](https://docs.keystoneos.xyz/concepts/glossary.md): Definitions for domain-specific terms used throughout the KeyStone documentation.
- [Core Concepts](https://docs.keystoneos.xyz/concepts/overview.md): The building blocks of KeyStone settlement infrastructure.
- [Parties and Legs](https://docs.keystoneos.xyz/concepts/parties-and-legs.md): Who participates in a settlement and what obligations they have.
- [Settlements](https://docs.keystoneos.xyz/concepts/settlements.md): The core transaction object in KeyStone - created and enforced on-chain.
- [State Machine](https://docs.keystoneos.xyz/concepts/state-machine.md): Contract-enforced state transitions with compliance and deposit gates.
- [Templates](https://docs.keystoneos.xyz/concepts/templates.md): Reusable settlement workflow definitions.
- [Tokenised Repo](https://docs.keystoneos.xyz/concepts/tokenised-repo.md): How KeyStone handles tokenised repurchase agreement settlements.
- [Action Delegates](https://docs.keystoneos.xyz/elements/action-delegates.md): Route deposit and approval actions through your custody provider.
- [Authentication](https://docs.keystoneos.xyz/elements/authentication.md): How session tokens work and how to create them securely.
- [Getting Started](https://docs.keystoneos.xyz/elements/getting-started.md): Install KeyStone Elements and set up your first settlement integration.
- [Bilateral Instruction Flow](https://docs.keystoneos.xyz/elements/guides/bilateral-instructions.md): Submit instructions, share trade references, and track matched settlements.
- [Custody Wallet Integration](https://docs.keystoneos.xyz/elements/guides/custody-integration.md): Connect deposit flows to Fireblocks, BitGo, or any custody provider.
- [Real-time Settlement Tracking](https://docs.keystoneos.xyz/elements/guides/realtime-tracking.md): Track settlement progress with live state updates and event timelines.
- [Building a Settlement Dashboard](https://docs.keystoneos.xyz/elements/guides/settlement-dashboard.md): Build a real-time settlement monitoring page with filtering and pagination.
- [KeyStone Elements](https://docs.keystoneos.xyz/elements/overview.md): Plug-and-play settlement integration for platforms. Embed in minutes, customize everything.
- [Getting Access](https://docs.keystoneos.xyz/getting-started/access.md): Create your platform account and get API credentials.
- [Authentication](https://docs.keystoneos.xyz/getting-started/authentication.md): How to authenticate with the KeyStone OS API using M2M tokens and user tokens.
- [Your First Settlement](https://docs.keystoneos.xyz/getting-started/first-settlement.md): End-to-end walkthrough of a complete DvP settlement lifecycle.
- [Introduction](https://docs.keystoneos.xyz/getting-started/introduction.md): KeyStone OS - bilateral atomic settlement infrastructure for tokenized real-world assets.
- [Quickstart](https://docs.keystoneos.xyz/getting-started/quickstart.md): Get your first settlement running in under 10 minutes.
- [Bilateral Instructions](https://docs.keystoneos.xyz/guides/bilateral-instructions.md): How both parties submit settlement instructions independently.
- [Cross-Chain Settlement](https://docs.keystoneos.xyz/guides/cross-chain-settlement.md): How cross-chain DvP works when assets are on different blockchains.
- [Cross-Platform Settlement](https://docs.keystoneos.xyz/guides/cross-platform-settlement.md): How to settle a trade between parties on different platforms.
- [Dashboard Guide](https://docs.keystoneos.xyz/guides/dashboard.md): A complete guide to the KeyStone dashboard - managing settlements, team members, and platform settings.
- [Error Handling](https://docs.keystoneos.xyz/guides/error-handling.md): How to handle errors, retries, and edge cases.
- [Escrow Deposits](https://docs.keystoneos.xyz/guides/escrow-deposits.md): How parties deposit to escrow using commitment secrets and the contracts handle the rest.
- [Single-Platform DvP](https://docs.keystoneos.xyz/guides/single-platform-dvp.md): Step-by-step guide for a Delivery vs. Payment settlement within a single platform.
- [Testing Your Integration](https://docs.keystoneos.xyz/guides/testing.md): Set up a sandbox, get test tokens, and verify your integration end-to-end.
- [Execute a Tokenised Repo](https://docs.keystoneos.xyz/guides/tokenised-repo.md): Step-by-step guide to executing a tokenised repo settlement using bilateral instructions
- [Webhook Event Catalog](https://docs.keystoneos.xyz/guides/webhook-events.md): Complete reference for every webhook event type, payload structure, and recommended handling.
- [Webhooks](https://docs.keystoneos.xyz/guides/webhooks.md): Receive real-time notifications for settlement events.
- [useDeposit](https://docs.keystoneos.xyz/hooks/use-deposit.md): Manage the multi-step deposit flow for a settlement leg.
- [useKeystone](https://docs.keystoneos.xyz/hooks/use-keystone.md): Access the raw KeyStone Elements context for advanced use cases.
- [useSettlement](https://docs.keystoneos.xyz/hooks/use-settlement.md): Subscribe to a single settlement with real-time state updates.
- [useSettlementEvents](https://docs.keystoneos.xyz/hooks/use-settlement-events.md): Fetch the event timeline for a settlement.
- [useSettlements](https://docs.keystoneos.xyz/hooks/use-settlements.md): Fetch a paginated list of settlements with optional state filter.
- [useSubmitInstruction](https://docs.keystoneos.xyz/hooks/use-submit-instruction.md): Submit a bilateral settlement instruction and detect matching.
- [useTemplates](https://docs.keystoneos.xyz/hooks/use-templates.md): Fetch available settlement templates.
- [createSessionToken](https://docs.keystoneos.xyz/node/create-session-token.md): Create a scoped session token for frontend use.
- [Webhook Middleware](https://docs.keystoneos.xyz/node/webhook-middleware.md): Verify webhook signatures and parse events server-side.
- [CLI](https://docs.keystoneos.xyz/sdks/cli.md): Command-line tool for development, debugging, and webhook forwarding.
- [Client Libraries](https://docs.keystoneos.xyz/sdks/overview.md): Backend SDKs and frontend integration packages for KeyStone OS.
- [Postman Collection](https://docs.keystoneos.xyz/sdks/postman.md): Pre-built Postman collection for exploring and testing the KeyStone API with automatic Auth0 authentication.
- [Environments](https://docs.keystoneos.xyz/sdks/python/environments.md): Manage platform environments for data isolation.
- [Error Handling](https://docs.keystoneos.xyz/sdks/python/error-handling.md): Error types, retry behavior, and recovery patterns.
- [Getting Started](https://docs.keystoneos.xyz/sdks/python/getting-started.md): Install and configure the keystoneos Python client.
- [Instructions](https://docs.keystoneos.xyz/sdks/python/instructions.md): Submit and manage bilateral settlement instructions.
- [Settlements](https://docs.keystoneos.xyz/sdks/python/settlements.md): Create, monitor, and manage settlements.
- [Templates](https://docs.keystoneos.xyz/sdks/python/templates.md): List and inspect settlement templates.
- [Webhooks](https://docs.keystoneos.xyz/sdks/python/webhooks.md): Manage webhook endpoints, test delivery, and verify signatures.
- [Environments](https://docs.keystoneos.xyz/sdks/typescript/environments.md): Manage platform environments for data isolation.
- [Error Handling](https://docs.keystoneos.xyz/sdks/typescript/error-handling.md): Error types, retry behavior, and recovery patterns.
- [Getting Started](https://docs.keystoneos.xyz/sdks/typescript/getting-started.md): Install and configure the @keystoneos/sdk TypeScript client.
- [Instructions](https://docs.keystoneos.xyz/sdks/typescript/instructions.md): Submit and manage bilateral settlement instructions.
- [Settlements](https://docs.keystoneos.xyz/sdks/typescript/settlements.md): Create, monitor, and manage settlements.
- [Templates](https://docs.keystoneos.xyz/sdks/typescript/templates.md): List and inspect settlement templates.
- [Webhooks](https://docs.keystoneos.xyz/sdks/typescript/webhooks.md): Manage webhook endpoints, test delivery, and verify signatures.
- [ComplianceRegistry](https://docs.keystoneos.xyz/smart-contracts/compliance-registry.md): On-chain compliance attestations as a gate for settlement transitions.
- [KeystoneEscrow](https://docs.keystoneos.xyz/smart-contracts/escrow.md): Per-chain deposit lock with auto-notification, release, and rollback.
- [Smart Contracts](https://docs.keystoneos.xyz/smart-contracts/overview.md): On-chain infrastructure for autonomous, trustless settlement coordination.
- [SettlementCoordinator](https://docs.keystoneos.xyz/smart-contracts/settlement-coordinator.md): On-chain state machine enforcement with autonomous post-compliance execution.
- [Testnet Addresses](https://docs.keystoneos.xyz/smart-contracts/testnet-addresses.md): Deployed contract addresses on Sepolia and Base Sepolia testnets.

## OpenAPI Specs

- [openapi](https://docs.keystoneos.xyz/api-reference/openapi.json)