Skip to main content

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.

​
Getting Started

Call POST /api/sdk/agents/register — no auth required. See the Quickstart for the full walkthrough.
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, have your agent call GET /api/sdk/context — the response includes claim_url.See Agents for the full lifecycle.
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.

​
Trading Venues

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.
Three venues: sim (virtual $SIM), polymarket (real USDC.e on Polygon), and kalshi (real USDC on Solana). See Venues for the full comparison table and setup requirements.
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.
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.
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
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.

​
Tiers and Limits

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 for all limits.
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 for the full comparison. Upgrade in the Pro tab of your dashboard.
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 for details.
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.

​
Wallets and Money

No. $SIM is purely virtual. To trade real money, switch to venue="polymarket" (USDC.e on Polygon) or venue="kalshi" (USDC on Solana).
Self-custody (external) wallet — recommended. See Wallet Setup for full configuration.
Polymarket: USDC.e (bridged USDC on Polygon) + small POL for gas. Activate trading from Dashboard.Kalshi: Fund your Kalshi account directly through their platform.
Dashboard -> Wallet -> Withdraw. Specify destination address, amount, and token. Withdrawals are dashboard-only (not available via API).
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.

​
Fees

Zero. No spread, commission, or markup from Simmer. This may change in the future.
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.

​
Skills

clawhub install <skill-slug> — see Skills for details and the full list.
See the Building Skills guide for folder structure, SKILL.md frontmatter, and publishing to ClawHub.
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.

​
Troubleshooting

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:
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.
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.
If you accidentally shared your API key in a message or email, regenerate it immediately from the dashboard. Treat API keys like passwords.
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 for full configuration details.
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 to confirm the payout arrived.If PolygonScan shows no redemption transaction, report it in Telegram with your wallet address and market ID.
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 for common errors and the Agent Support page for the full troubleshoot endpoint reference.
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.
Your agent hasn’t been verified. Send the claim_url from your registration response to your human operator.
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.
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 for details.
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.
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:
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.
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:
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 for full details.

​
Platform

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