Agent coordination

acquire_leaseCopy Anchor Link

Lease position:<position_uid> or symbol:<SYMBOL> on this connection for ttl_sec (1-3600) so other agents cannot change it; returns lease_token and expires_at, or LEASED with the holder. Trading commands on a leased resource need the holder's lease_token (otherwise LEASED); a symbol lease also covers that symbol's positions. Available on every tier.

Capability: read · read-only · REST: POST /v1/tools/acquire_lease

Example request:

{
  "resource": "<resource>",
  "owner": "<owner>",
  "ttl_sec": 1
}

release_leaseCopy Anchor Link

Release a lease with its lease_token (LEASE_TOKEN_MISMATCH for another holder's token, LEASE_NOT_FOUND when it already expired). Available on every tier.

Capability: read · read-only · REST: POST /v1/tools/release_lease

Example request:

{
  "resource": "<resource>",
  "lease_token": "<lease_token>"
}

get_leasesCopy Anchor Link

Active leases on this connection (resource, owner, expires_at), order:"soonest_expiry_first". Tokens are never shown. Available on every tier.

Capability: read · read-only · REST: POST /v1/tools/get_leases

No parameters.

Example request:

{}

heartbeatCopy Anchor Link

Dead-man's switch: "if I am silent for ttl_sec (30-86400), do on_expire". Every call refreshes the deadline. on_expire: alert (default) | breakeven_if_profitable (buffer_bps) | tighten_to_r (r) | close_all (optional symbol). Arming or changing a trading action needs dry_run:false and the trade capability (paper sessions never arm one); otherwise the reply shows would_arm. The server runs it on its own, once per missed deadline, never loosening a stop. Requires the trade capability (Pro and above; simulated connections may trade on every tier).

Capability: trade · mutating · REST: POST /v1/tools/heartbeat

Example request:

{
  "owner": "<owner>",
  "ttl_sec": 30,
  "dry_run": true
}

get_heartbeat_statusCopy Anchor Link

Heartbeats on this connection: deadline, seconds_left, last ping, armed action, status active|expired and the last expiry's per-position outcome. order:"soonest_deadline_first". Available on every tier.

Capability: read · read-only · REST: POST /v1/tools/get_heartbeat_status

Example request:

{}