Developer Documentation

Introduction

Interpose is an API-first financial infrastructure platform. Each of the four pillars exposes a REST API (OpenAPI 3.1) and a real-time WebSocket stream (CloudEvents 1.0 over Kafka). Use any pillar independently — there's no forced bundling.

BaaS API →

Accounts, KYC, orders, positions, funding

Post-Trade API →

Transactions, NSCC, reconciliation, corporate actions

PM API →

Portfolios, models, rebalancing, performance, billing

TPA API →

Plans, participants, vesting, contributions, ADP/ACP testing

TypeScript SDK →

npm install @interpose/sdk — typed client for all four pillars

Python SDK →

pip install interpose — sync and async, Decimal-safe

Postman Collections →

Pre-built collections with HMAC signing scripts

Authentication

All APIs accept two authentication schemes. Use Bearer tokens for portal and client apps; use HMAC signing for server-to-server integrations.

Bearer token (OAuth 2.0 JWT)

http

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

HMAC-SHA256 (server-to-server)

Include three headers on every request. Requests older than 30 seconds are rejected.

http

X-VM-Key-Id:    your-key-id
X-VM-Timestamp: 1715441400000          # Unix milliseconds
X-VM-Signature: hex(HMAC-SHA256(secret, canonical_string))

Canonical string format:

text

{METHOD}\n{PATH}\n{TIMESTAMP_MS}\n{SHA256_HEX(body)}

python

import hashlib, hmac, time

def sign(secret: str, method: str, path: str, body: bytes = b"") -> dict:
    ts = str(int(time.time() * 1000))
    body_hash = hashlib.sha256(body).hexdigest()
    message = f"{method}\n{path}\n{ts}\n{body_hash}".encode()
    sig = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
    return {"X-VM-Key-Id": KEY_ID, "X-VM-Timestamp": ts, "X-VM-Signature": sig}

Event Streams

Every state change in Interpose emits a CloudEvents 1.0 envelope on Apache Kafka. Subscribe via the WebSocket stream endpoint on each API, or consume directly from Kafka.

CloudEvents envelope

json

{
  "specversion":       "1.0",
  "id":                "evt_01HV4Y2K3M5N8P9QR2ST4UVWXY",
  "source":            "com.interpose.baas",
  "type":              "com.interpose.baas.order.filled",
  "datacontenttype":   "application/json",
  "time":              "2026-05-12T14:23:00.000000000Z",
  "data": { ... }
}

Kafka topic registry

Topic	Published by	Consumed by
vm.baas.orders.submitted	BaaS	Post-Trade
vm.baas.orders.filled	BaaS	PM
vm.baas.orders.cancelled	BaaS	—
vm.baas.positions.updated	BaaS	PM
vm.post-trade.transactions.initiated	Post-Trade	—
vm.post-trade.transactions.settled	Post-Trade	BaaS
vm.post-trade.transactions.failed	Post-Trade	BaaS
vm.pm.rebalancing.initiated	PM	—
vm.pm.rebalancing.completed	PM	—
vm.pm.rebalancing.orders.created	PM	BaaS

Errors

All errors return a JSON body with a detail field. Compliance rejections include a failed_checks array.

Status	Meaning
400	Bad request — malformed JSON or missing required field
401	Unauthenticated — invalid or expired token / HMAC signature
403	Forbidden — valid credentials but insufficient scope
404	Resource not found
409	Conflict — e.g. cancelling an already-filled order
422	Validation error or compliance rejection
429	Rate limited — retry after the Retry-After header
5xx	Server error — contact api@interposehq.com

IDs, Types & Precision

All entity IDs are ULIDs — lexicographically sortable and safe to embed in URLs.

Prefix	Entity	Example
usr_	User	usr_01HV4Y2K3M5N8P9QR2ST4UVWXY
acct_	Account	acct_01HV4Y2K3M5N8P9QR2ST4UVWXY
ord_	Order	ord_01HV4Y2K3M5N8P9QR2ST4UVWXY
txn_	Transaction	txn_01HV4Y2K3M5N8P9QR2ST4UVWXY
ptf_	Portfolio	ptf_01HV4Y2K3M5N8P9QR2ST4UVWXY
reb_	Rebalancing run	reb_01HV4Y2K3M5N8P9QR2ST4UVWXY
stl_	Settlement (internal)	stl_01HV4Y2K3M5N8P9QR2ST4UVWXY

Financial precision rules

All monetary and quantity values are returned as strings, never floats. Floating-point precision errors in financial calculations are a regulatory liability.

Data type	JSON type	Precision	Example
Fiat monetary amount	string	4 decimal places	"152.3400"
Share quantity	string	8 decimal places	"10.00000000"
Crypto (BTC)	string	8 decimal places	"0.00150000"
FX rate	string	6 decimal places	"1.265432"
Performance return	string	10 decimal places (stored)	"0.0452318920"
Timestamp	string	ISO 8601 nanoseconds UTC	"2026-05-12T14:23:00.000000000Z"