Composer API

Composer is the AI basket advisor: describe a theme and answer a short risk profile, and Composer assembles a draft, risk-sized tokenized-basket recommendation from real trading vehicles. The API returns a draft recommendation only — nothing is minted, bought, or sold, and it is not yet tradeable. This is not investment advice.

Base URL & Authentication

All endpoints live under https://cymetica.com. Composer endpoints 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 a Draft Basket

Submit a theme and a 5-question risk profile (each Likert field is 1–5). Returns a draft instrument with a public_ref, a risk score, projected volatility, and the weighted asset legs.

Field	Type	Notes
theme	string	The investment theme to build around.
time_horizon_years	integer	Investment horizon in years (> 0).
loss_capacity	integer	Ability to bear loss, 1 (cannot) … 5 (large).
loss_tolerance	integer	Willingness to bear loss, 1 (panic-sell) … 5 (buy the dip).
knowledge	integer	Investing knowledge, 1 (novice) … 5 (professional).
liquidity_need	integer	Liquidity need, 1 (need soon) … 5 (no foreseeable need).

curl -X POST https://cymetica.com/api/v1/composer/instruments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "theme": "data center electricity",
    "time_horizon_years": 5,
    "loss_capacity": 3,
    "loss_tolerance": 3,
    "knowledge": 3,
    "liquidity_need": 3
  }'

{
  "public_ref": "cmp_a1b2c3d4",
  "status": "draft",
  "risk_score": 6,
  "projected_vol": "0.24",
  "assets": [
    {"symbol": "NVDA", "asset_class": "equity", "weight": 0.22},
    {"symbol": "VST",  "asset_class": "equity", "weight": 0.18}
  ],
  "rationale": "…why these vehicles fit the theme + your risk profile…",
  "legal_disclaimer": "Draft recommendation only. Not investment advice; not yet tradeable."
}

Fetch a Saved Draft

Return a draft you previously created. Owner-only — a public_ref belonging to another user returns 404.

curl https://cymetica.com/api/v1/composer/instruments/cmp_a1b2c3d4 \
  -H "Authorization: Bearer $TOKEN"

Historical Analogs

Compare this draft's theme to similar past events, found by semantic headline-embedding nearest-neighbour, with a forward-window performance read. Read-only; owner-gated; fail-soft (returns an empty analog set rather than a fabricated one when the corpus yields no covered comparison).

Field	Type	Notes
window_days	integer	Forward window per analog. Default 30, clamped 7–90.
limit	integer	Max analogs returned. Default 8, clamped 1–12.

curl -X POST https://cymetica.com/api/v1/composer/instruments/cmp_a1b2c3d4/historical-analogs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"window_days": 30, "limit": 8}'

The Composer → MacroMarket Loop

A Composer draft is the start, not the end. Backtest a saved draft as an AI Index Basket on MacroMarket — see the MacroMarket API:

Trading Mode

Composer is advisory / draft only. There is no live trading on this surface: no order is placed, no funds move, and nothing is minted. To paper-trade an idea, hand the draft to MacroMarket (above) and use its paper-trade endpoint.

Errors

{"detail": "Authentication required"}                              // 401
{"detail": "The Composer advisor is not available to you right now."} // 403  (feature/jurisdiction gate)
{"detail": "Not found"}                                             // 404  (unknown or non-owned public_ref)
{"detail": "time_horizon_years must be > 0"}                        // 422  (invalid risk profile)