From news event to tradable basket.You keep the licence, money, and customers.

API integration

Wire Cascade into your product from your Broker backend. Call Business with an API key; Business proxies allowlisted Engine routes and serves live SSE. Full request/response schemas live in Swagger.

API keys & scopes

Keys are issued from the Cascade dashboard. csk_test_… keys are available immediately; csk_live_… keys require an approved organisation — so you can build the entire integration before due diligence completes.

Scopes are exact strings. There is no hierarchy and there are no wildcards — read does not imply baskets:read, and admin does not imply trade.

Separate keys keep a leak bounded and let you rotate one service without an outage across your platform.

Modules & entitlements

Module 1 is always available. Modules 2–5 are enabled per organisation. Every request is checked in three stages, and each one fails differently.

How to integrate into your product

1. 01

   Authenticate

   Call Business with your API key. Unknown /v1/engine/* paths return 404; only the allowlisted surface is open.

   Authorization: Bearer csk_test_xxxxxxxx
   Content-Type: application/json

2. 02

   Load catalog into your product

   List published events and templates, then show constituents to customers.

   GET /v1/engine/events
   GET /v1/engine/events/{eventId}
   GET /v1/engine/catalog/templates

3. 03

   Quote against the live index

   Read the current level (starts at 1,000) and subscribe to SSE marks. Apply your own spread in your app. Cascade is spread-free.

   GET /v1/engine/baskets/{basketId}/index
   GET /v1/stream/marks

4. 04

   Record suitability, then trade

   A first buy is refused without a passing suitability row. Preview writes nothing; reserve holds capacity; commit opens the contract.

   PUT  /v1/engine/traders/{traderId}/suitability
   POST /v1/engine/buy/preview
   POST /v1/engine/buy/reserve
   POST /v1/engine/buy/commit

5. 05

   Show positions and closes

   Read the book your customers hold, preview a close, then queue the sell.

   GET  /v1/engine/positions
   GET  /v1/engine/portfolio
   POST /v1/engine/sell/preview
   POST /v1/engine/sell

6. 06

   Listen for hedge and lifecycle events

   Subscribe to the event stream for hedge-delta and trade lifecycle fan-out from Business.

   GET /v1/stream/events

API reference by module

Every allowlisted Broker Server route, with the same request and response detail as the Swagger UI. Click an endpoint to expand it. Scope hints must be present on your API key.

Trading, positions & book

Modules 3 and 5 in the licensed sense — order lifecycle and the book a customer holds. Outside the Cascade API Reference's scope, so summarised here rather than expanded.

Idempotency

Send an Idempotency-Key on every non-idempotent write.

• Repeating a request with the same key and same payload returns the original result.
• Reusing a key with a different payload is 409 conflict — never a silent overwrite.
• Keys are scoped to your organisation.
• Reuse one key across retries of the same logical request; generate a new one for a genuinely new request.

Some endpoints carry their own natural handle — publishKey on POST /v1/engine/events — and behave the same way.

Replay flags — treat every one as success

Errors & retries

Every error uses the same envelope. code is a closed set — branch on it. message is for humans and may be reworded at any time.

attempt (with Idempotency-Key)

  429                  -> wait the advertised delay, retry
  503 load_shed        -> jittered backoff, retry
                          (expected to succeed)
  503 unavailable, 500 -> jittered exponential backoff,
                          cap attempts, then alert
  other 4xx            -> do not retry; it will fail
                          identically

Rate limits & pagination

Requests are metered per organisation with a token bucket: capacity is your burst, refilled at your requests-per-second. Over the limit returns 429, with the retry delay in the body.

Read x-ratelimit-remaining on every response and throttle before you get there. Back off on 429; do not hot-loop.

Conventions

• Money fields are decimal strings, never JSON numbers.
• customerRef / traderId are opaque. Cascade holds no customer identity.
• Index values are levels starting at 1,000, not currency prices.
• Buy preview always returns indicative: true and never a firm entry price.
• POST /quotes is not on the Broker Server allowlist. You own the pricing layer.

Webhooks

Cascade publishes the same catalogue two ways: webhooks for anything your back office must not miss, and the event stream for anything a screen is watching. Most integrations use both — if you take only one, take webhooks, because they retry.

POST /cascade/webhook HTTP/1.1
Host: yourfirm.example.com
X-Cascade-Signature: v1=4a7f9c…
X-Cascade-Timestamp: 2026-09-23T21:05:00Z
Content-Type: application/json

{ "eventType": "reconciliation.break",
  "eventId": "9f30…",
  "occurredAt": "2026-09-23T21:05:00Z",
  "data": { "checkId": "e1f2…", "symbol": "MSFT",
            "severity": "high", "frozen": true } }

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody, headers, secret) {
  const ts  = headers["x-cascade-timestamp"];
  const sig = (headers["x-cascade-signature"] || "").replace(/^v1=/, "");

  if (Math.abs(Date.now() - Date.parse(ts)) > 5 * 60_000) return false;

  const expected = createHmac("sha256", secret)
    .update(ts).update(rawBody)
    .digest("hex");

  const a = Buffer.from(sig, "hex");
  const b = Buffer.from(expected, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

Error codes

The complete set, with whether retrying is worth it.

Degrading well

Going-live checklist

What to confirm before you point a live key at production.

Glossary