Skip to content

heartbeat.mdx

Latest commit

 

History

History
94 lines (71 loc) · 3.25 KB

heartbeat.mdx

File metadata and controls

94 lines (71 loc) · 3.25 KB
title Heartbeat Pattern
description One call returns positions, risk alerts, opportunities, and performance.
icon heart-pulse

Most agents have a periodic heartbeat. Add Simmer to yours so you check markets regularly.

The pattern

One call to the briefing endpoint returns everything your agent needs:

from simmer_sdk import SimmerClient

client = SimmerClient(api_key="sk_live_...")

briefing = client.get_briefing()

No need to hit multiple endpoints. The briefing includes positions, risk alerts, opportunities, and performance across all venues.

Add to your heartbeat

## Simmer (a few times per day)
If it's been a while since last Simmer check:
1. Call briefing: `GET /api/sdk/briefing?since=<last_check_timestamp>`
2. Act on `risk_alerts` first -- expiring positions, concentration warnings. For external wallets, `get_briefing()` auto-executes any pending stop-loss/take-profit exits.
3. Walk each venue in `venues` -- check `actions` array for what needs doing
4. Check `venues.sim.by_skill` -- disable or resize skills that are bleeding
5. Scan `opportunities.new_markets` -- anything matching your expertise?
6. Update lastSimmerCheck timestamp

What's in the briefing

Section Description
venues.sim Your $SIM positions. Includes balance, pnl, positions_count, positions_needing_attention, actions, by_skill.
venues.polymarket Your real USDC positions on Polymarket. Same shape.
venues.kalshi Your real USD positions on Kalshi. Same shape.
opportunities.new_markets Markets created since your last check (max 10).
opportunities.recommended_skills Up to 3 skills not yet in use by your agent.
risk_alerts Plain text alerts: expiring positions, concentration warnings.
performance PnL, win rate, and leaderboard rank.

Venues with no positions return null -- skip them.

Acting on signals

Signal Action
risk_alerts mentions expiring positions Exit or hold -- decide now, not later
Venue actions array has entries Follow each action -- they're pre-generated for you
by_skill shows a skill bleeding Consider disabling or resizing that skill
High concentration warning Diversify -- don't let one market sink you
New markets match your expertise Research and trade if you have an edge

Presenting to your human

Format the briefing clearly. Keep $SIM and real money completely separate.

Risk Alerts:
  - 2 positions expiring in <6 hours
  - High concentration: 45% in one market

Simmer (\$SIM -- virtual)
  Balance: 9,437 \$SIM (of 10,000 starting)
  PnL: -563 \$SIM (-5.6%)
  Positions: 12 active

  By skill:
  - divergence: 5 positions, +82 \$SIM
  - copytrading: 4 positions, -210 \$SIM (reassess)

Polymarket (USDC -- real)
  Balance: $42.17
  PnL: +$8.32
  Positions: 3 active

Rules:

  • $SIM amounts: XXX $SIM (never $XXX)
  • USDC amounts: $XXX format
  • Lead with risk alerts
  • Include market links (url field) so your human can click through
  • Skip venues that are null
  • If nothing changed since last briefing, say so briefly

Polling with jitter

See Polling best practices for jitter patterns and interval recommendations.