Connect — integration guide

Onboard a user and have them link their accounts in a hosted flow. Execution endpoints are documented separately.

Before you start

You'll get three things from us when your organization is set up:

An API key — your X-API-Key for every server-to-server call. It carries the sub_accounts entitlement (the scope that powers Connect). Shown once at creation.
A webhook secret — to verify the signed events we send you (optional, if you use webhooks).
Your return URL(s) registered — the hosted flow may only redirect users back to a URL on your allowlist.

We provision these for you — email james@openmarkets.ai. Base URL: https://api.openmarkets.ai.

text

X-API-Key:             om_..._live_...     every call (identifies your org)
X-OpenMarkets-Account: your-user-123       scopes the call to one of your users

How it works

Your backend

Create a link session

POST /flow/v1/connect/link-sessions

Returns a one-time hosted_url for this user.

↓ redirect the user to hosted_url

OpenMarkets · hosted

User links their accounts

connect.openmarkets.ai

Credentials are entered and validated here — never through you.

↓ user.partners_connected · signed webhook

Your backend

You’re notified

verify X-OpenMarkets-Signature

Mark the user connected.

↓ then, any time

Your backend

Read & act

GET /flow/v1/auth/account/partners

Balances & positions — or trade on their behalf.

Every authenticated call sends those two headers: X-API-Key (your org) and X-OpenMarkets-Account (your id for the user).

1 · Mint a link

bash

POST /flow/v1/connect/link-sessions
X-API-Key: om_..._live_...

{ "external_user_id": "your-user-123",
  "return_url": "https://app.yourco.com/openmarkets/done" }

→ { "hosted_url": "https://connect.openmarkets.ai/start?token=lt_live_..." }

Redirect the user to hosted_url. The first call also provisions the user. Add "mode":"manage" for the limits / accounts screen.

2 · Webhook

json

POST {your webhook_url}   ·   X-OpenMarkets-Signature: t=..,v1=<hmac>
{ "event": "user.partners_connected", "external_user_id": "your-user-123",
  "connected_partners": ["kalshi"], "delivery_id": "evt_..." }

Verify the HMAC, dedupe on delivery_id. Trust the webhook, not the redirect.

3 · Read accounts

bash

GET /flow/v1/auth/account/partners
X-API-Key: om_..._live_...   ·   X-OpenMarkets-Account: your-user-123

Connected accounts + balances. 403 = not your user.

4 · Place a trade

bash

POST /flow/v1/auth/orders/buy
X-API-Key: om_..._live_...   ·   X-OpenMarkets-Account: your-user-123

{ "orders": [
  { "position_hash": "<from the liquidity / quote feed>",
    "amount": 50,            // stake in USD — or "shares": 100
    "max_price": 0.42 }      // won't fill above this
]}

Name the position and a price ceiling. Omit partner_id and we route to the best venue (or pass it to pin one); add "mode":"paper" for a practice fill. Strict — any other field returns 400 unknown_parameter. Each leg comes back with its fill (filled_shares, filled_notional, avg_price) and a sor_decision_id for the audit trail.

Notes

Identity is (your org, external_user_id) — never email. Each org's users are fully isolated.
Users set their own limits, pause accounts, and disconnect — you're read-only there.
Prefer typed SDKs? @openmarketsai/connect-node (server) wraps every call here; @openmarketsai/connect-web is the drop-in account-linking launcher.