Back

MacroMarket Python SDK

A thin, dependency-light Python client for MacroMarket AI Index Baskets. It wraps the same endpoints documented in the REST API reference: build a themed basket of real vehicles, run a hypothetical backtest, and paper-trade it. No real funds move — paper / simulated only. Backtests are hypothetical and not indicative of future results. Not investment advice.

REST API Python SDK MCP Tools Open MacroMarket

Install

pip install requests

The SDK is a single file you can drop into your project — no package install required. It talks to the public API over HTTPS.

Quickstart

from macromarket import MacroMarketClient

client = MacroMarketClient(
    base_url="https://cymetica.com",
    email="you@example.com",
    password="…",
)

# 1) Build a themed AI Index Basket of real vehicles
aib = client.build("nuclear energy", num_assets=6, weighting="tuatara")
print("symbol:", aib["symbol"])
for c in aib["components"]:
    print(f"  {c['symbol']:6} {c['asset_class']:8} {c['weight']:.0%}")

# 2) Backtest it (hypothetical — paper only)
bt = client.backtest(aib_symbol=aib["symbol"], period_days=365)
print(bt)

# 3) Paper-trade it (simulated — no real funds)
fill = client.paper_trade(aib["symbol"], usd_notional=1000, side="buy")
print(fill)

Browse Build Options

opts = client.options()           # public — no auth needed
print("asset classes:", [a["key"] for a in opts["asset_classes"]])
print("vehicle classes:", len(opts["vehicle_classes"]))
print("models:", [m["name"] for m in opts["models"]])   # each model is a dict

SDK Source (paste this file)

"""macromarket.py — minimal client for EventTrader MacroMarket AI Index Baskets."""
import requests


class MacroMarketClient:
    def __init__(self, base_url: str, email: str | None = None, password: str | None = None):
        self.base = base_url.rstrip("/")
        self.s = requests.Session()
        self.token = None
        if email and password:
            r = self.s.post(f"{self.base}/auth/login",
                            json={"email": email, "password": password}, timeout=15)
            r.raise_for_status()
            self.token = r.json()["access_token"]
            self.s.headers.update({"Authorization": f"Bearer {self.token}"})

    def options(self):
        r = self.s.get(f"{self.base}/api/v1/macromarket/options", timeout=15)
        r.raise_for_status()
        return r.json()

    def build(self, theme: str, num_assets: int = 6, weighting: str = "tuatara",
              model: str = "tuatara", asset_classes=None, ontology_classes=None):
        body = {"theme": theme, "num_assets": num_assets,
                "weighting": weighting, "model": model}
        if asset_classes:
            body["asset_classes"] = asset_classes
        if ontology_classes:
            body["ontology_classes"] = ontology_classes
        r = self.s.post(f"{self.base}/api/v1/macromarket/build", json=body, timeout=90)
        r.raise_for_status()
        return r.json()

    def backtest(self, aib_symbol: str | None = None, theme: str | None = None,
                 period_days: int = 365):
        r = self.s.post(f"{self.base}/api/v1/macromarket/backtest",
                        json={"aib_symbol": aib_symbol, "theme": theme,
                              "period_days": period_days}, timeout=90)
        r.raise_for_status()
        return r.json()

    def paper_trade(self, aib_symbol: str, usd_notional: float = 1000.0,
                    side: str = "buy", idempotency_key: str | None = None):
        body = {"aib_symbol": aib_symbol, "usd_notional": usd_notional, "side": side}
        if idempotency_key:
            body["idempotency_key"] = idempotency_key
        r = self.s.post(f"{self.base}/api/v1/macromarket/paper-trade", json=body, timeout=60)
        r.raise_for_status()
        return r.json()

    def get(self, symbol: str):
        r = self.s.get(f"{self.base}/api/v1/macromarket/{symbol}", timeout=15)
        r.raise_for_status()
        return r.json()

    def from_composer(self, public_ref: str, period_days: int = 365):
        r = self.s.post(f"{self.base}/api/v1/macromarket/from-composer/{public_ref}",
                        params={"period_days": period_days}, timeout=90)
        r.raise_for_status()
        return r.json()

Example: compare two themes by hypothetical Sharpe

for theme in ["nuclear energy", "ai infrastructure"]:
    bt = client.backtest(theme=theme, period_days=365)
    print(f"{theme:20} return={bt.get('total_return')} sharpe={bt.get('sharpe')}")
# Hypothetical results only — exclude fees/slippage; not indicative of future results.

Example: backtest a Composer draft

# public_ref comes from the Composer SDK (client.compose(...)["public_ref"])
result = client.from_composer("cmp_a1b2c3d4", period_days=365)
print(result)

EventTrader