> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trymithril.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> From an API key to a risk-checked order in a few minutes.

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](https://app.trymithril.com):

<Steps>
  <Step title="Create your account">
    Sign up at [app.trymithril.com](https://app.trymithril.com) — or
    [book 20 minutes](https://calendly.com/thekarlg) and we'll onboard you
    personally. Your workspace is created for you on first sign-in.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Generate the API key">
    On the [API keys](https://app.trymithril.com/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.)
  </Step>
</Steps>

<Tip>
  Keep the key in `MITHRIL_API_KEY`; every example and the SDK read it from
  there automatically.
</Tip>

## 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.

```bash theme={null}
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.

<CodeGroup>
  ```python SDK theme={null}
  from trymithril import Mithril

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

  ```bash cURL theme={null}
  curl https://api.trymithril.com/v1/subaccounts \
    -H "Authorization: Bearer $MITHRIL_API_KEY"
  ```

  ```python requests theme={null}
  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"])
  ```
</CodeGroup>

A successful response is Mithril's standard list envelope:

```json theme={null}
{
  "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](/concepts/idempotency)) — the SDK attaches it for you.

<CodeGroup>
  ```python SDK theme={null}
  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)
  ```

  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python requests theme={null}
  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"])
  ```
</CodeGroup>

<Tip>
  Prices are probabilities in `(0, 1]` and quantities are decimals — both passed
  as **strings** to avoid float precision loss. See
  [Conventions](/concepts/conventions).
</Tip>

## 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:

<Steps>
  <Step title="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](/guides/guardrails).

    ```python theme={null}
    m.risk_limits.update(sub.id, max_order_notional="250", max_daily_loss="1000")
    ```
  </Step>

  <Step title="Find markets and read depth">
    Search across both venues and pull the book before you quote or take. See
    [Market data](/guides/market-data).
  </Step>

  <Step title="Place and manage orders">
    Vanilla limit/market orders, or hand Mithril size to
    [work into thin books](/guides/smart-execution) with `iceberg` / `peg` /
    `adaptive` and get a TCA receipt on every fill.
  </Step>

  <Step title="Watch your risk">
    Read exposure, P\&L, and per-market concentration in one call — per
    subaccount or across the workspace. See [Risk & P\&L](/guides/risk).
  </Step>

  <Step title="Isolate strategies">
    Give each bot or strategy its own [subaccount](/guides/accounts) — separate
    credentials, positions, and limits — so one can't touch another's capital.
  </Step>
</Steps>

## 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:

```bash theme={null}
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
```

<CardGroup cols={2}>
  <Card title="Python SDK" icon="python" href="/sdks/python">
    Typed models, auto-idempotency, pagination, and errors.
  </Card>

  <Card title="Guardrails" icon="shield-check" href="/guides/guardrails">
    Set the limits every order is checked against.
  </Card>
</CardGroup>