Quickstart - Mithril

Everything below talks to the public gateway at https://api.trymithril.com. The only thing you configure is an API key — venue auth, guardrails, and risk accounting happen server-side.

Get your API key

Everything runs off one mk_live_ key. Here’s the path from signup to key, in the dashboard:

Create your account

Sign up at app.trymithril.com — or book 20 minutes and we’ll onboard you personally. Your workspace is created for you on first sign-in.

Start your beta plan

Beta is free. Starting your plan is what unlocks key creation, so complete this step in onboarding before heading to the keys page.

Add a subaccount and venue credentials

Create a subaccount, then attach your Kalshi API key or Polymarket wallet key to it. Credentials are envelope-encrypted and used only to sign your orders — never returned, never logged.

Generate the API key

On the API keys page, create an mk_live_ key. It’s shown once — copy it into a secret manager or env var right away. (Use mk_test_ while you wire things up.)

Keep the key in MITHRIL_API_KEY; every example and the SDK read it from there automatically.

Two ways to call the gateway

The fastest path is the Python SDK — it handles auth, venue signing, idempotency, pagination, and typed errors. Or call the REST API directly with any HTTP client. Both talk to the same gateway; the tabs below show each.

pip install trymithril           # for the SDK
export MITHRIL_API_KEY=mk_live_...

Your first call

Confirm you can reach the gateway by listing your subaccounts.

from trymithril import Mithril

m = Mithril()  # reads MITHRIL_API_KEY
print(m.subaccounts.list()[0].id)

curl https://api.trymithril.com/v1/subaccounts \
  -H "Authorization: Bearer $MITHRIL_API_KEY"

import os, requests

BASE = "https://api.trymithril.com"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['MITHRIL_API_KEY']}"
print(s.get(f"{BASE}/v1/subaccounts").json()["data"][0]["id"])

A successful response is Mithril’s standard list envelope:

{
  "data": [
    { "id": "sub_wdzt3wugmlu4kadia7nuc2dz", "name": "main", "workspace_id": "ws_..." }
  ],
  "next_cursor": null,
  "has_more": false
}

Place a risk-checked order

The canonical trade is POST /v1/orders. Grab a token_id from a market’s orderbook, then submit. The idempotency-key header makes a blind retry safe (see Idempotency) — the SDK attaches it for you.

sub = m.subaccounts.list()[0]
market = m.markets.search("world cup", limit=1)[0]
ob = m.markets.orderbook(market.id)

order = m.orders.create(
    subaccount_id=sub.id,
    market_id=market.id,
    token_id=ob.token_id,
    action="buy",
    quantity="5",
    price="0.40",
)
print(order.id, order.status)

curl -X POST https://api.trymithril.com/v1/orders \
  -H "Authorization: Bearer $MITHRIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{
    "subaccount_id": "sub_...",
    "market_id": "mkt_...",
    "token_id": "7194...",
    "action": "buy",
    "order_type": "limit",
    "quantity": "5",
    "price": "0.40"
  }'

import uuid

order = s.post(
    f"{BASE}/v1/orders",
    headers={"idempotency-key": str(uuid.uuid4())},
    json={
        "subaccount_id": "sub_...",
        "market_id": "mkt_...",
        "token_id": "7194...",
        "action": "buy",
        "order_type": "limit",
        "quantity": "5",     # decimal STRING
        "price": "0.40",     # probability in (0, 1] as a STRING
    },
).json()
print(order["id"], order["status"])

Prices are probabilities in (0, 1] and quantities are decimals — both passed as strings to avoid float precision loss. See Conventions.

Make it useful for you

You have a key and a working call. Here’s the path from “hello world” to Mithril running your execution and risk:

Set your guardrails

Before you trade, tell Mithril your limits — max order size, daily-loss circuit breaker, kill switch. Every order is checked against them server-side. See Guardrails.

m.risk_limits.update(sub.id, max_order_notional="250", max_daily_loss="1000")

Find markets and read depth

Search across both venues and pull the book before you quote or take. See Market data.

Place and manage orders

Vanilla limit/market orders, or hand Mithril size to work into thin books with iceberg / peg / adaptive and get a TCA receipt on every fill.

Watch your risk

Read exposure, P&L, and per-market concentration in one call — per subaccount or across the workspace. See Risk & P&L.

Isolate strategies

Give each bot or strategy its own subaccount — separate credentials, positions, and limits — so one can’t touch another’s capital.

Run the full walkthrough

The examples/ folder is a runnable tour of the whole stack — one script per layer, all built on the SDK, the only config an API key:

pip install trymithril
export MITHRIL_API_KEY=mk_live_...

python 01_account.py          # subaccounts + balances
python 02_market_data.py      # search, orderbook, prices
python 03_guardrails.py       # watch the risk engine reject an oversized order
python 04_orders.py --live    # limit order lifecycle
python 05_smart_execution.py  # impact preview + adaptive execution + TCA
python 06_risk.py             # exposure, P&L, fills, portfolio

Python SDK

Typed models, auto-idempotency, pagination, and errors.

Guardrails

Set the limits every order is checked against.

​Get your API key

​Two ways to call the gateway

​Your first call

​Place a risk-checked order

​Make it useful for you

​Run the full walkthrough

Python SDK

Guardrails

Get your API key

Two ways to call the gateway

Your first call

Place a risk-checked order

Make it useful for you

Run the full walkthrough