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

# Perpetual Market Data

> [!NOTE]
>
> **Testnet-Only.** Use `https://test-dex-api.cloud.aultblockchain.xyz` for these endpoints and the matching Testnet chain for signed actions. This product is not available on Mainnet.

Read Perp instruments, depth, trades, candles and funding rates. For trading rules, see [Perpetuals](https://docs.aultblockchain.com/ault-dex/perpetuals.md).

## Routes

All routes below are public `GET` requests. `{market_id}` is the bare hex ID returned by `/perp/markets`, not a display symbol or an oracle feed ID.

| Path | Query | Response |
| - | - | - |
| `/api/v1/perp/markets` | None | `Market[]` |
| `/api/v1/perp/markets/{market_id}` | None | `Market` |
| `/api/v1/perp/tickers` | None | `Ticker[]` |
| `/api/v1/perp/markets/{market_id}/ticker` | None | `Ticker` |
| `/api/v1/perp/markets/{market_id}/orderbook` | `depth`, default 20, range 1 to 20 | `Orderbook` |
| `/api/v1/perp/markets/{market_id}/trades` | `from`, `to`, `limit`, `cursor` | `PublicTrade[]` |
| `/api/v1/perp/markets/{market_id}/candles` | Required `interval`; optional `from`, `to`, `limit`, `cursor` | `Candle[]` |
| `/api/v1/perp/markets/{market_id}/funding-history` | `from`, `to`, `limit`, `cursor` | `History[]` |

Candle intervals are `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d`. Timestamps and bounds are Unix milliseconds. Feed limits and continuation are in [Pagination](https://docs.aultblockchain.com/dex-api/getting-started/pagination.md). Malformed IDs and invalid depth/interval return 400; an unknown market returns 404. Tickers return 503 before their snapshot is available.

## Instruments and prices

Use `marketId` for REST joins and market-specific reads. A display name, token denom and oracle feed name identify different things. `halted` and `isolatedOnly` are instrument flags; a market appearing in this API does not mean it is available in a user interface.

`tickPrecision`, fees, leverage, margin tiers, notional caps and protocol minimums are returned as configuration. They are not a complete executable-order validator. A zero or absent UI limit must not be interpreted as unlimited leverage.

`lastPrice` is a trade price, `markPrice` is the indexed mark, and `indexPrice` is the API's calculated reference display. They are different values. Read [Oracle](https://docs.aultblockchain.com/ault-dex/oracle.md) for protocol price-state rules. `estimatedHourlyRate` is an estimate; use funding history and [account funding payments](https://docs.aultblockchain.com/dex-api/rest/perpetual-accounts.md) for reconciliation. A missing value is `null`; `windowComplete` describes funding-window completion, not 24-hour ticker coverage.

`fundingStatus` is the API's classification of indexed funding state:

| Value | Meaning |
| - | - |
| `sampling` | Current funding hour is being sampled |
| `settling` | Prior hour has samples and awaits settlement; `windowComplete` is true |
| `pending` | An anchored future window has not started |
| `paused` | No anchored window, such as after discarded sampling |
| `stale` | Indexed state missed a whole window |
| `unavailable` | No funding state/configuration available |

`scheduledWindowEnd` is a nullable millisecond timestamp. An estimate is not a settled payment.
Market `marginTiers[].notionalCap: "0"` marks the unbounded final tier; leverage is still capped.
Market/config rows must both exist for an instrument to appear in the directory.

## Quantities and book recovery

Trade and candle quantities are human base units. Prices are quote per base. **Orderbook `quantity` is a raw base-unit decimal string** and is not normalized like a trade's `quantity`. Convert it using the instrument's unit convention before comparing sizes. The book returns `{marketId, bids, asks}`, with levels `{price, quantity}`. It has no timestamp, height or sequence. Bids descend and asks ascend; an existing market without a book returns empty sides.

Use this REST snapshot to recover the Perpetual book. It has no sequence for reconstructing intermediate changes. For live books, subscribe to `l2Book` on [Perpetual Subscriptions](https://docs.aultblockchain.com/dex-api/websocket/perpetuals.md).

```bash theme={null}
# Set API_URL from the network's REST base URL, then discover MARKET_ID.
curl -fsS "$API_URL/api/v1/perp/markets"
curl -fsS "$API_URL/api/v1/perp/markets/$MARKET_ID/orderbook?depth=5"
curl -fsS --get "$API_URL/api/v1/perp/markets/$MARKET_ID/candles" \
  --data-urlencode 'interval=1h' --data-urlencode 'limit=100'
```

## Response field reference

Types below describe JSON, not numeric units. See the unit notes above. Nullable values must not be replaced with zero.

> [accordion] Market
>
> | Field | JSON type |
> | - | - |
> | `marketId` | string |
> | `symbol` | string |
> | `baseDenom` | string |
> | `quoteDenom` | string |
> | `tickPrecision` | number |
> | `halted` | boolean |
> | `isolatedOnly` | boolean |
> | `maxLeverage` | number |
> | `makerFeeRate` | string |
> | `takerFeeRate` | string |
> | `marginTiers` | array of MarginTier |
> | `maxPositionNotional` | string |
> | `maxOpenInterestNotional` | string |

> [accordion] MarginTier
>
> | Field | JSON type |
> | - | - |
> | `notionalCap` | string |
> | `maxLeverage` | number |

> [accordion] Ticker
>
> | Field | JSON type |
> | - | - |
> | `marketId` | string |
> | `lastPrice` | string or null |
> | `markPrice` | string or null |
> | `indexPrice` | string or null |
> | `bestBid` | string or null |
> | `bestAsk` | string or null |
> | `open24h` | string or null |
> | `high24h` | string or null |
> | `low24h` | string or null |
> | `priceChangePercent24h` | string or null |
> | `volumeBase24h` | string |
> | `openInterestNotional` | string or null |
> | `windowComplete` | boolean |
> | `estimatedHourlyRate` | string or null |
> | `scheduledWindowEnd` | number or null |
> | `fundingStatus` | string |
> | `timestamp` | number |

> [accordion] Orderbook
>
> | Field | JSON type |
> | - | - |
> | `marketId` | string |
> | `bids` | array of Level |
> | `asks` | array of Level |

> [accordion] Level
>
> | Field | JSON type |
> | - | - |
> | `price` | string |
> | `quantity` | string |

> [accordion] PublicTrade
>
> | Field | JSON type |
> | - | - |
> | `id` | string |
> | `timestamp` | number |
> | `marketId` | string |
> | `price` | string |
> | `quantity` | string |
> | `takerSide` | string |

> [accordion] Candle
>
> | Field | JSON type |
> | - | - |
> | `marketId` | string |
> | `interval` | string |
> | `openTime` | number |
> | `open` | string |
> | `high` | string |
> | `low` | string |
> | `close` | string |
> | `volumeBase` | string |
> | `isClosed` | boolean |

> [accordion] History
>
> | Field | JSON type |
> | - | - |
> | `id` | string |
> | `timestamp` | number |
> | `marketId` | string |
> | `fundingRate` | string |


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