> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobula.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve All Perp Markets

> Fetch the full catalog of tradable perpetual markets indexed by Mobula (Gains Network + Lighter) with a single GET request to /api/2/perp/pairs.

Mobula indexes perp markets from **Gains Network** and **Lighter**. To enumerate them, call the **Perp Pairs** endpoint. It returns every **tradable** market in one request — no pagination, no per-DEX normalization needed.

<Tip>
  Only **tradable** markets are returned. Disabled, closed, or delisted markets are filtered out server-side, so anything absent from the response is not tradable. There is no separate "disabled" flag to check.
</Tip>

***

## Endpoint shape

|                 |                                                        |
| --------------- | ------------------------------------------------------ |
| **URL**         | `GET https://api.mobula.io/api/2/perp/pairs`           |
| **Auth header** | `Authorization: <YOUR_API_KEY>` (raw key, no `Bearer`) |
| **Query**       | `chain` (optional) — filter to a single chain/venue    |
| **Response**    | `{ "data": [ ...pairs ] }`                             |

### Query parameter

| Parameter | Type | Required | Description                                                                                 |
| --------- | ---- | -------- | ------------------------------------------------------------------------------------------- |
| `chain`   | enum | No       | Restrict the result to one chain/venue. Omit it to get **every** chain and DEX in one list. |

**Accepted `chain` values**

| Value              | Meaning                                  | DEX     |
| ------------------ | ---------------------------------------- | ------- |
| `arbitrum`         | Gains markets on Arbitrum                | gains   |
| `base`             | Gains markets on Base                    | gains   |
| `arbitrum-sepolia` | Gains markets on Arbitrum Sepolia (test) | gains   |
| `lighter`          | Lighter markets                          | lighter |

***

## Quick start — curl

```bash theme={null}
# All markets (every chain + DEX)
curl "https://api.mobula.io/api/2/perp/pairs" \
  -H "Authorization: YOUR_API_KEY"

# Single chain — Arbitrum (Gains)
curl "https://api.mobula.io/api/2/perp/pairs?chain=arbitrum" \
  -H "Authorization: YOUR_API_KEY"

# Lighter only
curl "https://api.mobula.io/api/2/perp/pairs?chain=lighter" \
  -H "Authorization: YOUR_API_KEY"
```

***

## Response

```json theme={null}
{
  "data": [
    {
      "name": "BTC/USD",
      "baseToken": "BTC",
      "quoteToken": "USD",
      "minLeverage": 1.1,
      "maxLeverage": 200,
      "dex": "gains",
      "chain": "arbitrum",
      "assetClass": "crypto",
      "dexMarketId": 0,
      "socialUrl": "",
      "pairFullName": "BTC",
      "percentageChange24h": -2.98,
      "price": 71571.74,
      "logo": "https://metadata.mobula.io/assets/logos/100001656.webp"
    }
  ]
}
```

`data` is the full list of tradable markets — there is no pagination.

### Market model

| Field                 | Type           | Description                                                                                                                          |
| --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `name`                | string         | Human-readable `base/quote` label, e.g. `"BTC/USD"`.                                                                                 |
| `baseToken`           | string         | Base asset symbol, e.g. `"BTC"`.                                                                                                     |
| `quoteToken`          | string         | Quote asset symbol, e.g. `"USD"`.                                                                                                    |
| `minLeverage`         | number         | Minimum allowed leverage.                                                                                                            |
| `maxLeverage`         | number         | Maximum allowed leverage. Always `> 0` (disabled markets are excluded).                                                              |
| `dex`                 | enum           | `"gains"` or `"lighter"`.                                                                                                            |
| `chain`               | enum           | `"arbitrum"`, `"base"`, `"arbitrum-sepolia"`, or `"lighter"`.                                                                        |
| `assetClass`          | enum           | `"crypto"`, `"forex"`, `"stocks"`, `"indices"`, `"commodities"`, `"degen"`, or `"new"`.                                              |
| `dexMarketId`         | integer (≥ 0)  | The DEX's internal market id — Gains `pairIndex` / Lighter `market_id`. Use it when referencing the market in quote/execution calls. |
| `socialUrl`           | string         | Reserved for a social/info URL. Currently empty.                                                                                     |
| `pairFullName`        | string         | Full name of the market as reported by the DEX.                                                                                      |
| `percentageChange24h` | number         | 24h price change, in percent.                                                                                                        |
| `price`               | number         | Latest/mark price in USD (`0` if no price is currently available).                                                                   |
| `logo`                | string \| null | Base-asset logo URL, or `null` when unknown.                                                                                         |

***

## TypeScript

```typescript theme={null}
import axios from 'axios';

const PAIRS_URL = 'https://api.mobula.io/api/2/perp/pairs';
const API_KEY = process.env.MOBULA_API_KEY!;

type PerpPair = {
  name: string;
  baseToken: string;
  quoteToken: string;
  minLeverage: number;
  maxLeverage: number;
  dex: 'gains' | 'lighter';
  chain: 'arbitrum' | 'base' | 'arbitrum-sepolia' | 'lighter';
  assetClass: 'crypto' | 'forex' | 'stocks' | 'indices' | 'commodities' | 'degen' | 'new';
  dexMarketId: number;
  socialUrl: string;
  pairFullName: string;
  percentageChange24h: number;
  price: number;
  logo: string | null;
};

async function fetchPerpPairs(chain?: PerpPair['chain']): Promise<PerpPair[]> {
  const res = await axios.get<{ data: PerpPair[] }>(PAIRS_URL, {
    headers: { Authorization: API_KEY },
    params: chain ? { chain } : undefined,
  });
  return res.data.data;
}

// Every tradable market across all chains and DEXes
const all = await fetchPerpPairs();

// Gains markets on Arbitrum only
const arbitrum = await fetchPerpPairs('arbitrum');

console.log(`Total markets: ${all.length}`);
```

***

## Common pitfalls

* **`Bearer` prefix in the Authorization header.** Don't add it — pass the raw API key.
* **Expecting disabled markets.** They are filtered out. If a market isn't in the response, it isn't tradable.
* **Using `dexMarketId` across DEXes.** It is only unique within a `(dex, chain)`. Pair it with `dex`/`chain` when keying markets.

***

## Related

<CardGroup cols={2}>
  <Card title="Perp Quote" icon="calculator" href="/rest-api-reference/endpoint/perp-quote">Quote a perp position once you've picked a market.</Card>
  <Card title="Execute Perp Action" icon="bolt" href="/rest-api-reference/endpoint/perp-execute">Submit signed payloads via `/2/perp/execute-v2`.</Card>
  <Card title="DEX Status" icon="heart-pulse" href="/data/perps/perp-dex-status">Lighter / Gains uptime, probe results and maintenance windows.</Card>
  <Card title="Perps Data Model" icon="database" href="/indexing-stream/stream/data-model/perps-data-model">Indexed event shapes for perps.</Card>
</CardGroup>

***

## Need help?

<CardGroup cols={4}>
  <Card title="Telegram" icon="telegram" href="https://t.me/mobuladevelopers">Fast support</Card>
  <Card title="Discord" icon="discord" href="https://discord.gg/JVT7xKm3AD">Community</Card>
  <Card title="Slack" icon="slack" href="https://join.slack.com/t/mobulaapi/shared_invite/zt-29zrrpjnl-I0tyD73sy7zKy8q~KLL3Ug">Enterprise</Card>
  <Card title="Email" icon="envelope" href="mailto:contact@mobulalabs.org">Contact us</Card>
</CardGroup>