# Gate Status API

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

Source: https://docs.constant-k.com/neon-zero/gate-status/

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

| Region                                | URL                                                               |
| :------------------------------------ | :---------------------------------------------------------------- |
| <Flag region="newyork" /> New York    | `https://neon-rpc-newyork.constant-k.com/?api-key=YOUR_API_KEY`   |
| <Flag region="frankfurt" /> Frankfurt | `https://neon-rpc-frankfurt.constant-k.com/?api-key=YOUR_API_KEY` |
| <Flag region="amsterdam" /> Amsterdam | `https://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.

| Field          | Meaning                                                                                                            |
| :------------- | :----------------------------------------------------------------------------------------------------------------- |
| `site`         | The region that answered: `newyork`, `frankfurt` or `amsterdam`.                                                   |
| `open`         | `true` when a `sendTransaction` sent now is forwarded.                                                             |
| `verdict`      | Why the gate is open or closed. See the verdict table below.                                                       |
| `slot`         | The current slot. Omitted when the clock has no reading.                                                           |
| `leader`       | The current slot's leader, base58. `null` for a moment right after a slot change.                                  |
| `leader_check` | The leader test for the current slot: `ok`, `rtt_far`, `rtt_unknown`, `deny`, `none`, or `-` when no data arrived. |
| `rtt_ms`       | Measured round-trip time to the current leader, in ms. `null` when not measured.                                   |
| `ms_into_slot` | Milliseconds into the current leader's slot. Omitted when the clock has no reading.                                |
| `max_rtt_ms`   | The gate's distance cutoff: a leader farther than this never opens the gate.                                       |
| `max_into_ms`  | The gate's cutoff for milliseconds into the slot.                                                                  |
| `next_open`    | The next leader window this region would open for, or `null` when no upcoming window would open the gate.          |
| `healthy`      | Whether the region's gate reports itself healthy.                                                                  |
| `now_ms`       | The current time, in unix ms.                                                                                      |
| `data_age_ms`  | How 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:

| Field        | Meaning                                                                                         |
| :----------- | :---------------------------------------------------------------------------------------------- |
| `first_slot` | The window's first slot.                                                                        |
| `leader`     | The window's leader, base58.                                                                    |
| `rtt_ms`     | Measured round-trip time to that leader, in ms.                                                 |
| `eta_ms`     | Milliseconds from now until that window begins, never negative. `0` when the window begins now. |

Verdicts:

| Verdict       | Gate          | Meaning                                                         |
| :------------ | :------------ | :-------------------------------------------------------------- |
| `open`        | Open          | The leader is close to this region and its slot has just begun. |
| `late`        | Closed        | Too far into the leader's slot.                                 |
| `rtt_far`     | Closed        | The leader is too far from this region.                         |
| `rtt_unknown` | Closed        | The latency to the leader is not measured yet.                  |
| `deny`        | Closed        | The leader is excluded from the gate.                           |
| `none`        | Cannot decide | No leader is known for the current slot.                        |
| `unhealthy`   | Cannot decide | The region's gate reports itself unhealthy.                     |
| `stale`       | Cannot decide | The gate's data is more than a second old.                      |
| `no_clock`    | Cannot decide | The clock has no reading for the current slot.                  |
| `nodaemon`    | Cannot decide | No gate data arrived.                                           |

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

```bash
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"}'
```

```json title="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]`.

| Param       | Default                                | Meaning                                                                                                  |
| :---------- | :------------------------------------- | :------------------------------------------------------------------------------------------------------- |
| `from_slot` | The current leader window's first slot | The first window to return. A `from_slot` older than the history is raised to the oldest window on hand. |
| `to_slot`   | The furthest window measured ahead     | The last window to return. A `to_slot` past the horizon is lowered to the horizon.                       |
| `limit`     | 1,000                                  | The 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`.

| Field            | Meaning                                                                            |
| :--------------- | :--------------------------------------------------------------------------------- |
| `site`           | The region that answered.                                                          |
| `now_ms`         | The current time, in unix ms.                                                      |
| `current_slot`   | The current slot.                                                                  |
| `oldest_slot`    | The oldest window on hand: about 24 hours behind `current_slot`.                   |
| `horizon_slot`   | The furthest window measured ahead.                                                |
| `slot_ms`        | The measured average milliseconds per slot.                                        |
| `max_rtt_ms`     | The gate's distance cutoff.                                                        |
| `rows`           | One row per leader window, oldest first. See the rows fields below.                |
| `next_from_slot` | The `from_slot` that returns the next page, or `null` when every row was returned. |

`rows` fields:

| Field                     | Meaning                                                                                                                               |
| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------ |
| `first_slot`, `last_slot` | The window's slots, inclusive.                                                                                                        |
| `leader`                  | The window's leader, base58.                                                                                                          |
| `state`                   | `past`, `current` or `upcoming`.                                                                                                      |
| `start_ms`                | Past and current: the time the window began, in unix ms. Upcoming: the estimate. `null` when the window was filled from the schedule. |
| `rtt_ms`                  | Past: the latency used when that window began. Upcoming: the latest measured latency. `null` when not measured.                       |
| `rtt_src`                 | How `rtt_ms` was measured: `quic` or `icmp`. `null` with `rtt_ms`.                                                                    |
| `gate`                    | The gate's word for that leader: `open`, `rtt_far`, `rtt_unknown`, `deny`, `none`.                                                    |
| `observed`                | `false` 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.

```bash
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}}'
```

```json title="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

```bash
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
```

## Related

- [Neon Zero](https://docs.constant-k.com/neon-zero/)

- [Plans & Limits](https://docs.constant-k.com/get-started/plans-and-limits/)
