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

# Markets

> Pair catalog, fees, funding, open interest, and spreads.

## Pair catalog

```python theme={null}
pairs = await client.markets.pairs()             # {index: PairInfo}
eth = await client.markets.pair("ETH/USD")       # by symbol or index

print(eth.index, eth.symbol)
print("leverage:", eth.leverages.min_leverage, "-", eth.leverages.max_leverage)
print("fees:", eth.open_fee_p, "/", eth.close_fee_p, "%")
print("funding/h:", eth.funding_fee_per_hour_p, "%")
print("OI:", eth.open_interest.long, "long /", eth.open_interest.short, "short")
```

Everything comes from one `/v2/trading` snapshot, cached for 5 seconds (`snapshot()` with `force=True` refreshes). For a live copy of the same payload (funding, OI, spreads, market hours) subscribe to the data service [Socket.IO feed](/data/socket-io). Useful `PairInfo` fields:

| Field                                                      | Meaning                                              |
| ---------------------------------------------------------- | ---------------------------------------------------- |
| `leverages`                                                | Min/max leverage (plus Upside-specific bounds)       |
| `open_fee_p`, `close_fee_p`, `spread_p`                    | Fees and fixed spread, in %                          |
| `min_lev_pos_usdc`                                         | Minimum position notional in USDC                    |
| `open_interest`, `pair_oi`, `pair_max_oi`, `max_wallet_oi` | OI state and caps                                    |
| `funding_rate`, `funding_fee_per_hour_p`, `margin_fee`     | Funding and rollover                                 |
| `values.max_gain_p`, `values.max_sl_p`                     | TP/SL percent bounds (`2500` = 2500% gain cap)       |
| `twap_params`                                              | Min/max run time, frequency, TWAP fee                |
| `pnl_fees`                                                 | Upside profit-share tiers                            |
| `is_upside`                                                | `True` for Upside markets (`_UPSIDE`-suffixed pairs) |
| `is_market_open`                                           | Market-hours check (matters for forex/commodities)   |

The snapshot itself (`await client.markets.snapshot()`) carries protocol-wide state: `total_oi`, `max_open_interest`, `group_info`, `max_trades_per_pair`.

## Upside markets

Upside markets (formerly "zero-fee"/ZFP) are separate pairs suffixed
`_UPSIDE` — `BTC_UPSIDE/USD` trades alongside `BTC/USD` with the same price
feed but no open/close fee and a tiered profit share on gains. Trading
methods route the order type automatically from the pair; you just pick the
market:

```python theme={null}
upside = await client.markets.upside_pairs()          # {index: PairInfo}

btc_upside = await client.markets.pair("BTC_UPSIDE")  # symbol works too
twin = await client.markets.upside_pair_for("BTC/USD")  # fixed-fee -> upside twin

print(btc_upside.is_upside)     # True
print(btc_upside.base_symbol)   # "BTC/USD" (suffix stripped)
```

Symbol resolution accepts `"BTC_UPSIDE"`, `"BTC_UPSIDE/USD"`, and quote-side
forms like `"USD/JPY_UPSIDE"`; `upside_pair_for` raises when a market has no
upside listing. Upside pairs are market-only — see
[Market orders](/trading/market-orders).

## Spread

Per-order spread quote from the risk engine v2 — the same endpoint the Avantis web app uses. Size the request by coin exposure directly, or by `collateral` + `leverage` (converted at `wanted_price`, or the live price when omitted):

```python theme={null}
spread = await client.markets.spread(
    "ETH/USD", collateral=1000, leverage=10, is_long=True,
)
print(spread["spreadPct"], spread["spreadMechanism"])   # percent, descaled
```

`spreadPct` is the quoted value (the with-flow estimate when the flow mechanism is active, otherwise the without-flow spread). A `404` means the engine matched a mechanism but could not compute a spread (for example a stale orderbook) — treat it as "do not execute", not as zero spread.

<Note>
  The v2 spread engine serves both networks — it is the production spread source. The legacy `client.markets.dynamic_spread(...)` endpoint was decommissioned on mainnet at the v2 cutover (it raises a `ConfigError` there) and remains available on testnet only.
</Note>

Related risk reads: `client.markets.open_interests()` (per-pair long/short OI including pending amounts) and `client.markets.orderbook_snapshots()` (cumulative bid/ask coin liquidity per orderbook source).

## Candles

OHLCV via the feed's TradingView shim:

```python theme={null}
import time
candles = await client.markets.candles("ETH/USD", "60", int(time.time()) - 86400, int(time.time()))
```

Resolutions follow TradingView conventions (`"1"`, `"5"`, `"60"`, `"D"`, ...).

For live prices and streaming, see [Prices & streams](/data/prices-and-streams).