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

# Python SDK

> Install, initialize, and use the simmer-sdk Python package.

The `simmer-sdk` package wraps the [REST API](/api/overview) with an authenticated client and typed data classes. All SDK methods map 1:1 to REST endpoints — see the [API Reference](/api/overview) for full parameter and response documentation.

## Installation

```bash theme={null}
pip install -U simmer-sdk   # examples on this page verified against 0.21.0
```

<Note>
  Run `pip install -U simmer-sdk` to get the latest version. These examples were verified against `simmer-sdk` 0.21.0. Versions before 0.21.0 are missing `TradeResult.fill_price` and `TradeResult.fee_rate_bps`, and silently ignore a `shares` argument on buy orders instead of raising `ValueError`.
</Note>

## Initialization

```python theme={null}
from simmer_sdk import SimmerClient

# From env var (recommended) — requires SDK 0.13.0+
# export SIMMER_API_KEY="sk_live_..."
client = SimmerClient.from_env()

# Or pass directly
client = SimmerClient(api_key="sk_live_...")

# With venue default — kwargs forward through from_env()
client = SimmerClient.from_env(venue="polymarket")

# Explicit OWS-managed wallet routing
client = SimmerClient.with_ows_wallet("my-agent-wallet")
```

`SimmerClient.from_env()` reads `SIMMER_API_KEY` from the environment and auto-detects `WALLET_PRIVATE_KEY` (external EVM wallet) and `OWS_WALLET` (OWS-managed wallet) when set. It raises `RuntimeError` with a dashboard pointer if `SIMMER_API_KEY` is missing. `SimmerClient.with_ows_wallet(name)` is the same idea but takes the OWS wallet name explicitly — useful when the same agent process talks to multiple wallets.

These classmethods are sugar over the regular `SimmerClient(api_key=..., ...)` constructor. They exist so skill bundles and bots never have to read `os.environ` directly — keeping `import os` out of skill code helps the [ClawHub](https://clawhub.ai) scanner.

## Quick example

```python theme={null}
# Find markets, check context, trade
markets = client.find_markets("bitcoin")[:5]
context = client.get_market_context(markets[0].id)

if context.get("edge", {}).get("recommendation") == "TRADE":
    result = client.trade(
        market_id=markets[0].id,
        side="yes",
        amount=10.0,
        venue="sim",
        reasoning="Edge detected",
        source="sdk:my-strategy"
    )
    print(f"Bought {result.shares_bought} shares for {result.cost}")
```

See the [Trading Guide](/trading-guide) for the full workflow.

### Market discovery filters

`get_markets()` supports keyword-only filters for discovery (SDK 0.17.31+):

```python theme={null}
liquid = client.get_markets(sort="volume", limit=20)      # most-traded first — best for finding tradeable markets
wc = client.get_markets(tags="world-cup", limit=50)       # by tag (comma-separated, all must match)
poly = client.get_markets(venue="polymarket", limit=20)   # by trading venue; venue="sim" returns all active markets
```

`get_markets()` and `GET /api/sdk/markets` are discovery reads, not full-catalog dumps. The server returns at most 1,000 matching markets for the requested window, then applies `limit`/`offset` within that capped window. In the raw API response, `total` is the window size rather than the full catalog count; when the ceiling is hit, the response includes `truncated: true` and `capped_at_limit: true`.

Always filter before paging. SDK filters `q=`, `tags=`, `venue=`, and `sort=` are applied server-side before the cap, so `tags="world-cup", sort="volume"` gives you the most liquid World Cup markets inside that slice. The REST endpoint also accepts `max_hours_to_resolution=` for time-window slices. To enumerate beyond 1,000, split the catalog by category, venue, keyword, or time-to-resolution windows and page each slice. Imports are uncapped: if a market is live on Polymarket or Kalshi but absent from discovery, use `check_market_exists()` / import flows rather than treating the capped browse result as authoritative.

The default ordering is liquidity-first as of 2026-06-15; pass `sort="recent"` for newest-first.

## Data classes

### Market

```python theme={null}
market.id                        # UUID
market.question                  # Market question
market.status                    # "active" or "resolved"
market.current_probability       # Current YES price (0-1)
market.url                       # Direct link
market.import_source             # "polymarket", "kalshi", etc.
market.resolves_at               # Resolution date
market.polymarket_token_id       # YES CLOB token ID (may be None for non-Polymarket markets)
market.polymarket_no_token_id    # NO CLOB token ID (may be None)
market.polymarket_condition_id   # Polymarket condition ID 0x hex — may be None; use for get_top_holders()
```

`polymarket_condition_id` is `None` for Kalshi markets, some new imports, and edge cases. For cross-referencing Polymarket markets, `polymarket_token_id` and `polymarket_no_token_id` are the more reliable keys — they're populated for any market with an active CLOB.

### TradeResult

```python theme={null}
result.success          # Boolean — order accepted (not necessarily filled, see fill_status)
result.trade_id         # UUID
result.shares_bought    # Shares bought (0 for sells)
result.shares_sold      # Shares sold (0 for buys)
result.shares_filled    # Direction-agnostic filled shares — shares_bought OR shares_sold
result.shares_requested # Shares requested (compare with shares_filled for partial fills)
result.cost             # USDC spent (buy) / received (sell) — always positive
result.fill_price       # Effective average fill price per share — cost / shares_filled (SDK 0.21.0)
result.new_price        # Effective fill price (same value as fill_price; prefer fill_price in new code)
result.fee_rate_bps     # Taker fee rate in basis points — currently 0 on Polymarket (SDK 0.21.0)
result.fully_filled     # Boolean — shares_filled >= shares_requested
result.fill_status      # "filled", "submitted", "unconfirmed", or "failed" (see Trading Guide)
result.order_status     # Polymarket order status: "matched", "live", "delayed"
result.error            # Error message if failed
result.hint             # Resolution hint if failed
result.warnings         # List of warnings
result.skip_reason      # Why trade was skipped (e.g. "conflicts skipped")
```

### Position

```python theme={null}
position.market_id
position.question
position.shares_yes
position.shares_no
position.current_price
position.current_value
position.cost_basis
position.pnl
position.venue
position.currency          # "$SIM" or "USDC"
position.status
```

## Environment variables

| Variable             | Description                                           |
| -------------------- | ----------------------------------------------------- |
| `SIMMER_API_KEY`     | Your API key                                          |
| `WALLET_PRIVATE_KEY` | Polygon wallet private key (for Polymarket trading)   |
| `SOLANA_PRIVATE_KEY` | Base58-encoded Solana secret key (for Kalshi trading) |
| `SIMMER_BASE_URL`    | API base URL (default: `https://api.simmer.markets`)  |

## Error handling

```python theme={null}
import requests

try:
    result = client.trade(market_id="uuid", side="yes", amount=10.0)
except requests.exceptions.HTTPError as e:
    if e.response.status_code == 401:
        print("Invalid API key")
    elif e.response.status_code == 403:
        print("Agent not claimed or limit reached")
    elif e.response.status_code == 400:
        print(f"Bad request: {e.response.json().get('detail')}")
```

All error responses include a `fix` field with actionable resolution steps. See [Errors](/api/errors) for the full reference.