# GET /perps/candles: $0.002 per call

OHLCV candles for a perpetual futures market on Hyperliquid or dYdX (1m to 1d, up to 500), with a summary: change, high/low, USD volume and annualised realised volatility. Pass ?coin=ETH&interval=1h&limit=24 (&venue=dydx).

- **Price:** $0.002 in USDC, the same on Base, Solana, Polygon, Arbitrum. Failed calls are never charged.
- **Free trial:** yes, 20 free calls a day from Claude, Cursor or any MCP client ([set-up](/mcp/setup)).
- **Answers cached for:** 30 s
- **Data sources:** Hyperliquid public info API; dYdX v4 public indexer
- **Lane:** Perpetual futures data ([OpenAPI](/openapi/perps.json))
- **Live health:** [status page](/status)

## Free sample

See an answer for the demo input first, free (no payment, 10 a minute): [https://aayatai.com/sample/perps-candles](/sample/perps-candles). It is a stored real answer when we have one, otherwise an example marked `"kind": "illustrative"`.

```bash
curl "https://aayatai.com/sample/perps-candles"
```

## 1. See the price (free)

Call it without paying: you get `402 Payment Required` and a `PAYMENT-REQUIRED` header with the exact price and where to pay.

```bash
curl -i "https://aayatai.com/perps/candles?coin=BTC&interval=1h&limit=6"
```

## 2. Pay and call (TypeScript)

```bash
npm install @x402/fetch @x402/evm viem
```

```ts
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

// A wallet used only by your agent, holding a little USDC on Base.
const account = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY as `0x${string}`);
const pay = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
});

const res = await pay("https://aayatai.com/perps/candles?coin=BTC&interval=1h&limit=6");
console.log(await res.json());
```

## 3. Or as an MCP tool

```ts
// MCP server: https://aayatai.com/mcp (Streamable HTTP). With the x402 MCP client (see /start):
const result = await client.callTool("perps-candles", {"coin":"BTC","interval":"1h","limit":6});
```

## Inputs

- `coin` **(required)** (string): Market symbol, e.g. BTC, ETH, SOL.
- `interval` (string; one of `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d`; default `1h`): Candle size.
- `limit` (integer; default `24`): How many of the latest candles (2-500).
- `venue` (string; one of `auto`, `hyperliquid`, `dydx`; default `auto`): auto (default: Hyperliquid, or dYdX while Hyperliquid is unavailable), hyperliquid or dydx.
- `detail` (string; one of `full`, `brief`; default `full`): brief = key fields only (same price)

Bad inputs are rejected with HTTP 400 before any payment is asked for.

## Example answer

Example only: the shape of an answer, with placeholder addresses and made-up figures. It is not data about any real token or wallet; call the service (or its free sample) for real results.

```json
{
  "venue": "hyperliquid",
  "coin": "BTC",
  "interval": "1h",
  "asOf": "2026-09-30T03:35:00.000Z",
  "candles": [
    {
      "time": "2026-09-29T22:00:00.000Z",
      "open": 83465,
      "high": 83697,
      "low": 83464,
      "close": 83573,
      "volumeCoins": 648.69592,
      "volumeUsd": 54213464,
      "trades": 8004
    },
    {
      "time": "2026-09-29T23:00:00.000Z",
      "open": 83573,
      "high": 83801,
      "low": 83568,
      "close": 83620,
      "volumeCoins": 489.27094,
      "volumeUsd": 40912836,
      "trades": 6156
    },
    {
      "time": "2026-09-30T00:00:00.000Z",
      "open": 83620,
      "high": 83689,
      "low": 83301,
      "close": 83411,
      "volumeCoins": 656.57928,
      "volumeUsd": 54765934,
      "trades": 8016
    },
    {
      "time": "2026-09-30T01:00:00.000Z",
      "open": 83412,
      "high": 83521,
      "low": 83294,
      "close": 83405,
      "volumeCoins": 381.18808,
      "volumeUsd": 31792992,
      "trades": 5677
    },
    {
      "time": "2026-09-30T02:00:00.000Z",
      "open": 83405,
      "high": 83581,
      "low": 83250,
      "close": 83344,
      "volumeCoins": 302.27044,
      "volumeUsd": 25192428,
      "trades": 6077
    },
    {
      "time": "2026-09-30T03:00:00.000Z",
      "open": 83349,
      "high": 83399,
      "low": 83133,
      "close": 83289,
      "volumeCoins": 580.14654,
      "volumeUsd": 48319825,
      "trades": 5001
    }
  ],
  "summary": {
    "candles": 6,
    "from": "2026-09-29T22:00:00.000Z",
    "to": "2026-09-30T03:00:00.000Z",
    "open": 83465,
    "close": 83289,
    "high": 83801,
    "low": 83133,
    "changePct": -0.211,
    "volumeUsd": 255197479,
    "realizedVolAnnualPct": 10.71
  },
  "attribution": "Data from Hyperliquid's public info API (api.hyperliquid.xyz)."
}
```

## Related

- [GET /perps/funding](/services/perps-funding) ($0.003): Perpetual futures funding rates from Hyperliquid and dYdX: the current hourly rate, 8-hour and annualised equivalents, premium, mark and oracle price and open i
- [GET /perps/open-interest](/services/perps-open-interest) ($0.002): Open interest on Hyperliquid or dYdX perpetual futures: contracts and USD value per market, share of the venue total, 24h volume, volume/OI, 24h price change an
- [GET /perps/markets](/services/perps-markets) ($0.003): Every perpetual futures market on Hyperliquid and dYdX side by side: which venues list each coin, price, open interest, 24h volume, max leverage and funding (ho
- [GET /perps/orderbook](/services/perps-orderbook) ($0.002): Live order book for a perpetual futures market on Hyperliquid or dYdX: best bid and ask, spread in bps, USD depth within 10/50/100 bps of mid, and the average f

New here? [Getting started in 60 seconds](/start). All services: [Aayat AI](/).