FlintTrade API Reference

FlintTrade owns the terminal’s authenticated HTTP transport. Native broker reads and account mutations remain frozen; Practice uses the local sandbox.

WSGI prefix strip. Blueprints mount at /v1/* or /api/v1/* — match the prefix the frontend uses. The Vite dev proxy and a production reverse proxy add /ft-api before forwarding, and WSGI middleware strips that prefix before URL dispatch. A client path /ft-api/v1/X is /v1/X inside the backend; /ft-api/api/v1/X is /api/v1/X. Never double-prefix.

2. FlintTrade backend (/ft-api/v1/*)Copy Anchor Link

Order submissionCopy Anchor Link

Four routes submit an order. Every order FlintTrade submits goes through admission when it's placed. Nothing else does, including POST /api/v1/orders/place-smart, POST /api/v1/orders/open-position, and POST /api/v1/orders/close-position, which are not mounted. The Practice book under /v1/sandbox/ can cancel or modify a resting order. It has no place route and no square-off route. Practice square-off is an opposite order on POST /api/v1/orders/place. Settings → Practice adjusts virtual capital and square-off times; it does not place.

POST /api/v1/orders/cancel-all cancels open orders. Practice cancels pending sandbox orders. Live uses the gated cancel_all_orders verb and does not place. A Live body with strategy set is HTTP 400, because that verb cannot narrow by strategy.

Reduce-only is decided on the server. A close qualifies when it is the same contract, the opposite side, and the quantity is no more than the open quantity minus pending exits. On Live, pending exits include the broker's open orders on that contract when that book can be read. When the broker order book cannot be read, the cap is the open quantity minus this desk's own pending exits, and the close can still qualify. When the position book cannot be read, the place is not classified as a close. A second exit on the same broker account, while one of this desk's exits on that contract is still unfilled, is HTTP 409 exit_pending, with message and reason both Not placed. An exit for <symbol> is already pending. Wait for it to fill, or cancel it and try again. Practice uses this code on the Practice book. On Live it is the code when the broker order book can be read. The Live hold is for that broker account. When that second exit is refused because the broker order book cannot be read, the code is exit_orders_unreadable, and message and reason are both Not placed. One exit at a time for <symbol> until your broker's orders load. The Positions row shows Exit pending for the unfilled exit. The label is the symbol, or this contract when the symbol is empty.

While Laya is Down, a new order is paused and a qualifying close is still admitted. Live still runs SafetySystem after that record. The desk line is Laya is Down. New orders are paused until it's Ready. You can still close positions. A filled reducing close can show Closed. Exits are allowed while Laya is Down.

A position whose sign flips after the broker book has loaded keeps its row, tagged Unexpected, and the Positions book shows Position changed after your broker's orders loaded. You're now <long or short> <quantity> <symbol>. Close it if that wasn't intended. until dismissed.

Layer 5 (POST /api/v1/safety/kill-switch) cancels resting orders and then flattens through the emergency exit_all_positions verb. Ditto execution endpoints, including /api/v1/ditto/kill-all, remain unavailable until native cutover.

Analysis (/api/v1/*; Vite proxy /ft-api/api/v1/*)Copy Anchor Link

Powered by packages/services/screener/. The analysis blueprint mounts at /api/v1, not /v1. POST endpoints expect a JSON body (symbol, exchange, and expiry / expiry_date for option-chain tools). GET endpoints are marked.

Chart preferences (/api/v1/chart)Copy Anchor Link

Native broker connect and reads (/api/v1/native/*)Copy Anchor Link

Source: packages/core/core/src/flinttrade_core/native_account_routes.py.

These endpoints are the first-party native broker HTTP surface the terminal still calls from Setup → Brokers and Settings → Brokers. They are not a working operator path on this unreleased line. Account-management writes (POST / DELETE / PUT / PATCH, plus the GET OAuth callback) return 503 broker_account_cutover_unavailable until Task 9D. Account and market-data reads return 409 with zero provider calls until the Task 7C.2 / 8B read-port cutover onto the in-process BrokerReadPort. Exact broker reads that already exist are that in-process port, not this HTTP family and not terminal UX. Brokers that are built but not cleared for activation stay connectable=false while any declared native_connect_blocker remains. Legacy gateway /v1 account/auth mutations are likewise frozen (503) and still reject native broker ids with data.native_connect_blockers when a catalogued native broker is evidence-gated.

Broker-hosted MCP setup catalogue: broker/mcp (GET). Metadata only; FlintTrade does not proxy MCP tool calls.

Broker capability metadata (/api/v1/broker/*, GET)Copy Anchor Link

Source: packages/integrations/gateway/src/flinttrade_gateway/capabilities_routes.py.

Service providers and connections (/ft-api/v1/services/*)Copy Anchor Link

Source: packages/core/core/src/flinttrade_core/service_provider_routes.py, service_connection_routes.py, service_providers.py, and service_connections.py.

This is a static, non-invoking control plane. Listing a provider or persisting a connection does not resolve, probe, authenticate to, or start that provider.

The catalogue is composed at app startup from the AI, historical, and gateway contributor descriptors. Catalogue service_kinds values include broker_execution, market_data_live, market_data_historical, news, llm, forecast, agent_runtime, embedding, and decision.

decision entries are catalogue providers for place admission, not LLM chat profiles. Their default evidence scope is offline qualification until a Live qualification record exists. Listing them does not probe or start the host.

Connection reads and writes are loopback-only. Non-loopback peers receive 403 forbidden before route dispatch. Mutations require If-Match (collection ETag) and Idempotency-Key (UUID4); missing If-Match is 428 connection_revision_required. Mutation endpoints share a 10-per-minute limit. Individual redacted connection objects include schema_version, provider_id, connection_id, label, model, endpoint, auth_mode, credential_configured, created_at, and updated_at — never the secret material. The collection read wraps those objects in connections; a delete returns only {"deleted": true}. Every service-connection-family response is Cache-Control: no-store.

The in-process BrokerReadPort (quotes, depth, history, account books, and related exact reads) is not this HTTP surface and is not terminal UX. Native HTTP reads stay 409 until Task 7C.2 migrates callers onto that port. See ARCHITECTURE.md.

News (/api/v1/news)Copy Anchor Link

Source: packages/core/core/src/flinttrade_core/operations_routes.py. The operations blueprint mounts at /api/v1, so the Vite/dev-proxy form is /ft-api/api/v1/news. The terminal News widget calls this route only.

AI (/api/v1/advisor*, /api/v1/ai/*, /api/v1/signals/*; Vite proxy /ft-api/api/v1/…)Copy Anchor Link

Source: packages/services/ai/. Blueprints mount at /api/v1. GET unless noted. Advisor Chat uses /api/v1/advisor (not /ai/advisor). Managed local inference (/v1/ai/local-runtime) is the exception — that blueprint stays under /v1.

Managed local inference is controlled through authenticated, localhost-only routes under /ft-api/v1/ai/local-runtime. Runtime and model downloads never start at boot and require an explicit confirmation payload. Every mutating POST except stop also requires a client-generated admission_id matching adm_[0-9a-f]{32}. The status operation echoes that admission ID, so a caller can retry the same request idempotently and reconcile an HTTP timeout. stop instead accepts only the exact ID of a currently running operation; terminal operation IDs are rejected. Detailed receipts are size- and count-bounded; IDs compacted from the detailed journal remain fail-closed in a fixed-size spent-ID filter. An indeterminate receipt means the mutation outcome cannot be proved: clients must not issue a replacement admission ID. Further mutations remain blocked until the operator explicitly acknowledges that exact operation and its original admission ID through operations/reconcile. Acknowledgement does not replay the mutation or change its outcome to success; it records only that the unknown result was reviewed. The terminal validates every successful status, model-list and direct-result payload before changing local state, and clears a pending admission only when a direct receipt has the exact shape required by that action.

Sandbox / paper trading (/ft-api/v1/sandbox/*)Copy Anchor Link

Native virtual-capital paper trading. Source: packages/core/data/src/flinttrade_data/sandbox_routes.py.

Strategies (/api/v1/strategies/*; Vite proxy /ft-api/api/v1/strategies/*)Copy Anchor Link

Source: packages/services/engine/src/flinttrade_engine/strategy_routes.py. The blueprint mounts at /api/v1/strategies. Backed by the STRATEGY_RUNNER + CRON_SCHEDULER wired at app creation.

Trade journal (/ft-api/api/v1/trades/*)Copy Anchor Link

Source: packages/core/core/src/flinttrade_core/operations_routes.py. The journal reads recorded executions from the shared DuckDB store. A successful order submission is not a fill: manual, webhook and autonomous-agent acknowledgements retain their submission audit events but do not insert the requested price and quantity as an executed trade. Authoritative native fill ingestion is not connected to this store yet, so new live submissions do not populate the execution journal. Existing rows are retained unchanged; older submission-derived rows are not retroactively verified as fills. Practice fills remain owned by the local sandbox. Live P&L is computed client-side in the MTM Monitor widget from real positions.

Safety (/api/v1/safety/*)Copy Anchor Link

Source: packages/core/core/src/flinttrade_core/operations_routes.py. The operations blueprint mounts at /api/v1, so the Vite/dev-proxy form is /ft-api/api/v1/safety/… and a direct backend call is http://<host>:5100/api/v1/safety/…. These are not under /v1/.

Cron / Schedules (/api/v1/cron/*)Copy Anchor Link

Source: packages/core/core/src/flinttrade_core/operations_routes.py. The operations blueprint mounts at /api/v1, so the Vite/dev-proxy form is /ft-api/api/v1/cron/… and a direct backend call is http://<host>:5100/api/v1/cron/…. These are not under /v1/.

Telegram (/api/v1/telegram)Copy Anchor Link

Ditto (/api/v1/ditto/*)Copy Anchor Link

Source: packages/core/core/src/flinttrade_core/operations_routes.py. The operations blueprint mounts at /api/v1, so the Vite/dev-proxy form is /ft-api/api/v1/ditto/… and a direct backend call is http://<host>:5100/api/v1/ditto/….

Native copy trading is unavailable pending its native safety design. Linking returns 501; the default factory creates no copy runtime. Runtime operations return 503 after their authentication, body and mode checks. These routes do not enable a broker bridge or Live mirroring.

Legacy account-only metadata routes accept only an unambiguous account ID. If two native brokers share that ID, they return HTTP 400 account_selector_required and change neither account. An explicit adapter never falls back to an account at another broker; malformed selectors return HTTP 400 account_selector_invalid.

Auth (/ft-api/v1/auth/*)Copy Anchor Link

JWT-based. Source: packages/core/core/src/flinttrade_core/auth_routes.py.

Welcome's Forgot your password? uses the OTP pair (forgot-password-otp / reset-password-otp). The JWT-token pair (forgot-password / reset-password) is present in the handler but is not a working operator path until something injects Flask-Mail MAIL; SMTP/SES configure EmailTransport only.

Monitoring And ObservabilityCopy Anchor Link

GET endpoints. Source: packages/core/core/src/flinttrade_core/monitoring_routes.py, health_routes.py, infra_routes.py, and the scoped audit/activity routes in packages/core/data/src/flinttrade_data.

The terminal has two development proxy namespaces:

• backend /api/v1/* routes are requested as /ft-api/api/v1/*;
• backend /v1/admin/* routes are requested as /ft-api/v1/admin/*.

Errors (/ft-api/v1/errors, /ft-api/v1/changelog)Copy Anchor Link

Support diagnostics (/ft-api/v1/support/*)Copy Anchor Link

Source: packages/core/core/src/flinttrade_core/support_routes.py. The route is covered by the backend's global authentication and additionally requires the admin.errors.read session scope. Responses use Cache-Control: no-store.

There are roughly 20 FlintTrade-specific endpoint families across the 13 Python packages. The complete list of registered Flask blueprints appears in packages/core/core/src/flinttrade_core/app.py — search for register_blueprint.

4. AuthenticationCopy Anchor Link

JWT (FlintTrade backend)Copy Anchor Link

require_auth accepts a session JWT or an API key on every mounted route that is not on the public allowlist in flinttrade_core.public_routes. That allowlist is the only exemption, and it is checked before the handler runs, so a new route is protected until it is added there. OPTIONS is always public. HEAD follows GET. The SPA shell (/ and /<path:path>) is public only for a non-API path; unknown /v1/, /api/, and /ft-api/ paths that fall through stay authenticated. Broker account-management writes still require the operator's session JWT after that check.

A non-public route behaves as follows.

The public allowlist, method and rule, is exactly:

POST /v1/auth/setup/resume is on that list. A reload mid-setup proves the password (and the authenticator code once one is enrolled) and receives a setup-session JWT. It does not require a session that is already in the browser. POST /v1/auth/setup/complete is not on the list: it needs the operator's session JWT. POST /v1/auth/setup/vault is on that list so the setup wizard can reach it, and the handler still requires the setup-session JWT and rejects a daily-login token. POST /v1/auth/setup/reset and POST /v1/auth/setup/regenerate-2fa stay reachable during first-run. Once an authenticator is enrolled, account recovery requires an active session, the password, and the current authenticator code (totp_code). A signed-out reset or authenticator change on a finished account returns Sign in to reset this account. You'll need your password and authenticator code. when an authenticator is enrolled, and Sign in to reset this account. You'll need your password. when it is not. The body includes authenticator_enrolled. A successful wipe bumps the account epoch. POST /v1/auth/totp/enable, /pin, /pin/set, /mode, and /logout are not on the list: they need an existing session JWT and return 401 without one. POST /csp-report is public because the browser cannot attach a session. The shared content-type gate accepts application/csp-report and application/reports+json (and any type whose name contains json). The handler reads a legacy csp-report object or a Reporting API list and answers HTTP 204. A non-empty body of any other type is HTTP 415 Content-Type must be application/json before the handler runs.

Authorization: Bearer <jwt>

Token claimsCopy Anchor Link

The JWT carries three claims you care about:

A jti (JWT ID) is included so the server can revoke individual tokens when the user logs out or switches mode. The revocation blocklist lives in packages/core/core/src/flinttrade_core/auth_state.py.

Backend API KeysCopy Anchor Link

5. Rate limitsCopy Anchor Link

Native broker throttles are applied by BrokerRouter using each adapter’s capabilities and workspace overrides. Every Live write still needs a one-shot SafetyContext from gate_order or gate_broker_write.

6. Mode systemCopy Anchor Link

explore | practice | live — server-side JWT-claim enforcement. The claim explore is example data. Operators see Example, not a Mode in the menu. The guard lives at packages/services/engine/src/flinttrade_engine/mode_guard.py. Every order-path endpoint asks the guard whether the current JWT permits live orders; the guard returns one of three verdicts:

POST /v1/auth/mode accepts only a downgrade to practice. That call issues a fresh JWT and revokes the previous jti. Any other value, including explore, live, and a missing mode, returns HTTP 400 before the current session is revoked, with message Only a downgrade to practice is allowed here. Switch to Live via POST /v1/auth/live with PIN verification. Live is entered only through POST /v1/auth/live, with the 6-digit PIN, after the authenticator is enrolled (totp_enabled). Without enrolment that call refuses 403 with code: "totp_required". Quick Unlock (POST /v1/auth/pin) reopens the Mode already on the session. Its body is { "pin" }. It keeps that Mode.

Authoritative coverage: packages/core/core/tests/test_order_routes.py asserts Example-data rejection, Practice routing, and Live gate / fail-closed behaviour. Engine routes that bypass the core order proxy use packages/services/engine/src/flinttrade_engine/mode_guard.py.

7. Example request / responseCopy Anchor Link

The five most-used endpoints, each shown twice: a curl command for bash/zsh, and an Invoke-RestMethod equivalent for Windows PowerShell (where curl is an alias for Invoke-WebRequest, \ is not a line continuation, and environment variables are read as $env:NAME).

7.1 Exercise the practice order pathCopy Anchor Link

This example is for a locally issued Practice-mode FlintTrade session JWT.

curl -X POST http://127.0.0.1:5100/api/v1/orders/place \
  -H "Authorization: Bearer $FLINTTRADE_PRACTICE_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "NIFTY",
    "exchange": "NSE",
    "action": "BUY",
    "quantity": 50,
    "price": 0,
    "product": "MIS",
    "order_type": "MARKET"
  }'

$params = @{
  Method      = "Post"
  Uri         = "http://127.0.0.1:5100/api/v1/orders/place"
  Headers     = @{ Authorization = "Bearer $env:FLINTTRADE_PRACTICE_JWT" }
  ContentType = "application/json"
  Body        = '{
    "symbol": "NIFTY",
    "exchange": "NSE",
    "action": "BUY",
    "quantity": 50,
    "price": 0,
    "product": "MIS",
    "order_type": "MARKET"
  }'
}
Invoke-RestMethod @params

Sandbox response shape — the handler returns the sandbox dict as-is (COMPLETE / PENDING). A REJECTED sandbox result is HTTP 400 with status: "error". There is no status: "success" envelope on this path.

{
  "order_id": "sandbox-...",
  "status": "COMPLETE",
  "message": "Paper order executed: BUY 50 NIFTY @ 0.00"
}

7.5 Compute Gamma Exposure (FlintTrade-side)Copy Anchor Link

curl -X POST http://127.0.0.1:5100/api/v1/gex \
  -H "Authorization: Bearer $FLINTTRADE_JWT" \
  -H "Content-Type: application/json" \
  -d '{"symbol":"NIFTY","exchange":"NFO","expiry":"28MAY26"}'

$params = @{
  Method      = "Post"
  Uri         = "http://127.0.0.1:5100/api/v1/gex"
  Headers     = @{ Authorization = "Bearer $env:FLINTTRADE_JWT" }
  ContentType = "application/json"
  Body        = '{"symbol":"NIFTY","exchange":"NFO","expiry":"28MAY26"}'
}
Invoke-RestMethod @params

Successful responses include status, symbol, exchange, expiry, spot, lot_size, is_sample_data, and a data object with underlying, spot_price, atm_strike, strikes, net_gex, total_call_gex, total_put_gex, dealer_zone, and gamma_flip_strike (the last is null unless a true flip level was computed). Via the Vite proxy the same route is POST /ft-api/api/v1/gex.

8. Error responsesCopy Anchor Link

Every endpoint returns one of two shapes.

Success:

{ "status": "success", "data": { … } }

Error:

{ "status": "error", "message": "Human-readable explanation.", "code": "optional_code" }

Most handlers return only status + message. The core /api/v1/orders/* proxy rejects a sample-data session (/orders/place, modify, cancel, cancel-all, and the other verbs that share that mode gate) with HTTP 403 and code: "mode_blocked". The message is Orders are not available for Example. Switch to Practice or Live to trade. That refusal runs before Laya.admit. Core operator place, after the mode guard, admits before SafetySystem and before the Practice sandbox. A client source field is ignored, so the request cannot present itself as chat or as automate. A refusal is HTTP 403 laya_denied. A quantity clamp is HTTP 409 laya_clamp and places neither size. It applies only when the requested quantity is greater than the allowed one. A decision with no proof, while the chip can stay Ready, is HTTP 409 laya_unverified. http_status is not part of the JSON body. A Live JWT without PIN unlock on that same proxy is still message-only: HTTP 403 with "Live mode not unlocked — verify PIN first". A code field is also emitted on mode_guard-decorated engine routes (brackets and other executor-direct paths), on POST /api/v1/telegram sample-data refusals, on POST /api/v1/ditto/mirror/start and POST /api/v1/ditto/kill-all sample-data refusals, and on POST /api/v1/cron/jobs/<name>/pause and …/resume sample-data refusals. Not every endpoint emits code:

Automate place admits before SafetySystem with the same verdict. A webhook place puts code, reason, limits, and (on a clamp) applied_quantity on the dispatcher result; the webhook HTTP receiver wraps a dispatcher error as HTTP 422 with that result under data. A strategy dispatch raises the server message and does not place the reduced quantity. Modify, cancel, and cancel-all are not admitted as place. Forever, basket, split, and conditional-trigger place do not submit. POST /api/v1/orders/forever returns HTTP 501 Orders are placed through /api/v1/orders/place. and does not call a broker. A Live bracket with exactly one stop-loss or one target does submit on POST /api/v1/orders/bracket. A GTT body on place, routed place, exit-all, or that bracket is HTTP 422 gtt_unsupported before that admission. Chat is not an admission source. Details of the place path are in ORDER_SAFETY.md.

9. VersioningCopy Anchor Link

The HTTP surface uses URL-segment versioning (/api/v1/, /ft-api/v1/). Breaking changes go to /v2/ and the /v1/ surface stays alive for at least one minor release. The WebSocket protocol carries a version field on the handshake; current value is 2.

See releases/ for per-version change notes.