Neon Zero

Gate Status API

Each Neon Zero region's gate verdict and its measured latency to past, current and upcoming slot leaders, over JSON-RPC.

The Gate Status API reports each Neon Zero region's gate and each region's own measured distance to the slot leaders. Two JSON-RPC 2.0 methods answer on the region's Neon Zero URL: getNeonGate reports the gate right now, and getNeonLeaders reports leader windows from the last 24 hours to the windows measured ahead.

Endpoint

RegionURL
United States flag New Yorkhttps://neon-rpc-newyork.constant-k.com/?api-key=YOUR_API_KEY
Germany flag Frankfurthttps://neon-rpc-frankfurt.constant-k.com/?api-key=YOUR_API_KEY
Netherlands flag Amsterdamhttps://neon-rpc-amsterdam.constant-k.com/?api-key=YOUR_API_KEY

The client POSTs a JSON-RPC 2.0 request to the same URL it sends sendTransaction through. Authentication is the same as on the other Neon Zero requests: the api-key query parameter or the x-api-key header. Each region answers with its own gate and its own measurements; the site field names the region that replied.

Access

  • Nexus plan only. A key on another plan gets HTTP 403 with error -32600, as on the other Neon Zero requests.
  • Neither method counts against any rate limit. A key can poll as often as needed.
  • Rapid repeats are cached at the edge for a fraction of a second: a live answer may be up to 0.2 s old, and a range of past leaders only for 30 s.
  • A batch carrying either method is refused with error -32600.

getNeonGate

No params. Returns the gate state for this region at this instant. The verdict is the same word a sendTransaction sent at this instant would get.

FieldMeaning
siteThe region that answered: newyork, frankfurt or amsterdam.
opentrue when a sendTransaction sent now is forwarded.
verdictWhy the gate is open or closed. See the verdict table below.
slotThe current slot. Omitted when the clock has no reading.
leaderThe current slot's leader, base58. null for a moment right after a slot change.
leader_checkThe leader test for the current slot: ok, rtt_far, rtt_unknown, deny, none, or - when no data arrived.
rtt_msMeasured round-trip time to the current leader, in ms. null when not measured.
ms_into_slotMilliseconds into the current leader's slot. Omitted when the clock has no reading.
max_rtt_msThe gate's distance cutoff: a leader farther than this never opens the gate.
max_into_msThe gate's cutoff for milliseconds into the slot.
next_openThe next leader window this region would open for, or null when no upcoming window would open the gate.
healthyWhether the region's gate reports itself healthy.
now_msThe current time, in unix ms.
data_age_msHow old the gate's data is, in ms. -1 when unknown.

The reply also carries version, slot_start_ms, rtt_src and slot_ms when known.

next_open fields:

FieldMeaning
first_slotThe window's first slot.
leaderThe window's leader, base58.
rtt_msMeasured round-trip time to that leader, in ms.
eta_msMilliseconds from now until that window begins, never negative. 0 when the window begins now.

Verdicts:

VerdictGateMeaning
openOpenThe leader is close to this region and its slot has just begun.
lateClosedToo far into the leader's slot.
rtt_farClosedThe leader is too far from this region.
rtt_unknownClosedThe latency to the leader is not measured yet.
denyClosedThe leader is excluded from the gate.
noneCannot decideNo leader is known for the current slot.
unhealthyCannot decideThe region's gate reports itself unhealthy.
staleCannot decideThe gate's data is more than a second old.
no_clockCannot decideThe clock has no reading for the current slot.
nodaemonCannot decideNo gate data arrived.

While the gate is closed or cannot decide, sendTransaction is not forwarded.

curl "https://neon-rpc-frankfurt.constant-k.com/?api-key=YOUR_API_KEY" \
  -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getNeonGate"}'
getNeonGate reply
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "site": "frankfurt",
    "open": true,
    "verdict": "open",
    "slot": 456542917,
    "leader": "GbkvTn7nQK9rJYqTzXwQhZ8vLpRdCm5aKqTgHsYbNcP",
    "leader_check": "ok",
    "rtt_ms": 15.8,
    "ms_into_slot": 20.7,
    "max_rtt_ms": 50,
    "max_into_ms": 75,
    "next_open": {
      "first_slot": 456542920,
      "leader": "AmVr4cN6kQpLdG7Ltbgm4PjqYKbx2XvBfVd8aJcEoW",
      "rtt_ms": 33.1,
      "eta_ms": 1179.3
    },
    "healthy": true,
    "now_ms": 1791916627310,
    "data_age_ms": 12
  }
}

getNeonLeaders

Returns leader windows. A leader window is the run of consecutive slots one leader produces, usually 4 slots. Past windows come from the recorded history, which goes back 24 hours. Current and upcoming windows come from the leader schedule, as far ahead as the region scouts (currently about 4,000 slots).

Params are optional: an object {from_slot, to_slot, limit} or the positional form [from_slot, to_slot, limit]. A positional item may be null to keep its default, e.g. [null, null, 3].

ParamDefaultMeaning
from_slotThe current leader window's first slotThe first window to return. A from_slot older than the history is raised to the oldest window on hand.
to_slotThe furthest window measured aheadThe last window to return. A to_slot past the horizon is lowered to the horizon.
limit1,000The most rows per call, 1 to 5,000.

A window that starts before from_slot but reaches into the range is included. from_slot above to_slot is error -32602.

FieldMeaning
siteThe region that answered.
now_msThe current time, in unix ms.
current_slotThe current slot.
oldest_slotThe oldest window on hand: about 24 hours behind current_slot.
horizon_slotThe furthest window measured ahead.
slot_msThe measured average milliseconds per slot.
max_rtt_msThe gate's distance cutoff.
rowsOne row per leader window, oldest first. See the rows fields below.
next_from_slotThe from_slot that returns the next page, or null when every row was returned.

rows fields:

FieldMeaning
first_slot, last_slotThe window's slots, inclusive.
leaderThe window's leader, base58.
statepast, current or upcoming.
start_msPast and current: the time the window began, in unix ms. Upcoming: the estimate. null when the window was filled from the schedule.
rtt_msPast: the latency used when that window began. Upcoming: the latest measured latency. null when not measured.
rtt_srcHow rtt_ms was measured: quic or icmp. null with rtt_ms.
gateThe gate's word for that leader: open, rtt_far, rtt_unknown, deny, none.
observedfalse when the window was filled from the schedule while not observed live.

Error -32602 is invalid params. Error -32603 is leader data not available yet or the region busy. A retry answers.

curl "https://neon-rpc-frankfurt.constant-k.com/?api-key=YOUR_API_KEY" \
  -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getNeonLeaders","params":{"from_slot":456542800,"limit":500}}'
getNeonLeaders reply, trimmed
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "site": "frankfurt",
    "now_ms": 1791916627310,
    "current_slot": 456542917,
    "oldest_slot": 456326917,
    "horizon_slot": 456546917,
    "slot_ms": 400,
    "max_rtt_ms": 50,
    "rows": [
      {
        "first_slot": 456542800,
        "last_slot": 456542803,
        "leader": "7Ltbgm4PjqYKbx2XvBfVd8aJcEoW6uS5rNzT9kQpLdG",
        "state": "past",
        "start_ms": 1791916580510,
        "rtt_ms": 61.4,
        "rtt_src": "icmp",
        "gate": "rtt_far",
        "observed": true
      },
      {
        "first_slot": 456542916,
        "last_slot": 456542919,
        "leader": "GbkvTn7nQK9rJYqTzXwQhZ8vLpRdCm5aKqTgHsYbNcP",
        "state": "current",
        "start_ms": 1791916627289.3,
        "rtt_ms": 15.8,
        "rtt_src": "quic",
        "gate": "open",
        "observed": true
      },
      {
        "first_slot": 456542920,
        "last_slot": 456542923,
        "leader": "AmVr4cN6kQpLdG7Ltbgm4PjqYKbx2XvBfVd8aJcEoW",
        "state": "upcoming",
        "start_ms": 1791916628489.3,
        "rtt_ms": 33.1,
        "rtt_src": "icmp",
        "gate": "open",
        "observed": false
      }
    ],
    "next_from_slot": null
  }
}

Polling

while true; do
  # .result.open is the gate word
  if curl -s "https://neon-rpc-frankfurt.constant-k.com/?api-key=YOUR_API_KEY" \
    -X POST -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":1,"method":"getNeonGate"}' | jq -e ".result.open" > /dev/null; then
    ./bot
  fi
  sleep 1
done

On this page