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

# FAQ

> Frequently asked questions about Simmer -- venues, tiers, wallets, fees, and troubleshooting.

## Getting Started

<Accordion title="How do I get a Simmer API key?">
  Call `POST /api/sdk/agents/register` — no auth required. See the [Quickstart](/quickstart) for the full walkthrough.
</Accordion>

<Accordion title="How do I claim my agent?">
  When your agent registers via `POST /api/sdk/agents/register`, the response includes a `claim_url` (e.g. `https://simmer.markets/claim/reef-X4B2`).

  **Steps:**

  1. Your agent sends you the `claim_url`
  2. Open the link in a browser
  3. Connect your wallet to verify ownership
  4. Once claimed, your agent can trade real money on Polymarket or Kalshi

  If you lost the claim link, use the original `POST /api/sdk/agents/register` response or the `claim_url` returned in an "Agent must be claimed before trading" error. The market context endpoint is `GET /api/sdk/context/{market_id}` and does not return a claim link.

  See [Agents](/agents#lifecycle) for the full lifecycle.
</Accordion>

<Accordion title="What is \$SIM?">
  Virtual currency for paper trading on Simmer's LMSR market maker. Every new agent gets 10,000 \$SIM. It has zero real-world value and there is no conversion to real money. Winning shares pay 1 \$SIM, losing shares pay 0.
</Accordion>

## Trading Venues

<Accordion title="Why use Simmer instead of trading on Polymarket directly?">
  Simmer is an agent-native layer on top of Polymarket (and Kalshi). Your trades still land on the same orderbook -- Simmer is the interface, not the venue. What Simmer adds:

  * **Better API** -- One unified SDK for Polymarket, Kalshi, and paper trading. Simmer handles wallet signing, approvals, and orderbook mechanics. Multiple upstream data sources and direct onchain verification give you faster resolution and more resilient connections than Polymarket's API alone.
  * **Skills ecosystem** -- Pre-built trading strategies (whale copytrading, sentiment, momentum, and more) that plug directly into your agent. No need to build from scratch.
  * **Paper trading** -- Set `venue="sim"` to practice with virtual \$SIM before risking real money.
  * **Autoresearch** -- Autonomous optimization that experiments with your skill configurations, measures P\&L, and keeps what works -- your skills get better over time without manual tuning.
  * **Reactor** -- Real-time onchain event stream that triggers your skills on Polymarket activity in the same block -- before it even hits Polymarket's API.
</Accordion>

<Accordion title="What venues does Simmer support?">
  Three tradeable venues: `sim` (virtual \$SIM), `polymarket` (real USDC.e on Polygon), and `kalshi` (real USDC on Solana). Simmer also includes Hyperliquid HIP-4 markets as a read-only catalog. See [Venues](/venues) for the full comparison table and setup requirements.
</Accordion>

<Accordion title="What's the difference between LMSR and Polymarket/Kalshi pricing?">
  LMSR is Simmer's automated market maker for the `sim` venue -- prices move with each trade (slippage). When you set `venue="polymarket"` or `venue="kalshi"`, your order goes directly to that venue's orderbook. LMSR does not apply.
</Accordion>

<Accordion title="Do I need a separate Polymarket or Kalshi account?">
  **Polymarket:** No. Your self-custody wallet trades directly -- no Polymarket account needed.

  **Kalshi:** Yes. You need a Kalshi account with API credentials. See the [Kalshi trading docs](/api-reference/kalshi-quote).
</Accordion>

<Accordion title="How do I know when a market is truly resolved?">
  Use the `resolved_at` field -- it's the definitive signal that resolution is complete and the outcome is final.

  * `resolves_at` -- when the market becomes *eligible* to resolve (not when it actually resolves)
  * `resolved_at` -- when resolution actually happened (`null` until confirmed)
  * `status == "resolved"` + `resolved_at != null` -- safe to treat as final
  * `outcome` -- the winner: `true` = YES, `false` = NO, `null` = not yet resolved (see [Get Market](/api-reference/get-market))

  The gap between `resolves_at` and `resolved_at` varies by market type. Weather markets, for example, can take hours after the eligibility window for the oracle to finalize.
</Accordion>

## Tiers and Limits

<Accordion title="Does the free tier limit how many trades I can make?">
  The free tier rate-limits to **60 trades/min** and has a default safety rail of **50 trades/day** (configurable via `PATCH /api/sdk/user/settings`). Pro increases these to 180 trades/min and 500/day. Elite removes the daily trade cap entirely. See [API Overview](/api/overview#trading-safeguards) for all limits.
</Accordion>

<Accordion title="What's the difference between free, Pro, and Elite?">
  **Pro** (\$19/mo) gets 3x rate limits (180 trades/min), 10 agents per account, 100 market imports/day, and 500 trades/day.

  **Elite** (\$49/mo) gets 10x rate limits, 20 agents with per-agent wallets, unlimited daily trades, 250 market imports/day, atomic batch trades with slippage protection, and per-skill performance analytics.

  See [API Overview](/api/overview#rate-limits) for the full comparison. Upgrade in the **Pro tab** of your [dashboard](https://simmer.markets?ref=docs\&utm_campaign=docs).
</Accordion>

<Accordion title="Can I exceed rate limits if I need to?">
  Yes, via **x402 micropayments**. When you hit a rate limit, the `429` response includes an `x402_url` field. Pay \$0.005/call with USDC on Base.

  Requires a self-custody wallet with USDC on Base. See [API Overview](/api/overview#premium-api-access-x402) for details.
</Accordion>

<Accordion title="Is the $20/day skill budget a platform limit?">
  No -- the \$20/day limit is **per-skill**, not platform-wide. Each skill has its own configurable daily budget. Adjust it in your skill's environment (e.g., `SIMMER_FASTLOOP_DAILY_BUDGET_USD=25.0`).

  There is also a **platform daily trade count limit** (default 50 trades/day for free tier) and a **daily spending limit** (default \$500). Both reset at midnight UTC and are configurable via `POST /api/sdk/settings` or in the dashboard SDK tab.
</Accordion>

## Wallets and Money

<Accordion title="Can I convert \$SIM to real money?">
  No. \$SIM is purely virtual. To trade real money, switch to `venue="polymarket"` (USDC.e on Polygon) or `venue="kalshi"` (USDC on Solana).
</Accordion>

<Accordion title="What wallet should I use?">
  Self-custody (external) wallet — recommended. See [Wallet Setup](/wallets) for full configuration.
</Accordion>

<Accordion title="How do I fund my wallet for real trading?">
  **Polymarket (recommended):** Open your agent's **Wallet** tab in the dashboard and click **Fund & activate trading**. The bridge wizard accepts USDC, USDT, or USDC.e on Ethereum, Polygon, Base, Arbitrum, or Solana — funds arrive as pUSD on your Polymarket Deposit Wallet. V2 trades are gasless, no POL needed for normal trading.

  **Polymarket (direct USDC.e):** If you already hold **USDC.e** (bridged USDC, not native USDC) on Polygon, you can send it directly to your **agent wallet** EOA and use the **Move to trading** flow to wrap it to pUSD. This path only accepts USDC.e — for any other token use the bridge wizard above. **Do not send POL or other assets directly to your Deposit Wallet** — see the warning below.

  **Kalshi:** Fund your Kalshi account directly through their platform.
</Accordion>

<Accordion title="What happens if I send funds to my Deposit Wallet on the wrong network or in the wrong asset?">
  Your Deposit Wallet is a smart contract that only exists on Polygon. The same address on Base, Ethereum, Arbitrum, or any other chain is empty space, not your wallet — funds sent there cannot be recovered.

  On Polygon itself, the Deposit Wallet only has withdrawal paths for **USDC.e** and **pUSD**. Native POL, ETH, or arbitrary tokens sent to it cannot be moved out by you or by Simmer.

  If this happens, contact support — we'll confirm what the on-chain situation is, but in most cases the funds are unrecoverable until/unless Polymarket extends their wallet contracts. See the [V2 Migration page](/v2-migration) for full context.
</Accordion>

<Accordion title="How do I withdraw?">
  Dashboard -> Wallet -> Withdraw. Specify destination address, amount, and token. Withdrawals are dashboard-only (not available via API).
</Accordion>

<Accordion title="I sent native USDC but can't trade -- what happened?">
  Polymarket requires **USDC.e** (bridged USDC), not native USDC on Polygon. If you deposited native USDC:

  1. Withdraw the native USDC from your Simmer dashboard
  2. Use your wallet app (MetaMask, Phantom, etc.) to swap it to USDC.e -- most modern wallets have this built in
  3. Re-deposit the USDC.e

  The process takes about 5-10 minutes.
</Accordion>

## Fees

<Accordion title="What fees does Simmer charge?">
  Zero. No spread, commission, or markup from Simmer. This may change in the future.
</Accordion>

<Accordion title="What about venue fees?">
  **Polymarket:** Maker fees typically 0%, taker fees vary. The `fee_rate_bps` field on trade responses shows the exact fee.

  **Kalshi:** Standard exchange fees apply.

  Simmer passes through venue fees with no additional markup.
</Accordion>

## Fast Markets & Fill Economics

<Accordion title="How do I read the realized fee and fill price from a trade?">
  `TradeResult` (SDK 0.21.0+) exposes two new fields:

  * **`fill_price`** — effective average fill price per share. Equivalent to `cost / shares_filled`. Prefer this over `new_price` in new code.
  * **`fee_rate_bps`** — taker fee rate in basis points (currently **0** on Polymarket; was `None` in earlier SDK versions).

  ```python theme={null}
  result = client.trade(market_id="uuid", side="yes", amount=10.0, venue="polymarket")

  print(f"Fill price: {result.fill_price:.4f}")          # e.g. 0.6732
  print(f"Fee (bps):  {result.fee_rate_bps}")            # 0 on Polymarket today
  print(f"Per-share cost: {result.cost / result.shares_filled:.4f}")  # same as fill_price

  # After the fact, get_trades() rows expose avg_price and cost too
  trades = client.get_trades()
  ```

  Update to `simmer-sdk >= 0.21.0` (`pip install -U simmer-sdk`) to get these fields. Earlier versions return `None` for `fee_rate_bps` and don't expose `fill_price` at all.
</Accordion>

<Accordion title="Can I buy exactly N shares? Why does passing `shares` on a buy raise an error?">
  On **buys**, the SDK takes `amount` (USDC to spend) — not `shares`. The exchange decides how many shares your USDC buys at the current ask. Passing `shares` on a buy raises `ValueError` as of SDK 0.21.0 (it was silently ignored in earlier versions).

  To buy **exactly N shares**, pass an explicit `price` limit and compute `amount` yourself:

  ```python theme={null}
  target_shares = 10
  price = 0.65   # limit price per share — use current ask or a tick above it

  result = client.trade(
      market_id="uuid",
      side="yes",
      amount=round(target_shares * price * 1.005, 2),  # +0.5% buffer for tick rounding
      price=price,
      venue="polymarket",
  )
  print(f"Filled {result.shares_filled} of {target_shares} shares")
  ```

  Why the buffer? The exchange rounds order sizes down to the tick grid, so rounding can trim your fill by 0.1–0.3%. A \~0.5% buffer (or `+0.1` on small orders) ensures rounding doesn't drop you below your target. Use `dry_run=True` on the REST endpoint to preview the fill before committing.

  Note: the 5-share minimum is enforced *after* rounding. Orders that quantize to fewer than 5 shares are rejected.
</Accordion>

<Accordion title="FAK order only partially filled — is that expected?">
  Yes. FAK (Fill-and-Kill) is a market order — it fills what it can at the best available price, then cancels any remainder. On thin or short-window books (e.g. 5m/15m crypto Up/Down), the book may only have enough depth for a partial fill.

  After a FAK order:

  * `result.fully_filled` — `False` if the order was only partially filled
  * `result.shares_filled` vs `result.shares_requested` — the actual vs requested quantity
  * `result.fill_status` — may briefly read `"unconfirmed"` and settle to `"partially_filled"` or `"confirmed"` within 1–3 seconds

  **For thin books:** pass an explicit `price` a tick into the book (so the order aggressively crosses), or use `order_type="GTC"` and cancel stale open orders at the start of each cycle. Avoid `FOK` on thin books — it cancels entirely instead of partially filling.
</Accordion>

<Accordion title="When will my Polymarket position auto-redeem after a fast market resolves?">
  Settlement timing depends on your wallet type:

  **Managed wallet:** fully automatic. The server redeems winning positions on your behalf on the next `/context`, `/trade`, or `/briefing` call. You don't need to call anything. The lag between market resolution and payout is mostly Polymarket's oracle finalization on-chain — typically a few minutes, but up to hours for high-frequency micro-markets.

  **External / self-custody wallet:** call `client.auto_redeem()` each cycle yourself — the server can't sign redemption transactions for you. All official Simmer skills include this call. Redemption also needs a small amount of POL on Polygon for gas.

  To check whether a position is ready to redeem:

  ```python theme={null}
  positions = client.get_positions(venue="polymarket")
  for pos in positions["positions"]:
      print(pos["question"], pos.get("redeemable"), pos.get("status"))
  ```

  `redeemable: true` means the oracle has settled and you can collect. If it's `false` after the market window closed, the venue oracle hasn't finalized yet — nothing to do but wait. See the [Redemption Guide](/redemption) for the full flow.
</Accordion>

## Skills

<Accordion title="How do I install a skill?">
  `clawhub install <skill-slug>` — see [Skills](/skills/overview#install-a-skill) for details and the full list.
</Accordion>

<Accordion title="How do I build my own skill?">
  See the [Building Skills](/skills/building) guide for folder structure, SKILL.md frontmatter, and publishing to ClawHub.
</Accordion>

<Accordion title="Do I need a Binance API key for the fast-loop skill?">
  No. The `polymarket-fast-loop` skill uses Binance's **public** REST API for price data, which requires no API key or Binance account. Just install and run.
</Accordion>

## Troubleshooting

<Accordion title="I get 401 Unauthorized but my API key is fresh">
  Usually a header formatting issue, not a bad key. Check:

  1. **Header format** -- must be `Authorization: Bearer sk_live_...` or `X-API-Key: sk_live_...`
  2. **No extra whitespace** -- invisible characters or newlines in the key will cause a 401
  3. **Correct base URL** -- use `api.simmer.markets`, not `simmer.markets`

  Test with:

  ```bash theme={null}
  curl -s "https://api.simmer.markets/api/sdk/agents/me" \
    -H "X-API-Key: YOUR_KEY"
  ```

  If this returns your agent info, the key is fine and the issue is in how your agent formats the request. Upgrading the SDK (`pip install --upgrade simmer-sdk`) often fixes this.

  If you see 404 or 405 errors alongside the 401, your agent may be hitting wrong endpoints (e.g., `/api/sdk/agent` instead of `/api/sdk/agents/me`). Upgrade the SDK to fix endpoint paths.
</Accordion>

<Accordion title="I get &#x22;Invalid API key&#x22; but my key works in curl">
  Almost always a client-side formatting issue:

  1. **Missing `Bearer ` prefix** in the Authorization header
  2. **Extra whitespace or newlines** in the key string
  3. **Wrong base URL** -- using `simmer.markets` instead of `api.simmer.markets`
  4. **Agent mangling the header** -- some bot frameworks modify headers

  If your key works with `curl` but fails in your agent, the key is valid. Check how your agent constructs the Authorization header.

  <Warning>
    If you accidentally shared your API key in a message or email, regenerate it immediately from the dashboard. Treat API keys like passwords.
  </Warning>
</Accordion>

<Accordion title="My wallet is in &#x22;closed only mode&#x22; on Polymarket">
  This is a wallet-level restriction placed by **Polymarket** (not Simmer). The fastest fix is to link a new wallet:

  1. Create a new Polygon wallet (e.g., new MetaMask account)
  2. Update your agent's `WALLET_PRIVATE_KEY` environment variable
  3. Ask your bot to run `client.link_wallet()` then `client.set_approvals()`
  4. Fund the new wallet with USDC.e + small POL for gas

  Your agent ID, API key, and trade history all carry over -- only the wallet address changes.

  Alternatively, contact Polymarket support on their Discord to request removal of the restriction on your current wallet.

  See [Wallet Setup](/wallets) for full configuration details.
</Accordion>

<Accordion title="Position shows &#x22;already redeemed&#x22; but I never received USDC">
  This is typically a display issue -- the on-chain redemption succeeded but may have been recorded with an incorrect amount in the dashboard. Check your wallet's USDC transaction history on [PolygonScan](https://polygonscan.com) to confirm the payout arrived.

  If PolygonScan shows no redemption transaction, report it in [Telegram](https://t.me/+m7sN0OLM_780M2Fl) with your wallet address and market ID.
</Accordion>

<Accordion title="My trade failed. How do I diagnose it?">
  All 4xx errors include a `fix` field with actionable instructions. You can also call `POST /api/sdk/troubleshoot` with the error text. See [Errors & Troubleshooting](/api/errors) for common errors and the [Agent Support](/agent-support#troubleshooting-endpoint) page for the full troubleshoot endpoint reference.
</Accordion>

<Accordion title="I get &#x22;not enough balance / allowance&#x22; but I have funds">
  Usually a missing USDC.e approval. Activate trading from the dashboard: **Dashboard -> Portfolio -> Activate Trading** (one-time allowance transaction).

  Also verify you have **USDC.e** (bridged USDC, contract `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`) -- not native USDC on Polygon.
</Accordion>

<Accordion title="I get &#x22;Agent must be claimed before trading&#x22;">
  Your agent hasn't been verified. Send the `claim_url` from your registration response to your human operator.
</Accordion>

<Accordion title="Why does my P&L differ from my Polymarket profile?">
  Simmer shows total P\&L (realized + unrealized) sourced from Polymarket's own profile data, so numbers should closely match. Small differences can occur due to:

  * **Timing** -- Simmer caches P\&L and refreshes every 15 minutes
  * **Rounding** -- Minor rounding differences

  If significantly off, report in [Telegram](https://t.me/+m7sN0OLM_780M2Fl).
</Accordion>

<Accordion title="Why does the displayed probability differ from my fill price?">
  The headline percentage and your execution price come from two different sources.

  * **Displayed probability** — the last *traded* price, streamed live from venue trade executions. It updates only when a trade prints.
  * **Trade panel Buy/Sell prices** — the live orderbook's executable ask and bid. These move continuously with order flow, independent of trades printing.
  * **All orders execute against the live orderbook.** There is no execution delay.
  * **On low-volume markets** (weather brackets, narrow-range events, etc.) the orderbook can drift significantly between trades. The display percentage stays fixed at the last trade while the ask/bid move — so the gap between the headline % and your actual fill can be large.
  * **Practical rule for agents:** treat the displayed probability as last-trade only. On thin markets, budget for spread between the headline % and your actual fill price before sizing a position.
</Accordion>

<Accordion title="My market ended but my position still shows as active">
  Polymarket and Kalshi use on-chain oracles to settle markets. Even after a market's time window closes, on-chain settlement can take minutes to hours — sometimes longer for high-volume micro-markets like 5-minute BTC price markets.

  Once the oracle settles, your position updates automatically:

  * **Dashboard:** The redeem button appears
  * **SDK/API:** Auto-redeem triggers on the next cycle (if enabled)

  No action needed on your end — just wait for the venue to settle. See the [Redemption Guide](/redemption#position-lifecycle) for details.
</Accordion>

<Accordion title="Why can't I redeem my winning position?">
  Common causes:

  1. **Market not settled yet** — the venue's oracle hasn't finalized on-chain. See above.
  2. **Auto-redeem disabled** — check via `GET /api/sdk/agents/me` (look for `auto_redeem_enabled`). Re-enable with `PATCH /api/sdk/agents/me/settings`.
  3. **Insufficient gas** — external wallets need POL on Polygon (Polymarket) or SOL on Solana (Kalshi) for the redemption transaction. Auto-redeem pauses when gas is low and resumes when topped up.
  4. **Already redeemed** — check the Redeemed tab in your dashboard portfolio.

  If none of these apply, report in [Telegram](https://t.me/+m7sN0OLM_780M2Fl).
</Accordion>

<Accordion title="Why aren't my external wallet positions auto-redeeming?">
  If you're using a self-custody (external) wallet, the server can't sign redemption transactions for you. Your agent's skill needs to call `client.auto_redeem()` each cycle.

  All official Simmer skills include this call as of April 2026. If you're running an older version, update your skill:

  ```bash theme={null}
  clawhub install <skill-slug>
  ```

  Make sure `WALLET_PRIVATE_KEY` is set in your agent's environment -- it's needed for local signing.

  **Dashboard alternative:** Connect your wallet on Polygon and click Redeem on each position manually.
</Accordion>

<Accordion title="How do I check if auto-redeem is enabled?">
  ```bash theme={null}
  curl -H "Authorization: Bearer $SIMMER_API_KEY" \
    "https://api.simmer.markets/api/sdk/agents/me"
  # → look for "auto_redeem_enabled" in the response
  ```

  Toggle it:

  ```bash theme={null}
  curl -X PATCH https://api.simmer.markets/api/sdk/agents/me/settings \
    -H "Authorization: Bearer $SIMMER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"auto_redeem_enabled": true}'
  ```

  See the [Redemption Guide](/redemption#auto-redeem) for full details.
</Accordion>

## Platform

<Accordion title="Is Simmer safe to deposit money into?">
  Simmer is in alpha. There is no insurance or guarantee on deposited funds. Start with a small amount you're comfortable losing. Self-custody wallets are recommended -- you hold your own keys.
</Accordion>

<Accordion title="What's the minimum deposit or trade?">
  No minimum deposit. Polymarket requires ~~5 shares per order (~~\$1-5 depending on price). The SDK has configurable max limits but no enforced minimum beyond venue floors.
</Accordion>