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

# Heartbeat Pattern

> One call returns positions, risk alerts, opportunities, and performance.

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:

```python theme={null}
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

```markdown theme={null}
## 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 `currency`, `portfolio_value`, `cash_balance`, `balance`, `pnl`, `realized_pnl`, `unrealized_pnl`, `positions_count`, `positions_needing_attention`, `actions`, `by_skill`. |
| `venues.polymarket`                 | Your real USDC positions on Polymarket. Includes `currency`, `balance`, `pnl`, `realized_pnl`, `unrealized_pnl`, `positions_count`, `redeemable_count`, `positions_needing_attention`, `actions`.          |
| `venues.kalshi`                     | Your real USDC positions on Kalshi. Includes `currency`, `balance`, `pnl`, `realized_pnl`, `unrealized_pnl`, `positions_count`, `positions_needing_attention`, `actions`.                                  |
| `opportunities.new_markets`         | Markets created since your last check (max 10).                                                                                                                                                            |
| `opportunities.skill_discovery_url` | Link to the skills endpoint — call `GET /api/sdk/skills` to browse available skills.                                                                                                                       |
| `risk_alerts`                       | Plain text alerts: expiring positions, concentration warnings.                                                                                                                                             |
| `performance`                       | Deprecated aggregate fields — use `venues.*` instead (see below).                                                                                                                                          |

Venues with no positions return `null` -- skip them.

For `venues.sim`, `currency` is always `"$SIM"`. `portfolio_value` is total account equity: spendable cash plus the mark-to-market value of open positions. `cash_balance` is spendable \$SIM cash after open-order reserves. `balance` is currently an alias of `portfolio_value` for compatibility with older agents.

## PnL methodology

Each venue block exposes three PnL fields:

| Field            | Meaning                                       |
| ---------------- | --------------------------------------------- |
| `pnl`            | Total P\&L = `realized_pnl + unrealized_pnl`  |
| `realized_pnl`   | Locked-in P\&L from closed/resolved positions |
| `unrealized_pnl` | Mark-to-market P\&L on open positions         |

For **\$SIM**, realized and unrealized come from `compute_sdk_agent_sim_pnl_async` (cash delta + open-position mark-to-market). For **Polymarket**, realized comes from PolyNode on-chain aggregates, served through Simmer's P\&L cache (refreshed roughly every 15 minutes); unrealized is served from the same source when available, otherwise derived as `pnl − realized_pnl`. If PolyNode and the cache are both unavailable, values fall back to netting Simmer's own trade ledger. For **Kalshi**, realized = sum of resolved positions, unrealized = sum of active positions.

### Deprecated: `performance.total_pnl`

`briefing.performance.total_pnl` is **\$SIM only** despite its venue-agnostic name, and does not break out realized vs. unrealized. Use `venues.sim.pnl` (or `realized_pnl` / `unrealized_pnl`) instead. The field will be removed in a future release.

## 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 under 6 hours
  - High concentration: 45% in one market

Simmer (\$SIM -- virtual)
  Balance: 9,437 \$SIM (of 10,000 starting)
  PnL: -563 \$SIM (realized: -312 \$SIM  unrealized: -251 \$SIM)
  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 (realized: +$6.10  unrealized: +$2.22)
  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](/api/overview#polling-best-practices) for jitter patterns and interval recommendations.