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

# useMarket

> Query trading pairs and market data

```tsx theme={null}
import { useMarket } from "@0xmonaco/react";

const {
  getPaginatedTradingPairs,
  getTradingPairBySymbol,
  getCandlesticks,
  getMarketMetadata,
  // Perp market helpers
  getPerpMarketConfig,
  getPerpMarketSummary,
  getMarkPrice,
  getIndexPrice,
  getFundingState,
  listFundingHistory,
  getOpenInterest,
} = useMarket();
```

## Trading Pairs

<ResponseField name="getPaginatedTradingPairs" type="(params?) => Promise<GetTradingPairsResponse>">
  Fetch paginated list of trading pairs.

  **Returns:** `{ tradingPairs: TradingPair[], page, pageSize, total, totalPages }`
</ResponseField>

<ResponseField name="getTradingPairBySymbol" type="(symbol: string) => Promise<TradingPair | undefined>">
  Get a specific trading pair by symbol. Resolves `undefined` on a miss (never throws), so guard the result before dereferencing. The hook forwards only `symbol`; to disambiguate a symbol listed in both SPOT and MARGIN, call `sdk.market.getTradingPairBySymbol(symbol, marketType)` on the core SDK directly.
</ResponseField>

## Market Data

<ResponseField name="getCandlesticks" type="(tradingPairId: string, interval: Interval, params?: GetCandlesticksParams) => Promise<Candlestick[]>">
  Fetch OHLCV candlestick data for a trading pair.

  **Parameters:**

  * `tradingPairId`: string - Trading pair UUID (use `getTradingPairBySymbol` to get this)
  * `interval`: `"1m" | "5m" | "15m" | "1h" | "4h" | "1d"`
  * `params?`: Optional query parameters
    * `startTime?`: number - Unix timestamp in ms
    * `endTime?`: number - Unix timestamp in ms
    * `limit?`: number - Max candlesticks (default: 350, max: 500)
    * `priceType?`: `"trade" | "mark"` - price series to chart. `"trade"` (default) is the trade-derived OHLCV series; `"mark"` is the close-only mark-price series for margin pairs (each candle's open/high/low/close are the minute's closing mark, volume `0`). `"mark"` on a spot pair returns a `400`

  **Example:**

  ```tsx theme={null}
  const { getTradingPairBySymbol, getCandlesticks } = useMarket();

  const pair = await getTradingPairBySymbol('BTC/USDC');
  const candles = await getCandlesticks(pair.id, '1h', { limit: 100 });
  ```
</ResponseField>

<ResponseField name="getMarketMetadata" type="(pairId: string) => Promise<MarketMetadata>">
  Fetch market metadata for a trading pair including current price, volume, and statistics.

  **Parameters:**

  * `pairId`: string - Trading pair UUID

  **Returns:** `MarketMetadata` object with market statistics

  <Warning>
    **Important:** All market metadata fields are nullable. Markets without trade history will return `null` for price and volume fields.
  </Warning>

  **Fields** (all nullable):

  * `lastPrice: string | null` - Most recent trade price (null if no trades)
  * `lastPriceTimestamp: number | null` - Timestamp of last trade
  * `high24h: string | null` - 24-hour high price (null if insufficient data)
  * `low24h: string | null` - 24-hour low price (null if insufficient data)
  * `volume24h: string | null` - 24-hour trading volume in base-asset units (null if insufficient data)
  * `quoteVolume24h?: string | null` - 24-hour trading volume in quote-token (USDC) units
  * `priceChange24h: string | null` - 24-hour price change
  * `priceChangePercent24h: string | null` - 24-hour price change percentage
  * `marketInitializationTimestamp: number | null` - When market was initialized

  **Example with null checks:**

  ```typescript theme={null}
  const metadata = await getMarketMetadata(pair.id);

  // Always check for null before using
  if (metadata.lastPrice !== null) {
    console.log(`Current price: ${metadata.lastPrice}`);
  } else {
    console.log('No trades yet for this market');
  }

  // Use nullish coalescing for defaults
  const displayPrice = metadata.lastPrice ?? 'N/A';
  const displayVolume = metadata.volume24h ?? '0';
  ```
</ResponseField>

## Perp Market Data

For margin concepts, see [Margin](/trading-mechanics/perps). For full type shapes, see the [TypeScript Market reference](/sdk/typescript/market).

<ResponseField name="getPerpMarketConfig" type="(tradingPairId: string) => Promise<PerpMarketConfig>">
  Static perp config: `minLeverage`, `maxLeverage`, base initial/maintenance margin ratios, `fundingIntervalSeconds`, `riskTiers`, `liquidationFeeBps`.
</ResponseField>

<ResponseField name="getPerpMarketSummary" type="(tradingPairId: string) => Promise<PerpMarketSummary>">
  Aggregate snapshot: `markPrice`, `indexPrice`, 24h stats (base-asset `volume24h` and quote-token `quoteVolume24h`), `openInterest` (gross base-asset open interest, longs plus shorts; alias of `openInterestBase`), `openInterestBase`, `openInterestNotional` (base × mark, in quote units), `currentFundingRate`, `nextFundingTime`.
</ResponseField>

<ResponseField name="getMarkPrice" type="(tradingPairId: string) => Promise<MarkPrice>">
  Live mark price (oracle reference). Returns `{ markPrice, oracleProvider, regime, updatedAt, ... }`.
</ResponseField>

<ResponseField name="getIndexPrice" type="(tradingPairId: string) => Promise<IndexPrice>">
  Live index price with provider components. Returns `{ indexPrice, components: IndexComponent[], updatedAt }`.
</ResponseField>

<ResponseField name="getFundingState" type="(tradingPairId: string) => Promise<FundingState>">
  Current and estimated next funding rate plus settlement time.
</ResponseField>

<ResponseField name="listFundingHistory" type="(tradingPairId: string, params?: ListFundingHistoryParams) => Promise<ListFundingHistoryResponse>">
  Settled funding history for one pair. Cursor-paginated: `pageSize` 1 to 1000 (default 50), `pageToken`, `orderBy` (`ASC`/`DESC`, default `DESC`), optional `startTime`/`endTime`. There is no `page`: the SDK rejects one with a `ValidationError` before sending. Follow `nextPageToken` until it comes back `""`.
</ResponseField>

<ResponseField name="getOpenInterest" type="(tradingPairId: string) => Promise<OpenInterest>">
  Current gross open interest (longs plus shorts) in base-asset units and notional.
</ResponseField>

**Example — funding countdown:**

```tsx theme={null}
import { useMarket } from "@0xmonaco/react";
import { useEffect, useState } from "react";

function FundingCountdown({ tradingPairId }: { tradingPairId: string }) {
  const { getFundingState } = useMarket();
  const [next, setNext] = useState<string | null>(null);
  const [rate, setRate] = useState<string | null>(null);

  useEffect(() => {
    let cancelled = false;
    const tick = async () => {
      const state = await getFundingState(tradingPairId);
      if (cancelled) return;
      setNext(state.nextFundingTime);
      setRate(state.currentFundingRate);
    };
    tick();
    const id = setInterval(tick, 15000);
    return () => { cancelled = true; clearInterval(id); };
  }, [tradingPairId, getFundingState]);

  if (!next) return null;
  const msUntil = new Date(next).getTime() - Date.now();
  return (
    <span>
      Funding in {Math.max(0, Math.floor(msUntil / 1000))}s — rate {rate}
    </span>
  );
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.