weltiq — API & MCP docs

What is exposed — and what is not

Public interface	Kept inside the service
Account, positions, orders, fills, envelopes, bars, journal — the unified trading interface. Strategies are referenced by template id or your instance hash; you can run, backtest and stop them.	Strategy rule documents and parameters, the block DSL, the AI guidance memos, the review rules, reality profiles and the policy engine internals. The engineer AI explains and tunes a strategy for you inside the app — the rules themselves never leave the server, regardless of plan or login.

The missing tools are the contract: there is no endpoint or MCP tool to write policies, raise limits, promote to live or reset a kill switch. Those are human step-ups in the app.

Quickstart

Sign in with Google (free) and issue an API key under Settings → API keys. Choose its scopes at creation.
Call the API with the key as a bearer token, or plug the key into the MCP server for your Claude.

curl https://weltiq.ai/v1/markets -H "Authorization: Bearer $WELTIQ_API_KEY"

# backtest a catalog template on recent bars — same fill rules as paper
curl -X POST https://weltiq.ai/v1/backtest -H "Authorization: Bearer $WELTIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_id":"TPL-002","venue":"binance-spot","symbol":"BTCUSDT","tf":"1m","hours":24}'

Base URL https://weltiq.ai · JSON in, JSON out · send a real User-Agent (default Python/urllib agents are blocked at the edge) · OpenAPI explorer at /api-docs.

Authentication & scopes

Every key carries a subset of three scopes. Sessions (browser) hold all three; API keys hold exactly what you granted.

Scope	Grants
read-data	Markets, bars, watchlist, briefing, account, fills, orders, templates (public card), instances, backtest history, journal, AI analyst & review
run-backtest	Run backtests, instantiate templates, engineer AI (explain / tune / variants), formalize ideas (Pro)
operate-sim	Envelopes, one-off paper orders, cancel, resident slots (run / stop), promotion requests

Firewall rule for MCP: the analyst server only accepts keys whose sole scope is read-data. Issue two keys if you want both analysis and execution in your agent — they stay separate tokens on purpose.

REST reference

Market data

Endpoint	Scope	Description
`GET /v1/markets`	read-data	Venues with data freshness (live / stale): binance-spot, binance-usdm, bybit-spot, bybit-linear, us-equity, krx
`GET /v1/bars?venue&symbol&tf=1m\|1h\|1d&hours≤720`	read-data	Closed OHLCV bars (max 5,000 per call)
`GET /v1/watchlist` · `POST /v1/watchlist/refresh`	read-data · refresh: session	Signal-driven watchlist with technique, invalidation and 48h expiry
`POST /v1/signal-package` {venue, symbol}	read-data	Direction bias, techniques and template candidates for a symbol
`GET /v1/briefing`	read-data	Daily briefing

Strategies & backtests

Endpoint	Scope	Description
`GET /v1/templates?q&category&status` · `GET /v1/templates/{id}`	read-data	Template catalog (100). Public card only: name, targets, entry/exit one-liner, tags, status (ready / gated / out_of_scope), fit, forecast_load
`POST /v1/templates/{id}/instantiate`	run-backtest	Your instance of a template → `doc_hash` (Pro templates need Pro)
`POST /v1/backtest` {template_id \| doc_hash, venue, symbol, tf, hours, compare_lookahead?}	run-backtest	Replay on stored bars with the paper engine's fill rules. hours cap by tf: 1m 720 · 1h 8,760 · 1d 43,800. Returns bars, fills, pnl, fees, data_mode; recorded in history
`GET /v1/backtests?symbol` · `GET /v1/instances`	read-data	History and your instances — each labelled with template name or "custom" plus a one-line rules summary
`POST /v1/ai/engineer` {template_id, symbol, messages[]}	run-backtest	Engineer AI: explains, reviews settings, applies explicit changes. Returns reply, `changes[]` (server-computed diff) and `doc_hash`
`POST /v1/ai/engineer/variants`	run-backtest	2–3 nearby parameter variants, backtested together (Pro); rows carry changes vs base, never the rules
`POST /v1/ai/formalize` {idea, symbols[], base_template_id?}	run-backtest	Plain-language idea → instance (`doc_hash` + summary) or clarifying questions (Pro)

Resident slots (24/7 strategy runs)

Endpoint	Scope	Description
`GET /v1/slots`	read-data	Running slots with live state (position, daily pnl, last bar) and auto-stop status
`POST /v1/slots` {doc_hash, symbol, tf, stop_max_loss, stop_after_hours, signal_kind?}	operate-sim	Start a slot. Stop conditions are mandatory (loss cap in quote currency, 1–720 h). `signal_kind` links an external signal gate for gated templates. Free: 1 slot · Pro: 3
`DELETE /v1/slots/{deployment_id}`	operate-sim	Stop (closes the position)
`POST /v1/promotions`	operate-sim	Request promotion review from paper evidence

Account & orders

Endpoint	Scope	Description
`GET /v1/account`	read-data	Double-entry ledger balances: cash, position_value, fees (they sum to zero at every fill)
`GET /v1/fills?mode=paper\|testnet` · `GET /v1/orders`	read-data	Executions with fees; open orders with the full state machine
`GET /v1/fees/compare?mode&days&venues`	read-data	Your fills re-priced with each venue's fee schedule (spot vs spot, perp vs perp by default); delta vs actual and all-maker scenario
`GET /v1/envelopes` · `POST /v1/envelopes` · `DELETE /v1/envelopes/{id}`	operate-sim (read) · session (create/revoke — browser only)	Discretionary envelopes: symbols, max order notional, max daily notional, validity days
`GET/POST/DELETE /v1/connectors`	session	Your own broker API keys, encrypted per user — brokers: `binance` (USDⓈ-M futures; paper = demo/testnet), `bybit` (USDT perpetual; paper = demo trading), `kis` (soon). Verified on registration (balance read); withdrawal-enabled keys refused. Orders pick a connector with `target=cred_id`
`POST /v1/orders/oneoff` · `GET /v1/orders/oneoff`	operate-sim	One-off order inside an envelope (see order flow). `target`: `paper` (internal engine, default) or a connector `cred_id` — testnet/demo keys fill on the exchange's demo book, live keys need `thesis.live_ack`. Queue shows status and rejection code
`DELETE /v1/orders/{intent_id}`	operate-sim	Cancel — remaining qty counts as risk until confirmed
`GET /v1/journal`	read-data	Delegation journal: who / what / on whose behalf, for every action

AI analyst, keys & billing

Endpoint	Scope	Description
`POST /v1/ai/analyze` · `POST /v1/ai/chat`	read-data	Symbol analysis from deterministic stats + signals; chat on the same grounding. Observations and risks — never recommendations
`POST /v1/ai/review?days&lang=ko\|en`	read-data	Formal review of your own trades and account: metrics, rule-based findings, discipline state (good / watch / alert), fixed sections
`GET/PUT /v1/notifications`	session	Email notification preferences per kind (order fills/rejections, auto disposal, slot stops, credits, weekly review, notices). Security notices cannot be turned off
`GET/POST/DELETE /v1/keys`	session	Manage API keys (browser session only — a key cannot mint keys)
`GET /v1/billing` · `GET /v1/usage`	read-data	Credits and the open usage ledger

Order flow — the same for paper today and brokers later

Envelope — pre-authorize what a discretionary order may do: symbols, per-order and daily notional, validity.
One-off order — POST /v1/orders/oneoff with thesis.why and a disposal rule for the position: px_below and/or px_above (stop or target; the engine closes when either level is hit). No thesis or no level on an opening order → refused.
Closing — an order against a held position is treated as a close (reduce-only, capped at the held qty, no levels needed, not counted against envelope notional). Without levels the position is simply held until you close it.
Policy gate — the engine checks envelope, direction lease (no opposite-direction stacking on one symbol), self-trade, notional and data freshness. Rejections carry a code so you know exactly why.
Fill & ledger — executed against live quotes with venue-real fees and slippage; posted to the double-entry ledger. Poll GET /v1/orders/oneoff (usually within 5 s).

POST /v1/envelopes      {"symbols":["BTCUSDT"],"max_order_notional":"1000","max_daily_notional":"2000","days":7}
POST /v1/orders/oneoff  {"venue":"binance-spot","symbol":"BTCUSDT","side":"buy","type":"market","qty":"0.01",
                         "thesis":{"why":"support held on 4h"},"invalidation":{"px_below":"70000"}}

Connector roadmap: when a broker connector is attached to your account, the same request is translated to the broker's order and account calls (KIS, Binance, Bybit, IBKR) — envelope, thesis and invalidation travel with it. Nothing in your integration changes.

MCP — connect your own Claude

Two remote MCP servers (streamable HTTP), thin adapters over the same REST API — scopes, rate limits and journaling apply unchanged. Authenticate with your API key as a bearer header.

Server	URL	Accepts
weltiq (execution)	`https://weltiq.ai/mcp`	any key; tools follow the key's scopes
weltiq-analyst (information)	`https://weltiq.ai/mcp/analyst`	keys with read-data only

Claude Code

claude mcp add --transport http weltiq https://weltiq.ai/mcp \
  --header "Authorization: Bearer $WELTIQ_API_KEY"
claude mcp add --transport http weltiq-analyst https://weltiq.ai/mcp/analyst \
  --header "Authorization: Bearer $WELTIQ_READONLY_KEY"

Claude Desktop / any MCP client

{"mcpServers": {
  "weltiq": {"url": "https://weltiq.ai/mcp",
             "headers": {"Authorization": "Bearer wq_..."}}}}

Tools — weltiq (execution)

Tool	Scope	Description
`markets` · `bars`	read-data	Venue freshness; closed bars
`templates` · `template`	read-data	Catalog search and public card (rules one-liner, fit, forecast_load)
`instantiate` · `backtest` · `backtests` · `instances`	run-backtest	Own instance; backtest by template_id or doc_hash; history
`slots` · `slot_run` · `slot_stop`	operate-sim	Resident runs; stop conditions mandatory; optional signal gate
`account` · `fills` · `orders` · `journal`	read-data	Ledger, executions, open orders, delegation journal
`fees_compare`	read-data	Fee comparison across venues for your fills
`envelopes` · `order_oneoff` · `oneoff_orders` · `order_cancel` · `connectors`	operate-sim	Envelopes (read — created in the browser only), one-off order (thesis + invalidation required; `target` = paper or your connector cred_id, listed by `connectors`), queue, cancel

Tools — weltiq-analyst (information)

Tool	Scope	Description
`watchlist` · `signal_package`	read-data	Signals and per-symbol package
`analyze_symbol` · `review_account`	read-data	Symbol analysis; formal review of your own trading (credit-metered)
`fees_compare_analyst`	read-data	Fee comparison across venues for your fills

Local stdio alternative for self-hosters: WELTIQ_API_KEY=wq_... python -m weltiq.api.mcp_server [analyst]. Either way there are no tools for policies, limits, live promotion or kill-switch reset.

Errors

Errors are JSON with a code. Order rejections use venue-real reasons so your integration learns the same lessons a live venue would teach.

code	Meaning
`401` invalid token · `scope_denied`	Missing / revoked key; key lacks the required scope
`rate_limited` (429)	Per-minute window exceeded — see limits
`plan_required` (403) · `insufficient_credits` (402)	Pro feature; credit balance exhausted
`thesis_required` · `invalidation_not_declarative`	Opening orders need a thesis and a machine-checkable invalidation level
`envelope_gone` · `order_notional_exceeded` · `portfolio_budget`	No valid envelope; order or daily notional above envelope; portfolio budget
`direction_conflict` · `stp_self_cross` · `policy_denied`	Opposite direction already leased on the symbol; would self-cross; policy rule hits (listed)
`data_stale`	Market data not fresh — the engine retries on the next cycle instead of executing blind
`slot_limit` · `invalid_stop` · `not_executable`	Plan slot cap; stop conditions invalid; template has no executable document (options)
`llm_key_missing` · `llm_upstream`	AI endpoints: no model key configured; upstream model error

Metering & limits

Bucket (per minute, per user)	Free	Pro
Default endpoints	120	600
Backtests	10	60
AI endpoints	20	120

Credits: 100 on signup; draft rates 1,000 LLM tokens = 1 · 10,000 backtest bars = 1 · 100 API orders = 1 — fixed only after measurement, never retroactively (pricing). Backtest attempts are budgeted per strategy lineage, so parameter sweeps cannot buy promotion. Bars are for in-platform use; bulk extraction is throttled.

API & MCP documentation