# Pairs & Volume

Base URL: `https://service.leverup.xyz`

## List pairs

The authoritative list of tradable markets, including `pairBase` addresses. **Use this instead of
hardcoding addresses** — markets are listed and delisted over time.

```http
GET /v1/pairs
```

| Parameter | Default | Notes |
| :--- | :--- | :--- |
| `block_chain` | `MONAD` | |
| `is_ready_to_display` | `true` | Set `false` to include markets not yet surfaced in the UI |
| `symbol` | — | Filter by symbol, e.g. `BTC` |
| `tags` | — | Filter by tag, repeatable |
| `volume_time_range` | `ONE_DAY` | Window for the `volume` fields: `ONE_DAY`, `SEVEN_DAY`, `THIRTY_DAY`, `ALL` |
| `page` | `0` | |
| `size` | `20` | |

### Response

```json
{
  "content": [
    {
      "base": "0xcf5a6076cfa32686c0df13abada2b40dec133f1d",
      "pairName": "BTC/USD",
      "symbol": "BTC",
      "pairType": "CRYPTO",
      "icon": "https://…",
      "isDegenPair": false,
      "tags": ["majors"],
      "listAt": "2025-11-01T00:00:00Z",
      "nextOpen": null,
      "nextClose": null,
      "schedule": null,
      "priceDisplayDecimals": 2,
      "status": "AVAILABLE",
      "minHoldingSeconds": 0,
      "holdingTimeThresholdSizeUSD": "0",
      "pythPriceFeedId": "0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43",
      "pythProPriceFeedId": null,
      "pythSymbol": "Crypto.BTC/USD",
      "volume": "1234567.89",
      "volumeUSD": "1234567.89"
    }
  ],
  "pageNumber": 0,
  "pageSize": 20,
  "totalPages": 2,
  "totalElements": 24
}
```

| Field | Notes |
| :--- | :--- |
| `base` | The `pairBase` you pass to every contract call |
| `pairType` | `CRYPTO`, `STOCKS`, `FOREX`, `INDICES`, `COMMODITIES` |
| `status` | `AVAILABLE`, `REDUCE_ONLY`, `CLOSE` |
| `nextOpen` / `nextClose` | Non-null for markets with trading hours |
| `minHoldingSeconds` | Minimum time before a position can be closed |
| `priceDisplayDecimals` | Display hint only — prices are still 1e18 |
| `pythPriceFeedId` | The underlying feed. Not needed for the standard flow; use the [oracle endpoint](/api/oracle#price-updates-by-position). |
| `volume` / `volumeUSD` | Over `volume_time_range` |

::: warning Check `status` before trading
`REDUCE_ONLY` allows closes but not opens. `CLOSE` disables the market. Non-crypto markets are also
closed outside their trading hours — opening then reverts with `MarketClosed`.
:::

```ts
async function getPairs() {
  const res = await fetch(`${API}/v1/pairs?size=100`)
  const { content } = await res.json()

  return new Map(content.map((p: any) => [p.symbol, p]))
}

const pairs = await getPairs()
const btc = pairs.get('BTC')

if (btc.status !== 'AVAILABLE') throw new Error(`BTC is ${btc.status}`)
```

## Pair volume

```http
GET /v1/pairs/{pairBase}/volume
```

| Parameter | Default | Notes |
| :--- | :--- | :--- |
| `range` | `ONE_DAY` | `ONE_DAY`, `SEVEN_DAY`, `THIRTY_DAY`, `ALL` |
| `block_chain` | `MONAD` | |

```json
{
  "pairBase": "0xcf5a…",
  "volume": "1234567.89",
  "volumeUSD": "1234567.89",
  "period": "ONE_DAY"
}
```

Cached for five minutes.

## Cumulative volume

```http
GET /v1/pairs/{pairBase}/cumulative-volume
```

Same response shape with `period: "ALL"`. Equivalent to `/volume?range=ALL`.

## User volumes

Daily trading volume per user over a date range.

```http
GET /v1/trading-volumes/users?startTime=2026-07-01T00:00:00Z&endTime=2026-07-27T23:59:59Z
```

| Parameter | Required | Notes |
| :--- | :--- | :--- |
| `startTime` | yes | ISO-8601 with offset |
| `endTime` | yes | ISO-8601 with offset |
| `chains` | no | Comma-separated, defaults to `MONAD` |

```json
[
  {
    "userAddress": "0x…",
    "tradeDate": "2026-07-26",
    "dailyVolume": "125430.55",
    "openCount": 12,
    "closeCount": 11,
    "openVolume": "64000.00",
    "closeVolume": "61430.55"
  }
]
```

Returns one row per user per day. Not paginated — keep ranges bounded.

## Protocol volume

```http
GET /v1/trading-volumes/sum-by-date?startTime=…&endTime=…
GET /v1/trading-volumes/sum-all
```

```json
{ "vol": "98765432.10", "usdVol": "98765432.10" }
```

`sum-all` takes only the optional `chains` parameter.