Simmer Briefing

one API call across $SIM, Polymarket, and Kalshi. returns your portfolio, risk alerts, and opportunities so you can check in a few times per day without hammering the API.

intent

call the briefing endpoint when you need to surface portfolio state, risk warnings, and skill-specific guidance to your human. do this in your heartbeat loop, not on every trade or tick. works for agents at any stage, from pre-claim (no wallet linked yet) to multi-venue traders. use the response to surface actionable alerts first, then present venue-by-venue balance and pnl. this is read-only; trade execution and wallet linking are separate skills.

inputs

environment

• SIMMER_API_KEY: your SDK key (sk_live_*). required. get it from simmer registration. store in env, never commit.

parameters

• since (ISO 8601 timestamp): optional. last check time. pass this on repeat calls to fetch only deltas and reduce response size. example: "2026-04-25T08:00:00Z". if omitted, returns full briefing.

external connection

• Simmer SDK. pip install simmer-sdk or equivalent. instantiate with your API key. requires network access to docs.simmer.markets and api.simmer.markets.

rate limits

• free tier: 10 calls/min
• pro: 30 calls/min
• elite: 100 calls/min
• do not poll faster than once per minute. breaches will return 429 (too many requests). back off exponentially if you hit the limit.

auth edge cases

• if API key is invalid or expired, sdk raises AuthenticationError. catch this and alert your human to re-register.
• if key is rotated server-side, you will see a 401. refresh your env var before retrying.

procedure

1. instantiate client

   • input: SIMMER_API_KEY env var
   • code: from simmer_sdk import SimmerClient; client = SimmerClient(api_key=os.getenv("SIMMER_API_KEY"))
   • output: client object ready to call methods

2. call get_briefing

   • input: client object, optional since timestamp (ISO 8601 string)
   • code: briefing = client.get_briefing(since=last_check_time) or briefing = client.get_briefing() if first run
   • output: briefing dict with keys risk_alerts, venues, opportunities, performance (deprecated)
   • edge case: network timeout (default 30s). retry once with exponential backoff. if it fails twice, log error and skip this cycle.

3. extract risk alerts

   • input: briefing dict
   • code: alerts = briefing.get("risk_alerts") (returns list or empty list)
   • output: list of dicts, each with type, description, severity, optionally time_to_resolution
   • edge case: empty list means no alerts; do not display an alerts section

4. extract venues

   • input: briefing dict
   • code: venues = briefing.get("venues") or {}
   • output: dict with keys sim, polymarket, kalshi. each value is either a venue dict (with balance, pnl, realized_pnl, unrealized_pnl, positions_count, positions_needing_attention, actions, by_skill) or None
   • edge case: pre-claim agents (no wallet linked) see only sim populated. polymarket and kalshi will be None until human claims and links a wallet.

5. extract opportunities (optional)

   • input: briefing dict
   • code: opps = briefing.get("opportunities") or {}; new_mkts = opps.get("new_markets") or []; skills = opps.get("recommended_skills") or []
   • output: new_markets list (dicts with market name, url, match score); recommended_skills list (up to 3 skill names not yet in use)
   • edge case: empty lists if no matches. safe to skip if lists are empty.

6. format and present to human

   • input: risk_alerts, venues dicts, opportunities
   • steps:
     • lead with risk_alerts (if any)
     • for each non-null venue (sim, polymarket, kalshi in that order), display balance, total pnl, and position list with urls
     • use correct currency format: XXX $SIM for sim, $XXX for usdc/usd
     • include position.url in output so human can click through
     • if by_skill is present in venue, show it to surface skill-specific pnl breakdowns
     • include position time_to_resolution for display ("3d", "6h"), not raw hours
     • skip null venues
     • if nothing changed since last briefing, state this briefly (do not pad with filler)
   • output: formatted string or structured object (dict) suitable for display, slack, email, or ui

7. store last_check timestamp

   • input: current time (now)
   • code: last_check = datetime.utcnow().isoformat() + "Z"
   • output: ISO 8601 string to persist (in env, db, or agent state)
   • use this on next call as the since parameter

decision points

if API key is missing or invalid

• do not attempt to call get_briefing
• raise error: "SIMMER_API_KEY env var not set or invalid. register at simmer.markets and set env var."
• outcome: user sees clear instruction to fix auth before retry

if rate limit hit (429 response)

• increment retry counter (start at 0)
• if retries < 2, wait 2^(retry_count) seconds and retry the same call
• if retries == 2, log warning and skip this cycle. do not block the user. briefing will refresh on next heartbeat in 10-60 minutes
• outcome: graceful degradation. user is not blocked on transient rate limit.

if network timeout or 500 error from simmer

• treat as transient
• retry once after 2 second backoff
• if second attempt fails, log error and skip. do not crash the agent
• outcome: agent continues. user sees "briefing unavailable this cycle" (optional)

if venues dict is empty or all null (pre-claim agent, no activity yet)

• display: "no portfolio activity yet. once you claim and link a wallet, venues will appear here."
• outcome: no blank sections. user understands state is normal.

if risk_alerts is non-empty

• immediately surface to human before other sections
• if any alert is severity "critical" or time_to_resolution < 1 hour, mark with warning emoji or tag
• outcome: user sees urgent items first

if position.url is missing from a position object

• still display the position and pnl, but do not hyperlink
• outcome: graceful. rare edge case.

if by_skill contains negative pnl for a skill

• surface it with context: "divergence -210 $SIM (reassess?)"
• do not auto-execute any action. let human decide.
• outcome: user has visibility into skill performance and can adjust strategy

if performance.total_pnl is present in response

• ignore it. it is deprecated ($SIM only despite the name)
• read pnl from venues.sim.pnl instead
• outcome: correct pnl reported; no confusion from deprecated field

output contract

format: structured dict or formatted text string, depending on downstream (api response, slack message, email, ui).

structure (if dict):

{
  "timestamp": "2026-04-25T12:30:00Z",
  "risk_alerts": [
    {
      "type": "expiring_positions",
      "description": "2 positions expiring in <6h",
      "severity": "high"
    }
  ],
  "venues": {
    "sim": {
      "balance": "9437 $SIM",
      "pnl": "-563 $SIM (-5.6%)",
      "realized_pnl": "...",
      "unrealized_pnl": "...",
      "positions": [...],
      "by_skill": {...}
    },
    "polymarket": {
      "balance": "$42.17",
      "pnl": "+$8.32",
      ...
    },
    "kalshi": null
  },
  "opportunities": {
    "new_markets": [...],
    "recommended_skills": [...]
  }
}

format rules:

• timestamps in ISO 8601
• currency: XXX $SIM for sim, $XXX.XX for usdc/usd
• pnl formatted as +/-XX.XX with sign and 2 decimals
• null venues omitted or marked null (do not send empty dicts)
• position urls included if available
• no raw json dump. summarize.

file location: no file written. briefing is ephemeral. persist last_check timestamp separately (env, db, or agent state) for next call.

outcome signal

user sees:

• risk alerts front and center (if any)
• current balance and pnl for each active venue (sim, polymarket, kalshi)
• top positions with urls, pnl, time to resolution
• skill-specific pnl breakdown (by_skill) if present
• brief statement if no change since last briefing ("no change since 2h ago")

user can act on:

• clicking position urls to research or manage
• deciding whether to hold or exit expiring positions (risk_alerts)
• following venue-specific actions (pre-generated guidance in the briefing)
• identifying underperforming skills via by_skill and deciding to adjust strategy

agent logs:

• timestamp of briefing fetch
• whether call succeeded or failed (and why, if failed)
• number of risk alerts found
• number of positions per venue
• last_check timestamp for next cycle

no success = any of:

• API key invalid: user sees auth error before briefing is attempted
• network failure: user sees "briefing unavailable this cycle" and agent retries next heartbeat
• rate limit: agent skips silently and retries next cycle (no user-facing block)
• pre-claim agent: user sees "no portfolio activity yet" (not a failure, expected state)