Get Perp DEX Status

Query Details

Returns one entry per probed DEX with a rolled-up status, the individual probe results powering that rollup, and any active or upcoming maintenance windows.

Probes both HTTP and WebSocket upstreams. WS probes connect, wait for the first message, and disconnect.
Results are cached server-side per check to avoid hammering upstreams. Concurrent cold-cache calls are deduped — N parallel requests fire a single upstream probe.
Probes never throw — failures surface as ok: false on the corresponding check.
Auxiliary checks are informational and never affect the rollup; only critical checks do.

Endpoint

GET /api/2/perp/dex-status

Query Parameters

Parameter	Type	Required	Description
dex	`'lighter' \| 'gains'`	No	Filter to a single DEX. If omitted, both DEXes are probed in parallel and returned together.

Usage Examples

Both DEXes:

curl 'https://api.mobula.io/api/2/perp/dex-status'

Lighter only:

curl 'https://api.mobula.io/api/2/perp/dex-status?dex=lighter'

Gains only:

curl 'https://api.mobula.io/api/2/perp/dex-status?dex=gains'

Response

Top-level shape:

{
  data: PerpDexHealth[];
  meta?: {
    generatedAt: number; // unix ms — server-side response build time
    totalMs: number;     // controller-measured request duration in ms
  };
}

`PerpDexHealth`

One entry per probed DEX.

Field	Type	Description
dex	`'lighter' \| 'gains'`	DEX identifier.
status	`'operational' \| 'degraded' \| 'maintenance' \| 'down'`	Roll-up status derived from `checks` and any active maintenance window. See Status rollup.
checkedAt	`number`	Unix ms — when the snapshot for this DEX was assembled.
checks	`PerpDexCheckResult[]`	Individual probe results powering the rollup.
maintenance	`{ active: boolean; windows: PerpDexMaintenanceWindow[] }`	Active flag and parsed maintenance windows. Currently populated for `lighter` only (Gains: empty).
meta	`Record<string, unknown>` (optional)	DEX-specific extras. For Gains: `{ chains: [{ chainId, isTestnet, pairsCount }, ...] }`.

`PerpDexCheckResult`

One per upstream probe.

Field	Type	Description
name	`string`	Check identifier. See Checks reference.
description	`string`	Human-readable summary of what this check probes and why it matters.
weight	`'critical' \| 'auxiliary'`	Only `critical` checks contribute to the rollup. `auxiliary` is informational.
transport	`'http' \| 'ws'`	Probe transport.
ok	`boolean`	True if the probe succeeded (and, where applicable, body validation passed — e.g. `pairs.length > 0` for `trading-variables`).
slow	`boolean`	True only when `ok === true` and latency exceeds the transport’s slow threshold (HTTP: 2000 ms, WS: 3000 ms).
latencyMs	`number \| null`	Round-trip latency for the probe.
cached	`boolean`	True if the value was served from the in-memory cache rather than freshly fetched.
fetchedAt	`number`	Unix ms — timestamp of the underlying probe (cache-fill time when `cached === true`).
error	`string` (optional)	Present when `ok === false`; short error label.
meta	`Record<string, unknown>` (optional)	Check-specific extras (e.g. `pairsCount`, `networkId`, `firstMessageBytes`, `chainId`, `isTestnet`).

`PerpDexMaintenanceWindow`

Field	Type	Description
title	`string`	Source announcement title.
content	`string`	Source announcement body.
createdAt	`number`	Source announcement `created_at`, unix seconds.
expiredAt	`number \| null`	Source announcement `expired_at`, unix seconds (null when none).
isMaintenance	`boolean`	True when title/content match maintenance keywords (`upgrade`, `maintenance`, `downtime`).
scheduledAt	`number \| null`	Parsed window start in unix seconds (null when not extractable).
scheduledEndAt	`number \| null`	Parsed window end in unix seconds (null when not extractable).
active	`boolean`	True when `now` falls inside the parsed window (or inside the `expiredAt` fallback).

Status Rollup

Ranking best → worst:

maintenance — any maintenance window with active === true.
operational — every critical check is ok && !slow.
down — zero critical checks ok.
degraded — anything else (some critical OK and some not, or one critical is slow).

Auxiliary checks never affect the rollup.

Checks Reference

Lighter

name	weight	transport	Probes
http-root	critical	http	`https://mainnet.zklighter.elliot.ai/` — sequencer reachability; returns network id + timestamp.
announcements	auxiliary	http	Public announcements API. Source of `maintenance.windows`.
ws-stream	critical	ws	`wss://mainnet.zklighter.elliot.ai/stream` — live order/transaction confirmations.

Gains

One trading-variables and one ws-trading per supported chain, plus a single shared ws-pricing.

name	weight	transport	Probes
trading-variables	critical (Arbitrum, Base) / auxiliary (Polygon, Arbitrum Sepolia)	http	`<gains-backend>/trading-variables/all` — pair list and per-pair trading parameters.
ws-trading	critical (Arbitrum, Base) / auxiliary (Polygon, Arbitrum Sepolia)	ws	Gains backend event WS — order, position and chain events.
ws-pricing	critical	ws	`wss://backend-pricing.eu.gains.trade` — shared price feed for every Gains chain.

Per-chain weights:

chainId	network	weight	isTestnet
evm:42161	Arbitrum	critical	false
evm:8453	Base	critical	false
evm:137	Polygon	auxiliary	false
evm:421614	Arbitrum Sepolia	auxiliary	true

Caching & Timeouts

In-memory per-check TTLs:

Check	TTL
lighter `http-root`	10000 ms
lighter `announcements`	30000 ms
lighter `ws-stream`	15000 ms
gains `trading-variables/*`	15000 ms
gains `ws-trading/*`	15000 ms
gains `ws-pricing`	15000 ms

Probe budgets:

HTTP — timeout: 5000 ms · slow threshold: 2000 ms.
WS — timeout: 4000 ms · slow threshold: 3000 ms.

Example Response

Truncated for readability.

{
  "data": [
    {
      "dex": "lighter",
      "status": "operational",
      "checkedAt": 1714200000000,
      "checks": [
        {
          "name": "http-root",
          "description": "Lighter HTTP root endpoint. Returns the current network id and chain timestamp; failure means the L2 sequencer is unreachable.",
          "weight": "critical",
          "transport": "http",
          "ok": true,
          "slow": false,
          "latencyMs": 142,
          "cached": false,
          "fetchedAt": 1714199999850,
          "meta": { "status": 200, "networkId": 1, "serverTimestamp": 1714199999 }
        },
        {
          "name": "announcements",
          "description": "Lighter public announcements API. Source of scheduled maintenance and network-upgrade notices surfaced under `maintenance.windows`.",
          "weight": "auxiliary",
          "transport": "http",
          "ok": true,
          "slow": false,
          "latencyMs": 198,
          "cached": true,
          "fetchedAt": 1714199985000,
          "meta": { "totalAnnouncements": 42, "maintenanceWindowsTotal": 1, "maintenanceWindowsRelevant": 1 }
        },
        {
          "name": "ws-stream",
          "description": "Lighter WebSocket stream (`/stream`). Used for live order-status and transaction confirmations; failure breaks order tracking.",
          "weight": "critical",
          "transport": "ws",
          "ok": true,
          "slow": false,
          "latencyMs": 612,
          "cached": false,
          "fetchedAt": 1714199999800,
          "meta": { "firstMessageBytes": 184 }
        }
      ],
      "maintenance": {
        "active": false,
        "windows": [
          {
            "title": "Network Upgrade May 1",
            "content": "...",
            "createdAt": 1713000000,
            "expiredAt": null,
            "isMaintenance": true,
            "scheduledAt": 1714572000,
            "scheduledEndAt": 1714575600,
            "active": false
          }
        ]
      }
    },
    {
      "dex": "gains",
      "status": "operational",
      "checkedAt": 1714200000000,
      "checks": [
        {
          "name": "trading-variables",
          "description": "Gains backend `trading-variables/all` HTTP endpoint. Returns the pair list and per-pair trading parameters used to build orders.",
          "weight": "critical",
          "transport": "http",
          "ok": true,
          "slow": false,
          "latencyMs": 311,
          "cached": false,
          "fetchedAt": 1714199999700,
          "meta": { "chainId": "evm:42161", "isTestnet": false, "pairsCount": 168 }
        },
        {
          "name": "ws-trading",
          "description": "Gains backend WebSocket event stream. Pushes order, position and chain events; failure breaks live order tracking.",
          "weight": "critical",
          "transport": "ws",
          "ok": true,
          "slow": false,
          "latencyMs": 510,
          "cached": false,
          "fetchedAt": 1714199999700,
          "meta": { "chainId": "evm:42161", "isTestnet": false, "firstMessageBytes": 12 }
        },
        {
          "name": "ws-pricing",
          "description": "Gains pricing WebSocket (`backend-pricing.eu.gains.trade`). Provides the price feed used across every Gains chain.",
          "weight": "critical",
          "transport": "ws",
          "ok": true,
          "slow": false,
          "latencyMs": 240,
          "cached": false,
          "fetchedAt": 1714199999700,
          "meta": { "firstMessageBytes": 96 }
        }
      ],
      "maintenance": { "active": false, "windows": [] },
      "meta": {
        "chains": [
          { "chainId": "evm:42161", "isTestnet": false, "pairsCount": 168 },
          { "chainId": "evm:8453",  "isTestnet": false, "pairsCount": 168 },
          { "chainId": "evm:137",   "isTestnet": false, "pairsCount": 168 },
          { "chainId": "evm:421614","isTestnet": true,  "pairsCount": 168 }
        ]
      }
    }
  ],
  "meta": { "generatedAt": 1714200000000, "totalMs": 740 }
}

Errors

Status	When	`message`
400	Zod validation failed on `dex` (only `lighter` or `gains` accepted).	`zod validation failed`
500	Unexpected internal error.	`internal server error`

Probes themselves never throw — upstream failures are reflected as ok: false on the per-check result, not as HTTP errors.

Perpetuals APIs Overview

Supported exchanges and capability map.

Perp Fees

Fee structure for each integrated DEX.

Get Perp Quote

Preview fees, fills and venue routing before executing.

Perp Execution Flow

Build → execute flow against Lighter and Gains.

Introduction

Data

Execution

Cookbook

Streams

Reference

Query Details

Endpoint

Query Parameters

Usage Examples

Response

`PerpDexHealth`

`PerpDexCheckResult`

`PerpDexMaintenanceWindow`

Status Rollup

Checks Reference

Lighter

Gains

Caching & Timeouts

Example Response

Errors

Perpetuals APIs Overview

Perp Fees

Get Perp Quote

Perp Execution Flow

​Query Details

​Endpoint

​Query Parameters

​Usage Examples

​Response

​PerpDexHealth

​PerpDexCheckResult

​PerpDexMaintenanceWindow

​Status Rollup

​Checks Reference

​Lighter

​Gains

​Caching & Timeouts

​Example Response

​Errors

​Related

Perpetuals APIs Overview

Perp Fees

Get Perp Quote

Perp Execution Flow

Query Details

Endpoint

Query Parameters

Usage Examples

Response

`PerpDexHealth`

`PerpDexCheckResult`

`PerpDexMaintenanceWindow`

Status Rollup

Checks Reference

Lighter

Gains

Caching & Timeouts

Example Response

Errors

Related