Heartbeat

Overview

Heartbeat includes 2 tools for this workflow area.

Available tools: get_heartbeat_status, heartbeat.

Use the parameter tables and examples below as the canonical request contract.

get_heartbeat_status

Reports every heartbeat owner on this terminal, by owner name: ttl_sec, on_expire and on_expire_params, last_seen, deadline, effective_deadline (the deadline, or one TTL after the terminal last connected if that is later), seconds_remaining (negative when overdue) and state, all times UTC ISO. State is ok, grace_after_reconnect (overdue but the terminal reconnected recently), overdue_offline (overdue while the terminal is disconnected), overdue_no_positions (overdue, nothing to protect, will act if positions appear), pending_expiry (overdue with positions open, the platform is about to act) or expired (the action already ran: expired_at and a per-position result are shown until the owner sends its next heartbeat). Also returns terminal_connected, open_positions (only when some owner is overdue) and pending_expiries. Requires the read capability.

Parameters

No parameters.

Example Request

{
  "tool": "get_heartbeat_status",
  "arguments": {}
}

heartbeat

Dead-man's switch. Call this regularly to say "I am still running". If an owner sends no heartbeat for ttl_sec seconds while positions are open, the platform itself (no agent needed) runs on_expire once, adds a heartbeat_expired event to manage_alerts(action="poll"), fires any heartbeat_expired alerts (which sends their webhooks) and writes journal entries. Each call refreshes the deadline to now + ttl_sec and replaces the stored configuration (see dry_run below for when that needs dry_run:false).

owner names whoever is responsible, e.g. "position_manager" (self-declared: any caller with trade access can refresh or clear any owner). Each owner has its own deadline and action; at most 20 owners per terminal. ttl_sec is in SECONDS, 30 to 86400. Set it comfortably longer than your longest quiet gap: an expiry can close positions.

on_expire: "alert" only notifies. "breakeven_if_profitable" moves the stop of each position that is in profit to its entry price (on_expire_params {buffer_points?} are POINTS beyond entry, default 0). "tighten_to_r" (on_expire_params {r} required, multiples of the initial risk) moves the stop to lock r×R, measured from the R basis of an active exit plan on that position; positions without one are skipped and reported. "close_all" closes every open position at market (on_expire_params {symbol?} limits it to one symbol). Stops are never loosened and a stop changed by someone else in the meantime is not overwritten. The action ignores leases, because its job is to protect positions when the agent that holds them is gone.

Restart safety: when an owner is overdue and the terminal has reconnected since its last heartbeat, it gets one full ttl_sec counted from that reconnect before it can expire, so a restart of the terminal, EA or server is not mistaken for a missed heartbeat. That grace is granted once per missed deadline: later reconnects do not extend it. Expiry only happens while the terminal is connected and has open positions; if none are open when the deadline passes, nothing happens and the owner is checked again later. A heartbeat sent while the terminal is offline is recorded.

clear=true removes the owner so it can never expire (NOT_FOUND if it does not exist). dry_run: a plain heartbeat that repeats the stored configuration (same ttl_sec, on_expire and on_expire_params), and any on_expire "alert", is applied directly. Arming, re-arming after an expiry, or changing an on_expire that trades (breakeven_if_profitable, tighten_to_r, close_all) is only previewed (dry_run:true in the response, the stored owner is still refreshed) unless you pass dry_run:false; in paper mode it is never armed (mode_clamped:true). dry_run=true always just validates. Returns owner, ttl_sec, on_expire, last_seen, deadline, effective_deadline (UTC ISO times), seconds_remaining and state. Requires the trade capability.

Parameters

Example Request

{
  "tool": "heartbeat",
  "arguments": {
    "owner": "owner_value",
    "dry_run": true
  }
}

Usage Notes

• Keep dry_run: true until you have validated symbol, lot size, and expected execution behavior.