---
title: "Radix Gateway API"
url: "https://radix-wiki.miow.me/contents/tech/core-protocols/radix-gateway-api"
updated: 2026-10-03
description: "The Radix Gateway API is the primary developer interface for building dApps on Radix. It indexes the ledger and provides REST endpoints for querying account…"
---

# Radix Gateway API

|  |  |
| --- | --- |
| **Type** | Developer-Facing API |
| **Database** | ~2TB, growing ~60GB/month |
| **Transition** | Community RFP (Feb 2026) |
| **Target SLA** | 99.9% uptime, <1s query latency |
| **Staleness guard** | HTTP 500 `NotSyncedUpError` beyond 720s of ledger lag (mainnet) |

# Radix Gateway API

## Overview

The **Radix [Gateway API](https://docs.radixdlt.com/docs/network-gateway)** is the primary developer interface for building dApps on Radix. It indexes the ledger and provides REST endpoints for querying account states, token balances, transaction history, and [resource](/contents/tech/core-concepts/resources) metadata.

### Decentralization

Currently operated by the [Radix Foundation](/ecosystem/radix-foundation), the [Gateway API](https://docs.radixdlt.com/docs/gateway-sdk) is undergoing community transition via RFP (opened February 2026). The database is approximately 2TB with ~60GB monthly growth. Successful operators must guarantee 99.9% uptime and sub-second query latency for the [Radix Wallet](/contents/tech/core-protocols/radix-wallet) and [Dashboard](https://dashboard.radixdlt.com).

## What the Gateway does when it falls behind

The Gateway answers from its own index rather than from a node’s live state, so it can fall behind the network. Rather than serve a stale answer it refuses to answer at all. [`LedgerStateQuerier`](https://github.com/radixdlt/babylon-gateway/blob/main/src/RadixDlt.NetworkGateway.PostgresIntegration/Services/LedgerStateQuerier.cs) compares the timestamp of its own head against the clock and throws [`NotSyncedUpException`](https://github.com/radixdlt/babylon-gateway/blob/main/src/RadixDlt.NetworkGateway.GatewayApi/Exceptions/NotSyncedUpException.cs) when the gap is too wide. The caller gets HTTP 500 with a `NotSyncedUpError` body naming `current_sync_delay_seconds` and `max_allowed_sync_delay_seconds`.

The guard has two halves, separately configurable, both on by default at 30 seconds ([Gateway configuration reference](https://github.com/radixdlt/babylon-gateway/blob/main/docs/configuration.md)). `PreventReadRequestsIfDbLedgerIsBehind` covers the state and stream endpoints. `PreventConstructionRequestsIfDbLedgerIsBehind` covers `/transaction/construction`, and the source gives its reason: a construction request built against a stale index would use historic stake records, which gets an unstake calculation wrong. The Radix Foundation’s public mainnet Gateway runs both thresholds at 720 seconds.

### What that looks like from a dApp

The mainnet [halt of 31 August to 11 September 2026](/contents/history/hyperlane-asset-drain-2026#the-outage) held the guard open long enough to read it. Every endpoint below was called once at 03:10 UTC on 5 September 2026:

| Endpoint | Response |
| --- | --- |
| `/status/gateway-status` | 200, returning the frozen head: state version 557,840,622, epoch 339,896, round 102 |
| `/status/network-configuration` | 200 |
| `/state/entity/details` | 500, `request_type` `Read` |
| `/state/validators/list` | 500, `request_type` `Read` |
| `/stream/transactions` | 500, `request_type` `Read` |
| `/transaction/construction` | 500, `request_type` `Construction` |

All four failures reported `current_sync_delay_seconds` 366,663 against `max_allowed_sync_delay_seconds` 720. A wallet or dApp on this Gateway therefore connects, resolves the network, and then fails on every balance, history and submission call, with nothing wrong with the account or the key: the index will not answer for a ledger whose top it cannot see. The two status endpoints stay up throughout, which makes `/status/gateway-status` the place to check whether the network is moving. It is the wrong place to read where the ledger stopped. The head it reported for the whole halt, state version 557,840,622, is the last state the Gateway’s own index took in; [`/stream/transactions`](https://mainnet.radixdlt.com/stream/transactions) shows the ledger committed five more, ending at state version 557,840,627 (epoch 339,897, round 4) at 21:19:48 UTC on 31 August. [Verifiability](/policy/verifiability) lists this as a failure mode.

### Reading around the guard

The refusal covers questions about the present, and only those. `GetValidLedgerStateForReadRequest` resolves the ledger state the caller asked for before it does anything else, and the lag comparison sits behind an early return: `if (!ledgerStateReport.TopOfLedgerResolved) return ledgerState;`. `TopOfLedgerResolved` is set true on one branch only, the one taken when the request named no ledger state and the Gateway had to read its own head. A request that pins a state version, an epoch, an epoch and round, or a timestamp never reaches the threshold and cannot throw [`NotSyncedUpException`](https://github.com/radixdlt/babylon-gateway/blob/main/src/RadixDlt.NetworkGateway.GatewayApi/Exceptions/NotSyncedUpException.cs).

The halt makes that visible. Each endpoint below was called twice within two seconds at **07:07:56 UTC on 6 September 2026**, at a reported `current_sync_delay_seconds` of 467,332 against 720 — once as an ordinary request, once with `"at_ledger_state": {"state_version": 557,840,622}`, the head the status endpoint was reporting:

| Endpoint | Unpinned | Pinned |
| --- | --- | --- |
| `/state/entity/details` | 500 | **200** |
| `/state/validators/list` | 500 | **200**, 287 validators with stake vaults |
| `/stream/transactions` | 500 | **200** |
| `/transaction/construction` | 500 | 500 |

Construction is the exception and the source says why it is not an inconsistency: `GetValidLedgerStateForConstructionRequest` carries the identical early return, but the `/transaction/construction` request has no `at_ledger_state` field to fill, so the value is ignored, the Gateway resolves its own head, and the `Construction` guard fires as before. Nothing here lets a stopped network be transacted on; it lets a stopped network be read.

So the practical division during a halt is not between working and broken endpoints but between two questions. _What is true now_ has no answer and the Gateway declines to invent one. _What was true at a named state version_ has an answer: the same public Gateway serves balances, resource holdings and transaction history for any state the ledger committed. For this halt the last such state is 557,840,627, and a read pinned there on 12 September returns it, stamped 21:19:48 UTC on 31 August. A dApp fails during a halt because it asks the first question; a caller willing to name a ledger state gets the second.

### After the restart

Mainnet committed rounds again from 11:35 UTC on 11 September 2026, and the Eagle Ray protocol update enacted four minutes later ([enactment, read from the ledger](/contents/tech/releases/protocol-updates#eagle-ray-enactment)). Nobody switched the guard off. It stopped firing once the Gateway’s index was back within the 720-second threshold of the ledger’s tip: at 19:07 UTC on 12 September, unpinned calls to `/state/entity/details` and `/state/validators/list` both answered 200, and `/status/gateway-status` reported epoch 340,275.