# Cirrus API

> Cirrus trading API docs: place orders across broker accounts, protect positions, run strategies, stream live updates and get 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://web.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://web.cirrus.trade/llms-full.txt): all sections below in one Markdown file
- [Reference as one page](https://web.cirrus.trade/docs.md): the same, served as Markdown

## Getting started

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

## AI

- [Build with AI](https://web.cirrus.trade/docs/build-with-ai.md): Rules files for coding agents (Claude Code, Codex, Cursor, Copilot and more).
- [Connect an AI agent](https://web.cirrus.trade/docs/connect-agent.md): Connect Claude, ChatGPT, Cursor and other AI clients to your account over MCP, with limits you set.
- [OpenAPI spec](https://web.cirrus.trade/docs/openapi.md): An OpenAPI 3.1 description of every route, enum, error code, stream message and webhook body.

## Endpoints

- [Accounts](https://web.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://web.cirrus.trade/docs/instruments.md): Everything you can trade, from the daily instrument master, with the `instrument_token` every order needs.
- [Orders](https://web.cirrus.trade/docs/orders.md): Place in one or many accounts, modify, cancel, and broker bracket / cover orders.
- [Protection rules](https://web.cirrus.trade/docs/protection.md): Stop-loss, target and trail rules used by orders and triggers.
- [Portfolio](https://web.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.
- [GTT](https://web.cirrus.trade/docs/gtt.md): Good-till-triggered orders held at the broker: one leg, or stop-loss + target.
- [Positions convert](https://web.cirrus.trade/docs/convert.md): Move an open position between products (for example MIS to CARRYFORWARD).
- [Margins](https://web.cirrus.trade/docs/margins.md): Margin required for an order body, per order and account, after multiplier / lot rounding and market protection.
- [Profile](https://web.cirrus.trade/docs/profile.md): Who you are calling as, and with which credential.
- [Activity log](https://web.cirrus.trade/docs/activity.md): Everything that happened, in plain English: order actions, fills, rejections, triggers, signals and access changes.
- [Orders](https://web.cirrus.trade/docs/more-orders.md): Place, modify and cancel orders in one or many accounts, and estimate margin first.
- [Positions and portfolio](https://web.cirrus.trade/docs/more-portfolio.md): Read positions, holdings, trades and funds; exit or convert a position.
- [Triggers](https://web.cirrus.trade/docs/more-triggers.md): Alerts, stop-loss, targets, entries, ladders and loss limits the server watches tick by tick.
- [Risk limits](https://web.cirrus.trade/docs/more-risk-limits.md): Your overall daily loss limit and exposure cap for automated strategies.
- [Backtests](https://web.cirrus.trade/docs/more-backtests.md): Run a strategy version over past days and read its trades.
- [Deployments](https://web.cirrus.trade/docs/more-deployments.md): Run a strategy on paper or live accounts, then pause, stop or take it live.
- [Strategy gallery](https://web.cirrus.trade/docs/more-gallery.md): Browse, copy, buy and publish strategy templates.
- [Strategy builder](https://web.cirrus.trade/docs/more-strategy-builder.md): What a strategy can use, ready-made templates, and checks before you save or deploy.
- [Automated strategies](https://web.cirrus.trade/docs/more-strategies.md): Write, check, version and share strategy documents.
- [Strategy P&L](https://web.cirrus.trade/docs/more-strategy-pnl.md): Today's positions and P&L grouped by the strategy tag on your orders.
- [Baskets](https://web.cirrus.trade/docs/more-baskets.md): Saved sets of orders you can place together later.
- [Shared with you](https://web.cirrus.trade/docs/more-shared.md): Portfolios and automated strategies other people shared with you, read-only.
- [Instruments](https://web.cirrus.trade/docs/more-instruments.md): Find the instrument token to trade, its lot size and expiries.
- [Notifications](https://web.cirrus.trade/docs/more-notifications.md): Telegram and in-app notifications, and which events go where.
- [Signal URLs](https://web.cirrus.trade/docs/more-signal-urls.md): Secret URLs that turn TradingView, Chartink or Kuberhunt alerts into orders.
- [Watchlists](https://web.cirrus.trade/docs/more-watchlists.md): Your stock lists; a stock strategy can run on one.
- [Partner apps (OAuth)](https://web.cirrus.trade/docs/more-partner-apps.md): Apps that act for other users: register, exchange tokens, disconnect.

## Realtime

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

## App session only

- [API keys](https://web.cirrus.trade/docs/api-keys.md): Create and revoke the API keys scripts use (`Authorization: token <key_id>:<secret>`).
- [Partner apps & connections](https://web.cirrus.trade/docs/partner-apps.md): Register OAuth apps, rotate their secrets, and manage which apps may act for you.

## Reference

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

## Optional

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