MacroMarket API

MacroMarket turns a theme into an AI Index Basket (AIB) — a basket of real trading vehicles (stocks, ETFs, crypto from the ~48k-vehicle catalog) chosen by the Tuatara semantic model and weighted by relevance. Build it, run a hypothetical backtest, paper-trade it, or turn it into a live tradeable Event Card. No real funds move — build/backtest read+compute, paper-trade fills into a simulated portfolio. Backtested results are hypothetical and not indicative of future results. Not investment advice.

Base URL & Authentication

All endpoints live under https://cymetica.com. Read endpoints (/options, GET /{symbol}) are public; build / backtest / paper-trade require a logged-in user. Obtain a JWT from POST /auth/login and pass it as Authorization: Bearer <token>.

curl -X POST https://cymetica.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"…"}'
# -> {"access_token": "eyJ…", "token_type": "bearer", ...}

Build Options (public)

Generation options for the builder in one round-trip: the two asset classes, the trading-vehicle ontology classes that actually have catalog instances, and the AI models on offer (honest about which are configured).

curl https://cymetica.com/api/v1/macromarket/options

Build an AI Index Basket

Build + persist an AIB from a theme using the chosen AI model and optional class filters. Returns the basket symbol (MM-…), its components + weights, and its detail-page path.

Field	Type	Notes
theme	string	Required. Theme to build around.
num_assets	integer	Vehicles to include. Default 6, clamped 3–12.
weighting	string	tuatara (relevance-weighted, default) or equal.
model	string	AI model that proposes constituents (default tuatara). Validated against /options; fails closed if unavailable.
asset_classes	list?	Subset of ["crypto","equity"]; omit for both.
ontology_classes	list?	Trading-vehicle ontology-class slugs (from /options); omit for all.

curl -X POST https://cymetica.com/api/v1/macromarket/build \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"theme": "nuclear energy", "num_assets": 6, "weighting": "tuatara"}'

{
  "symbol": "MM-NUCLEAR-…",
  "name": "Nuclear Energy AIB",
  "theme": "nuclear energy",
  "weighting_used": "tuatara",
  "components": [
    {"symbol": "CCJ", "asset_class": "equity", "weight": 0.21, "t0_price": 51.2}
  ],
  "disclaimer": "Simulated / paper only — … not indicative of future results …",
  "persisted": true,
  "page": "/macromarket/MM-NUCLEAR-…"
}

Backtest (hypothetical)

Run the gated historical backtest of an AIB (by aib_symbol) or a fresh theme. Returns total return, Sharpe, max drawdown, win rate. Results are hypothetical and exclude fees, slippage, and transaction costs.

Field	Type	Notes
aib_symbol	string?	An existing AIB symbol (MM-…). Omit to build from theme first.
theme	string?	Theme to build + backtest if no aib_symbol.
period_days	integer	Lookback. Default 365, clamped 7–1825.

curl -X POST https://cymetica.com/api/v1/macromarket/backtest \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"aib_symbol": "MM-NUCLEAR-…", "period_days": 365}'

Paper-Trade (simulated)

Place a simulated basket order — splits a USD amount across the legs by weight and fills into your paper portfolio. No real funds move. Pass an idempotency_key so a double-submit replays instead of double-filling.

curl -X POST https://cymetica.com/api/v1/macromarket/paper-trade \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"aib_symbol": "MM-NUCLEAR-…", "usd_notional": 1000, "side": "buy"}'

Backtest a Composer Draft (the loop)

Backtest a saved Composer draft's basket as an AIB, honouring the draft's exact composition (no rebuild). Owner-gated.

Get a Built AIB (public)

Public JSON definition of a previously-built AIB (public projection — no internal catalog ids or raw scores).

curl https://cymetica.com/api/v1/macromarket/MM-NUCLEAR-…

Trading Mode

MacroMarket is simulated / paper only — there is no live trading on these endpoints. To make a basket actually tradeable, ask NEXUS to convert it to an Event Card (the build_event_card_from_aib tool; see MCP Tools), which lists it as an EVCDX index on the live order book.

Errors

{"detail": "Authentication required"}                  // 401
{"detail": "MacroMarket is not available in your region."} // 403  (OFAC floor)
{"detail": "theme is required"}                         // 422  (build: empty theme)
{"detail": "Provide aib_symbol or theme."}             // 422  (backtest: neither given)
{"detail": "usd_notional must be positive"}            // 422  (paper-trade)
{"detail": "No catalog vehicles matched ''. …"}  // 404
{"detail": "The AI model is temporarily unavailable; please retry."} // 503
{"detail": ""}                   // 402  (over allowance)