API

Read your trades programmatically. PAT auth, JSON, cursor pagination, rate-limited.

Overview

The TradeFlow Quantum REST API gives headless integrations (Notion, Google Sheets via Apps Script, Zapier, custom scripts) read-only access to your trades. v1 covers reads only — writes (imports, manual entry via API) are a later surface.

Base URL: https://tradeflowquantum.com/api/v1

Responses are JSON. Errors carry a stable error field for switch-on handling plus a human-readable message.

Authentication

All API requests are authenticated with a personal access token (PAT) in the Authorization header. No cookies, no Clerk session.

Authorization: Bearer tfq_<your_token>

Get a token: Settings → API tokens → Mint new token. The plaintext appears exactly once when minted — we only store its hash. Tokens are scoped to your user account; revoke individually if a token is leaked.

Pro tier required. Token minting is gated behind the paid plan. Free-tier accounts can hit the endpoints with an existing token but the mint endpoint returns 402.

Tokens never expire unless you set an expiration at mint time or revoke the token from /settings.

Rate limits

60 requests per minute per IP+token pair. Exceeded calls return HTTP 429 with a retry_after_seconds field and standard X-RateLimit-* response headers:

X-RateLimit-Limit — the window cap (60)
X-RateLimit-Remaining — calls left this window
X-RateLimit-Reset — Unix-seconds when the window resets

60/min bounds a leaked token to ~3,600 reads/hr — enough for legitimate headless analytics, well below mass-exfiltration speed. If you need a higher limit for a specific use case, email support@tradeflowquantum.com.

GET `/trades`

List your closed trades, newest first.

Query parameters

Param	Type	Description
`limit`	int	Max rows per page. Default 100, max 500.
`before`	ISO timestamp	Pagination cursor. Pass the previous response's `next_cursor` to fetch the next page.
`from`	ISO timestamp	Inclusive lower bound on `opened_at`.
`to`	ISO timestamp	Inclusive upper bound on `opened_at`.
`symbol`	string	Exact-match symbol filter (auto-uppercased).

Response shape

{
  "trades": [
    {
      "id":                  "uuid",
      "symbol":              "AAPL",
      "side":                "LONG",         // or "SHORT"
      "setup":               "breakout",     // user-assigned, nullable
      "entry":               172.30,
      "exit":                174.85,
      "quantity":            100,
      "pnl":                 255.00,
      "r_multiple":          1.7,            // nullable
      "psych_score":         8,              // 1-10, nullable
      "opened_at":           "2026-04-12T13:45:00Z",
      "closed_at":           "2026-04-12T14:22:00Z",
      "asset_class":         "stock",        // stock|option|futures|forex|crypto
      "contract_multiplier": 1,              // 100 for options, varies for futures
      "option_type":         null,           // "call"|"put" for options
      "strike":              null,           // for options
      "expiration":          null,           // for options
      "underlying_symbol":   "AAPL"          // self for stocks, "AAPL" for AAPL options
    }
  ],
  "has_more": true,
  "next_cursor": "2026-04-12T13:45:00Z"
}

curl example

curl -H "Authorization: Bearer tfq_yourtoken" \
     "https://tradeflowquantum.com/api/v1/trades?limit=50&symbol=AAPL"

Pagination pattern

Loop until has_more is false:

let cursor = null;
do {
  const url = cursor
    ? `/api/v1/trades?limit=500&before=${cursor}`
    : `/api/v1/trades?limit=500`;
  const res = await fetch(`https://tradeflowquantum.com${url}`, {
    headers: { Authorization: `Bearer ${PAT}` },
  });
  const data = await res.json();
  // …process data.trades…
  cursor = data.next_cursor;
} while (cursor);

Errors

Status	error	When
401	`unauthorized`	Missing, malformed, expired, or revoked PAT.
429	`too_many_requests`	Rate-limit exceeded. Response carries `retry_after_seconds`.
500	`query_failed`	Database error on our side. Retry with backoff; persistent errors → support.
503	`service_unavailable`	Temporary outage. Retry after a few seconds.

Versioning

URL-prefixed. Current version is v1. New fields can be added to existing endpoints without bumping the major version; removing or renaming a field gets a v2 with v1 maintained in parallel for ≥6 months.

Subscribe to the changelog for API additions and deprecations.

Roadmap

What's coming once user demand justifies the surface area:

POST /v1/trades — write a single trade
POST /v1/trades/import — bulk import (replaces the in-app CSV uploader for headless flows)
GET /v1/analytics/equity — equity curve time-series
GET /v1/trade-plans — read trade plans

Want one of these sooner? Tell us what you'd build — concrete user demand is what unlocks priority.

API