--- updatedAt: 2026-06-17T11:45:21.000Z agentTools: projectIndex: https://docs.overledger.dev/llms.txt --- # Overledger Gateway > **Audience:** Backend integrators building client services against Overledger. **Reading time:** \~12 minutes. **Prerequisites:** An API key ([Chapter 3: Authentication](https://docs.overledger.dev/docs/authentication)). **You'll learn:** Base URLs, request/response shapes, error envelopes, idempotency, rate limits, the full resource surface of the Gateway, and how to read the API reference. The Gateway is the single endpoint every Overledger client calls. It authenticates, enforces firewall policy, routes RPC traffic to Connectors or the Fusion Rollup, hosts Orchestration (Flow Applications), and exposes a set of REST resources for everything else. This chapter is the operational guide to using the Gateway. ## 4.1 Base URL & environments The new Base URLs will be released here when finalised.\_ Endpoints that embed your API key in the URL path (`/rpc/{apiKey}`, `/dlts/{dlt}/networks/{network}/rpc/{apiKey}`) treat the URL itself as authenticated material. Don't log or share these URLs. ## 4.2 How to call the Gateway Gateway request lifecycle **Authentication.** RPC calls carry your API key in the URL path (`/rpc/{apiKey}`) or the `X-API-Key` header. REST calls carry a JWT in the `Authorization` header or an API key in the `X-API-Key` header. See [chapter 3.3](https://docs.overledger.dev/docs/authentication#33-authenticate-your-requests) for the full breakdown. **Content type.** JSON request and response bodies. Set `Content-Type: application/json` on writes. **Error envelopes.** Two shapes, depending on the route: * **`StandardError`** (`Content-Type: application/json`), used by every non-Flow route. ```json { "timestamp": 1709737845000, "status": 400, "error": "Bad request", "message": "Validation failed", "path": "/users/me/deposits" } ``` * **`ProblemDetails` (RFC 7807, `Content-Type: application/problem+json`)**, used by every `/flow/*` route. ```json { "type": "urn:fusion:error:bad-request", "title": "Bad Request", "status": 400, "detail": "appId is required", "retryable": false, "instance": "/flow/sessions/abc123" } ``` The `instance` field on `ProblemDetails` carries a request identifier, quote it in any support ticket. The full error reference is in [chapter 11](https://docs.overledger.dev/docs/troubleshooting). **Idempotency.** The `POST /flow/sessions/{sessionId}/steps/{stepId}` endpoint **requires** an `Idempotency-Key` header (any string, 1–256 chars). Submissions are cached per session, repeating the same key on the same session returns the cached response without re-executing. **Rate limits.** Are surfaced through HTTP `429` (per [chapter 11](https://docs.overledger.dev/docs/troubleshooting)) with `Retry-After`. Tier-specific quotas vary by account; contact your account team if you need a higher tier. ## 4.3 The Gateway's resource model The Gateway exposes seven resource categories. The conceptual purpose of each is described here; the \*\*authoritative list of endpoints, request schemas, response shapes, and examples is the API reference. Treat this section as the map; treat the OpenAPI as the territory. ### Identity and history (`/users/me/*`) Everything scoped to your authenticated identity, including your `userId`, balances, the transactions you've sent on the rollup, your L1→L2 deposit records, cross-chain swap history, registered nodes and providers, stakes, and deployed contracts. By design these resources are *isolated per user*: another user calling the same endpoints sees their own data, never yours. All your API keys and JWT sessions resolve to the same identity, so data is consistent regardless of which credential you use. ### Deployed contracts and their permissions (`/deployed-contracts/*`) The registry of contracts you've deployed on the Fusion Rollup, plus the **permission API** that grants or revokes access to `permissioned` contracts. Each contract carries a `visibility` attribute (`public` / `permissioned` / `private`) that the on-chain firewall enforces against the calling address. This is the API surface of the on-chain **Fusion Firewall sub-component** of the Overledger Firewall. ### Networks and nodes (`/networks`, `/nodes`) The list of DLT networks the Gateway can reach today and the API to attach your own node to that pool, either on a network Overledger already supports or on a new network you're creating. The detail of the attach-a-node flow, including approved-provider domains for public networks and the "bring your own" path for private networks, lives in [chapter 5.2](https://docs.overledger.dev/docs/connectors#52-self-serve-networks). ### Providers and reset policies (`/users/me/providers/*`) Configuration for the external RPC providers (Alchemy, Infura, QuickNode, …) registered against your account. The reset-policy resource (`manual` / `daily` at a UTC hour / `monthly` on a day of month) controls when a provider that has tripped its rate limit becomes routable again. The Connector load-balancer ([chapter 5](https://docs.overledger.dev/docs/connectors)) reads these policies as it picks a backend. ### Stakes (`/stakes`, `/users/me/stakes/*`) The API surface for locking QNT to earn rewards and unlock higher capacity tiers. The end-to-end walkthrough is in [chapter 12](https://docs.overledger.dev/docs/staking). ### Fusion Rollup JSON-RPC (`/rpc/{apiKey}`) The JSON-RPC entry point into the Fusion Rollup (OP-Geth). Use any EVM tool (ethers.js, viem, web3.py, Foundry's `cast`) pointed at this URL. For multi-DLT JSON-RPC across non-Fusion chains, use the Connectors endpoint instead ([chapter 5.5](https://docs.overledger.dev/docs/connectors#55-multi-dlt-rpc-endpoint)). The connection mechanics are in [chapter 8.4](https://docs.overledger.dev/docs/fusion-rollup#84-connecting-to-fusion-rollup). ### Flow Applications (`/flow/*`) The **orchestration plane**: starting sessions on a Flow App, rendering and submitting steps, running read-only queries the app declares, and subscribing to webhook events the app emits. The Gateway handles authentication, idempotency, content filtering, and per-user data isolation on every call; the Flow App itself drives the step state machine. The full chapter is at [chapter 6](https://docs.overledger.dev/docs/flow-apps), and the agent (MCP) channel for the same resources is at [chapter 6.7](https://docs.overledger.dev/docs/flow-apps#67-agent-integration-mcp). ### Common patterns across resources A few conventions are worth knowing as you navigate the OpenAPI: * **Per-user isolation by default.** Reads under `/users/me/*` and writes under `/flow/sessions/*` are scoped to the authenticated user. Cross-user access is only possible where a contract or app explicitly opts in via the permission API or its own visibility model. * **List endpoints are paginated.** Responses wrap data in `{ data: [...], pagination }`. Use the `pagination.next` cursor rather than incrementing an offset. * **Write idempotency** is enforced on `POST /flow/sessions/{sessionId}/steps/{stepId}` via the required `Idempotency-Key` header (see [section 4.2](https://docs.overledger.dev/docs/overledger-gateway#42-how-to-call-the-gateway) above). Other writes are not idempotent by default. * **`visibility` and `status` enums are per-resource.** Don't assume the same set of strings means the same thing across contracts, networks, sessions, or webhook deliveries; the reference table in [section 4.4](https://docs.overledger.dev/docs/overledger-gateway#44-statuses) summarises which enum applies where. ## 4.4 Statuses Status vocabularies are **per-resource**, not universal across the Gateway. The enums you'll actually receive: | Resource | Status enum | Where defined | | -------------------- | -------------------------------- | ------------------------- | | **Flow App session** | `active`, `complete`, `expired` | `SessionStatus` | | **Network** | `active`, `paused`, `deprecated` | `Network.status` | | **Webhook delivery** | `pending`, `delivered`, `failed` | `WebhookDelivery.status` | | **Deposit / swap** | Free-form per underlying chain | `Deposit.status` (string) | For deposits, expect ledger-driven values that describe the state of the underlying L1 transaction and bridge step. Always treat unknown values as opaque rather than mapping them to assumed statuses. ## 4.5 Rate limits & quotas The Gateway enforces per-user throughput and concurrency. Limits and concurrency depend on your tier; contact your account team to find out your effective quota or to request a higher tier. Exceeding a limit returns HTTP `429` with a `Retry-After` header. For Flow routes the response body is a `ProblemDetails` with `type: urn:fusion:error:too-many-requests`; for non-Flow routes it is a `StandardError`.