# Cirrus API

> Cirrus trading API reference: place orders across broker accounts, read your portfolio, stream live updates and receive signed webhooks.

Plain HTTPS + JSON under `https://api.cirrus.trade/v1`, plus one WebSocket at `wss://api.cirrus.trade/v1/stream`. Authenticate with `Authorization: token <key_id>:<secret>`. All JSON keys are snake_case. Order placement needs an `Idempotency-Key` header; never retry an `unknown` result with a new key.

## Docs

- [OpenAPI 3.1 spec](https://app.cirrus.trade/docs/openapi.json): every endpoint, request and response schema, enum value, stream message, webhook body and example
- [OpenAPI spec, live from the API](https://api.cirrus.trade/v1/openapi.json): the same document as the API serves it
- [Full reference](https://app.cirrus.trade/llms-full.txt): all sections below in one Markdown file
- [Reference as one page](https://app.cirrus.trade/docs.md): the same, served as Markdown

## Getting started

- [Overview](https://app.cirrus.trade/docs/overview.md): Base URLs, response envelope and conventions.
- [Using your API key](https://app.cirrus.trade/docs/quick-start.md): Create an API key and make the first call.
- [Authentication](https://app.cirrus.trade/docs/authentication.md): API keys and partner OAuth (authorization code + PKCE).
- [OAuth for partner apps](https://app.cirrus.trade/docs/oauth.md): Partner apps: register, authorization code + PKCE, token exchange and refresh, errors, revocation, examples.
- [Scopes](https://app.cirrus.trade/docs/scopes.md): What each scope (read, orders, triggers) allows.
- [Errors & idempotency](https://app.cirrus.trade/docs/errors.md): Error codes, the error envelope and Idempotency-Key retries.
- [Rate limits](https://app.cirrus.trade/docs/rate-limits.md): Per key, per partner app and per broker account limits.

## AI

- [Build with AI](https://app.cirrus.trade/docs/build-with-ai.md): Rules files for coding agents (Claude Code, Codex, Cursor, Copilot and more).
- [OpenAPI spec](https://app.cirrus.trade/docs/openapi.md): An OpenAPI 3.1 description of every route, enum, error code, stream message and webhook body.

## Endpoints

- [Accounts](https://app.cirrus.trade/docs/accounts.md): Your linked broker accounts: whether each can trade right now, what its setup lacks and how order updates arrive.
- [Instruments](https://app.cirrus.trade/docs/instruments.md): Everything you can trade, from the daily instrument master, with the `instrument_token` every order needs.
- [Orders](https://app.cirrus.trade/docs/orders.md): Place in one or many accounts, modify, cancel, and broker bracket / cover orders.
- [Protection rules](https://app.cirrus.trade/docs/protection.md): Stop-loss, target and trail rules used by orders and triggers.
- [Portfolio](https://app.cirrus.trade/docs/portfolio.md): Reads come from the latest snapshots, never a broker call, so they are fast and do not spend the broker rate budget.
- [Triggers](https://app.cirrus.trade/docs/triggers.md): Cirrus stop-loss / target / trail triggers, evaluated on every tick.
- [GTT](https://app.cirrus.trade/docs/gtt.md): Good-till-triggered orders held at the broker: one leg, or stop-loss + target.
- [Positions convert](https://app.cirrus.trade/docs/convert.md): Move an open position between products (for example MIS to CARRYFORWARD).
- [Margins](https://app.cirrus.trade/docs/margins.md): Margin required for an order body, per order and account, after multiplier / lot rounding and market protection.
- [Profile](https://app.cirrus.trade/docs/profile.md): Who you are calling as, and with which credential.
- [Activity log](https://app.cirrus.trade/docs/activity.md): Everything that happened, in plain English: order actions, fills, rejections, triggers, signals and access changes.

## Realtime

- [Streaming](https://app.cirrus.trade/docs/streaming.md): WebSocket with live orders and portfolio: every message type and field.
- [Webhooks](https://app.cirrus.trade/docs/webhooks.md): Signed events: order updates, trades, account alerts, positions; every body field.
- [Verifying webhooks](https://app.cirrus.trade/docs/webhook-signatures.md): Standard Webhooks signatures and secret rotation.
- [Signal URLs](https://app.cirrus.trade/docs/signal-urls.md): TradingView, Chartink and Kuberhunt signal URLs and the bodies they accept.

## App session only

- [API keys](https://app.cirrus.trade/docs/api-keys.md): Create and revoke the API keys scripts use (`Authorization: token <key_id>:<secret>`).
- [Partner apps & connections](https://app.cirrus.trade/docs/partner-apps.md): Register OAuth apps, rotate their secrets, and manage which apps may act for you.
- [Shared portfolios](https://app.cirrus.trade/docs/shared.md): Portfolios other users shared with you: who shares what, one screen across every shared account, and each view limited to what the share allows.

## Reference

- [Values reference](https://app.cirrus.trade/docs/values.md): Every enum in the API: allowed values, what they mean and where each is used.

## Optional

- [HTML docs](https://app.cirrus.trade/docs): the human-readable reference