Health Check

Overview

In Lasso RPC Core v0.5.0, this endpoint reports application liveness, uptime, and cluster connectivity. It does not test whether an upstream can serve a request.

Endpoint

GET /api/health

Response

Returns a JSON object containing instance health information:

string

required

Application liveness status (“healthy” when this endpoint responds)

string

required

ISO 8601 timestamp of the health check

integer

required

Time in seconds since the Lasso RPC instance started

string

required

Current version of Lasso RPC

object

required

Cluster connectivity and status information

Show cluster properties

boolean

required

Whether clustering is enabled for this instance

integer

required

Number of cluster nodes currently connected

integer

required

Number of cluster nodes actively responding to health checks

integer

required

Expected total number of nodes in the cluster

array

required

List of geographic regions where cluster nodes are deployed

string

required

Status derived from responding versus connected nodes: standalone, healthy, degraded, or critical

Response Example

{
  "status": "healthy",
  "timestamp": "2026-03-03T21:45:30.123456Z",
  "uptime_seconds": 86400,
  "version": "0.5.0",
  "cluster": {
    "enabled": true,
    "nodes_connected": 3,
    "nodes_responding": 3,
    "nodes_total": 3,
    "regions": ["us-east-1", "eu-west-1", "ap-southeast-1"],
    "status": "healthy"
  }
}

Cluster Status Values

The cluster.status field indicates the overall health of your cluster deployment:

Clustering is not enabled. Instance is running independently.

Every connected node is responding. This does not establish that every expected node is connected.

Fewer nodes are responding than connected, but the responding count is at least floor(nodes_connected / 2).

The responding count is below floor(nodes_connected / 2).

The status calculation uses nodes_connected, not nodes_total. Monitor both counts to detect missing expected nodes; cluster.status alone does not prove full cluster coverage. This is the behavior of the released health controller and topology status function.

Route readiness

GET /api/ready checks whether the selected file profile has an eligible HTTP route and a fresh head observation for each selected chain. It defaults to the public profile and all its configured chains. Add profile and chain query parameters to check one route:

curl 'http://localhost:4000/api/ready?profile=public&chain=ethereum'

The endpoint returns HTTP 200 with status: "ready" when every selected chain is ready. It returns HTTP 503 with status: "not_ready" otherwise. Each item in checks includes chain_id, status, and a reason: either no_eligible_upstream, stale_or_missing_head, or null when ready. An unknown profile or chain returns reason: "profile_or_chain_not_configured". Readiness uses local state. It does not call an upstream or prove a particular RPC method will succeed. Monitor an upstream-backed request separately.

Use Cases

Load Balancer Health Checks

Configure your load balancer to poll this endpoint:

curl http://localhost:4000/api/health

Monitoring and Alerts

Integrate with monitoring systems to track uptime and cluster status:

# Check if instance is healthy
response=$(curl -s http://localhost:4000/api/health)
status=$(echo $response | jq -r '.status')

if [ "$status" != "healthy" ]; then
  echo "Alert: Lasso RPC is not healthy"
fi

Cluster Health Monitoring

Monitor cluster connectivity in distributed deployments:

# Alert if cluster is degraded
cluster_status=$(curl -s http://localhost:4000/api/health | jq -r '.cluster.status')

if [ "$cluster_status" = "degraded" ] || [ "$cluster_status" = "critical" ]; then
  echo "Alert: Cluster is $cluster_status"
fi

Notes

This endpoint responds immediately and does not perform heavy computation
It does not make a live upstream RPC call; pair it with provider and routing monitoring
A healthy response confirms application availability, not that every upstream is usable
When clustering is disabled, cluster.enabled is false and cluster.status is standalone

HTTP API

WebSocket API

Status and metrics

Reference

Releases and evidence

Health Check

Overview

Endpoint

Response

Response Example

Cluster Status Values

Route readiness

Use Cases

Load Balancer Health Checks

Monitoring and Alerts

Cluster Health Monitoring

Notes

​Overview

​Endpoint

​Response

​Response Example

​Cluster Status Values

​Route readiness

​Use Cases

​Load Balancer Health Checks

​Monitoring and Alerts

​Cluster Health Monitoring

​Notes

Overview

Endpoint

Response

Response Example

Cluster Status Values

Route readiness

Use Cases

Load Balancer Health Checks

Monitoring and Alerts

Cluster Health Monitoring

Notes