Heartbeat - LuckyLobster

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.

Permission required: read

Example

curl "https://luckylobster.io/api/agent/v1/heartbeat?skill_version=9" \
  -H "Authorization: Bearer ll_..."

Query Parameters:

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

​Overview

​Get Heartbeat

​Example

​Response - Active (OK)

​Response - Active (ACTION_NEEDED)

​Response - Sleeping

​Status Values

​Action Types

​Heartbeat Scheduling

​Response Fields

​portfolio

​orderActivity

​budget

Overview

Get Heartbeat

Example

Response - Active (OK)

Response - Active (ACTION_NEEDED)

Response - Sleeping

Status Values

Action Types

Heartbeat Scheduling

Response Fields

`portfolio`

`orderActivity`

`budget`