Overview
The heartbeat endpoint provides aggregated status information in a single call. Instead of polling multiple endpoints, agents call this periodically to see portfolio changes, pending actions, and budget status.
The heartbeat response includes a suggested next_check_at timestamp and latest_skill_version for informational purposes. Use these to decide when to check again and whether a skill update is available on ClawHub.
Get Heartbeat
Get current status, action items, portfolio summary, and scheduling info.
read
Example
curl "https://luckylobster.io/api/agent/v1/heartbeat?skill_version=9" \
-H "Authorization: Bearer ll_..."
| Parameter | Required | Description |
|---|
skill_version | optional | Your current skill.md version (from metadata.openclaw.version). The response includes latest_skill_version so you can compare. |
Response - Active (OK)
When there are no pending actions:
{
"success": true,
"data": {
"status": "OK",
"timestamp": "2026-02-06T14:30:00Z",
"portfolio": {
"openPositions": 3,
"totalValue": 185.50,
"unrealizedPnl": 12.30,
"redeemableCount": 0,
"redeemableValue": 0
},
"orderActivity": {
"openOrders": 1,
"filledSinceLastHeartbeat": 0,
"recentFills": []
},
"budget": {
"available": 46.58,
"limitedBy": "percent",
"walletBalance": 93.16
},
"heartbeat": {
"next_check_at": "2026-02-06T14:31:00Z",
"interval_ms": 60000,
"active_hours": {
"start": "08:00",
"end": "22:00",
"timezone": "America/New_York"
},
"heartbeat_count": 42,
"latest_skill_version": 9
}
}
}
Response - Active (ACTION_NEEDED)
When actions may need attention, the actions array is included:
{
"success": true,
"data": {
"status": "ACTION_NEEDED",
"timestamp": "2026-02-06T14:30:00Z",
"actions": [
{
"type": "REDEEM",
"priority": "high",
"summary": "2 position(s) ready to redeem (~$42.50)",
"details": {
"count": 2,
"estimatedValue": 42.50,
"positions": [
{
"conditionId": "0xbc13af0a...",
"title": "Bitcoin Up or Down - February 4",
"outcome": "Down",
"size": 5.0
}
],
"action": "POST /settlements/redeem"
}
},
{
"type": "ORDER_FILLED",
"priority": "medium",
"summary": "1 order(s) filled since last check",
"details": {
"count": 1,
"totalPnl": 3.25,
"fills": [
{
"id": "ord_abc123",
"side": "SELL",
"size": 50,
"filledSize": 50,
"avgFillPrice": 0.65,
"realizedPnl": 3.25,
"marketQuestion": "Bitcoin Up or Down?",
"outcome": "Up",
"filledAt": "2026-02-06T14:28:00Z"
}
]
}
}
],
"portfolio": { "..." : "..." },
"orderActivity": { "..." : "..." },
"budget": { "..." : "..." },
"heartbeat": { "..." : "..." }
}
}
Response - Sleeping
When outside configured active hours:
{
"success": true,
"data": {
"status": "SLEEPING",
"timestamp": "2026-02-06T03:00:00Z",
"message": "Outside active hours (08:00-22:00 America/New_York). Suggested next check at next_check_at.",
"heartbeat": {
"next_check_at": "2026-02-06T03:01:00Z",
"interval_ms": 60000,
"active_hours": {
"start": "08:00",
"end": "22:00",
"timezone": "America/New_York"
},
"heartbeat_count": 200,
"latest_skill_version": 9
}
}
}
Status Values
| Status | Meaning |
|---|
OK | Within active hours, no actions needed |
ACTION_NEEDED | Within active hours, actions may need attention |
SLEEPING | Outside configured active hours |
Action Types
Actions are returned in the actions array, sorted by priority.
| Type | Priority | Description |
|---|
REDEEM | high | Settled positions ready to redeem. Call POST /settlements/redeem. |
ORDER_FILLED | medium | Orders filled since the last heartbeat, with P&L details. |
BUDGET_LOW | medium | Budget below $5 or less than 10% of limit remaining. |
POSITION_EXPIRING | low | Open positions in markets closing within 30 minutes. |
SEEK_TRADES | low | Budget available - trading opportunities may exist. |
STRATEGY_EXECUTED | medium | Trades placed by your autonomous strategies. |
STRATEGY_ERROR | high | Strategies auto-paused after consecutive errors. |
STRATEGY_COMPLETED | low | Strategies that finished (budget exhausted or trigger fired). |
STRATEGY_PAUSED | high | Strategy paused by the user from the dashboard. POST /strategies/{id}/resume to restart. |
STRATEGY_CANCELLED | high | Strategy cancelled by the user from the dashboard. Create a new strategy if needed. |
Heartbeat Scheduling
Every response (including SLEEPING) includes a heartbeat object with scheduling information:
| Field | Type | Description |
|---|
next_check_at | string | ISO 8601 timestamp - suggested time for next check |
interval_ms | int | Heartbeat interval in milliseconds (configured per API key) |
active_hours | object|null | Configured active hours (start, end, timezone), or null if always active |
heartbeat_count | int | Total heartbeats recorded for this API key |
latest_skill_version | int | Latest skill version available - compare with your version to check for updates on ClawHub |
Use next_check_at as a scheduling suggestion. The server computes this based on your API key’s configuration.
Response Fields
portfolio
| Field | Type | Description |
|---|
openPositions | int | Number of open positions |
totalValue | float | Total value of open positions |
unrealizedPnl | float | Unrealized P&L across open positions |
redeemableCount | int | Positions ready to redeem |
redeemableValue | float | Estimated value of redeemable positions |
orderActivity
| Field | Type | Description |
|---|
openOrders | int | Number of open/pending orders |
filledSinceLastHeartbeat | int | Orders filled since last heartbeat |
recentFills | array | Details of recently filled orders |
budget
| Field | Type | Description |
|---|
available | float | How much you can spend right now |
limitedBy | string | Which constraint is active: wallet, fixed_limit, percent, position_limit |
walletBalance | float | Raw wallet USDC balance |
