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

# Sources & Markets

> Hyperliquid market classes and symbol schemes.

## Source

Every Ironflow response carries a `source` field. Today it is always `hyperliquid` — Ironflow is purpose-built for Hyperliquid and indexes the full HL economy.

| Source | Description |
| - | - |
| `hyperliquid` | Hyperliquid HyperCore — native perps, HL spot, HIP-3 builder markets, and HIP-4 outcome contracts |

`source` defaults to `hyperliquid` if omitted. The field exists in the schema so we can extend cleanly later if needed, but Hyperliquid is the dataset and where we put 100% of our reliability focus.

## Market symbols

Hyperliquid runs four kinds of markets, all ingested under `source=hyperliquid`. Each carries a `market_class` field on response objects so you can filter or branch on shape.

**Native HL perps** (`market_class: "perp"`) — listed by Hyperliquid itself. Symbol is just `{BASE}-PERP`:

```
BTC-PERP     # Bitcoin perpetual
ETH-PERP     # Ethereum perpetual
SOL-PERP     # Solana perpetual
```

**HIP-3 builder markets** (`market_class: "perp"`) — deployed by third-party builders (Felix Exchange, XYZ, HyENA, Kinetiq, etc.) on top of HyperCore. Symbol is namespaced by the builder's issuer prefix: `{issuer}:{BASE}-PERP`:

```
xyz:NVDA-PERP    # Nvidia stock perp by Trade.xyz
flx:GAS-PERP     # Natural gas perp by Felix Exchange
hyna:BASED-PERP  # BASED perp by HyENA
km:HYPE-PERP     # HYPE perp by Markets by Kinetiq
```

**HL spot pairs** (`market_class: "spot"`) — accept either the human form `{BASE}/{QUOTE}` or the underlying numeric coin alias `@{index}`. Both resolve to the same market on the wire; pick whichever is easier to read in your client.

```
HYPE/USDC    # human form
@285         # numeric coin alias for the same pair
PURR/USDC
```

**HIP-4 outcome contracts** (`market_class: "prediction"`) — fully collateralized binary contracts that settle at 0 or 1 based on a real-world event. Each contract has two complementary sides whose prices sum to 1.0 (the implied probability). Display symbol is `{UNDERLYING}-{TARGET}-{EXPIRY}-{Yes|No}` for binary price contracts:

```
BTC-78213-20260503-Yes   # "Will BTC close above $78,213 on 2026-05-03?"
BTC-78213-20260503-No    # the complementary "No" side, prices sum to 1.0
```

The on-chain wire form is `#N` (e.g. `#0`, `#1`). Both forms resolve to the same market — query whichever is more readable in your client. Each market's full metadata (resolution condition, expiration timestamp, target price, period) is available via the `metadata` JSON column on `/v1/markets`.

Endpoints that are intrinsically perp-only (`/v1/funding`, `/v1/open-interest`, `/v1/mark-prices`) return `400 INVALID_MARKET_CLASS` for spot symbols (`HYPE/USDC`, `@285`) and prediction symbols (`#0-OUTCOME`, `BTC-...-Yes/No`) — those concepts don't apply outside perps. Use the multi-class endpoints (`/v1/trades`, `/v1/fills`, `/v1/candles`) for spot and prediction.

Market symbols are **case-sensitive**.

### Three ways to filter

Every market-scoped endpoint accepts three forms:

| Filter | What it matches |
| - | - |
| `market=flx:GAS-PERP` | One specific HIP-3 build |
| `base_market=GAS-PERP&issuer=flx` | Same as above, decomposed |
| `base_market=GOLD-PERP` (issuer omitted) | Every issuer's GOLD-PERP (cross-issuer query) |
| `market=BTC-PERP` | One specific native HL perp |
| `market=BTC-PERP&issuer=` | ❌ Don't pass empty `issuer` — omit it instead. |

For native HL markets `issuer` is the empty string and `market == base_market`. The decomposed form is most useful when you want to query a base symbol (`GOLD`, `NVDA`, `SILVER`) across every builder that has deployed it.

### Decomposed response fields

Every market-scoped response object carries three identifiers:

```json theme={null}
{
  "source": "hyperliquid",
  "market": "flx:GAS-PERP",
  "issuer": "flx",
  "base_market": "GAS-PERP",
  "timestamp": 1718400000000,
  "price": "1.5021",
  "size": "12000",
  "side": "buy"
}
```

Group or aggregate by `issuer` to compare builders, by `base_market` to combine all builds of one symbol, or by `market` for the full canonical identifier.

### Getting available markets

One call covers every class — native perps, HIP-3 builder markets, spot, and prediction — from the markets registry:

```bash theme={null}
# Everything (native + builder perps + spot)
curl "https://api.ironflow.sh/v1/markets" \
  -H "Authorization: Bearer if_your_api_key"

# Only HIP-3 builder markets from one issuer
curl "https://api.ironflow.sh/v1/markets?issuer=xyz" \
  -H "Authorization: Bearer if_your_api_key"

# Only native markets (no builder prefix)
curl "https://api.ironflow.sh/v1/markets?issuer=" \
  -H "Authorization: Bearer if_your_api_key"
```

Each row carries the full identity tuple — `market_id`, `market_class`, `issuer`, `base_asset`, `base_market`, `display_symbol`, `hl_coin` — so you can join `/v1/markets` results against any other response without renaming columns.

```python theme={null}
import requests

rows = requests.get(
    "https://api.ironflow.sh/v1/markets",
    headers={"Authorization": "Bearer if_your_api_key"},
).json()["data"]

native = [m["display_symbol"] for m in rows if m["market_class"] == "perp" and not m["issuer"]]
hip3 = [m["display_symbol"] for m in rows if m["issuer"]]
print(f"{len(native)} native HL perps, {len(hip3)} HIP-3 builder markets")
```

## Omitting market

Most endpoints accept optional `market`, `base_market`, and `issuer` parameters. When all are omitted, the query covers **all markets** (both native and HIP-3):

```bash theme={null}
# All trades across all markets, all issuers
curl "https://api.ironflow.sh/v1/trades?source=hyperliquid&from=1718398800000" \
  -H "Authorization: Bearer if_your_api_key"
```

This is useful for cross-market dashboards or whale alert systems. Tier query-window limits apply more aggressively without a market filter — see [Rate Limits](/concepts/rate-limits).


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