Overledger Gateway

Audience: Backend integrators building client services against Overledger. Reading time: ~12 minutes. Prerequisites: An API key (chapter 3). 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

Every request runs through stages 1–4 before the backend even sees it. Each stage has its own failure code.

Authentication. Every call carries Authorization: Bearer <apiKey>. RPC endpoints also accept the API key in the path. There is no separate token-exchange step.

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.

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) 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 the calling API key, 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 API key: another tenant calling the same endpoints sees their own data, never yours.

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.

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) 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.

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). The connection mechanics are in chapter 8.4.

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-API-key data isolation on every call; the Flow App itself drives the step state machine. The full chapter is at Flow Applications, and the agent (MCP) channel for the same resources is at section 6.7.

Common patterns across resources

A few conventions are worth knowing as you navigate the OpenAPI:

• Per-API-key isolation by default. Reads under /users/me/* and writes under /flow/sessions/* are scoped to the calling key. Cross-tenant 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 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 summarises which enum applies where.

4.4 Statuses

Status vocabularies are per-resource, not universal across the Gateway. The enums you'll actually receive:

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-API-key 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.