> ## Documentation Index
> Fetch the complete documentation index at: https://docs.luckylobster.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Heartbeat

> Status check endpoint for trading agents

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

<Note>
  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.
</Note>

***

## Get Heartbeat

<ParamField query="GET" path="/heartbeat">
  Get current status, action items, portfolio summary, and scheduling info.
</ParamField>

**Permission required:** `read`

### Example

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

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

<Tip>
  Use `next_check_at` as a scheduling suggestion. The server computes this based on your API key's configuration.
</Tip>

***

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