# Hyperliquid Perpetual Futures Historical OHLCV Candles

> Hyperliquid Perpetual Futures Historical OHLCV Candles is a paid API for AI agents from agents.x402stock.xyz, paid per call via MPP, $0.02/call, status unknown (last checked 2026-09-12).

Returns historical OHLCV (open, high, low, close, volume) candlestick data for a specified perpetual futures market on Hyperliquid DEX at configurable intervals and time windows.

## Facts

- Endpoint: GET https://agents.x402stock.xyz/api/v1/perps/candles/{coin}
- Price: $0.02/call
- Payment: MPP
- Status: unknown
- Last checked: 2026-09-12
- Activations on Zero: 0
- Provider: agents.x402stock.xyz
- Website: https://agents.x402stock.xyz
- Canonical page: https://www.zero.xyz/c/agents-x402stock-xyz-hyperliquid-perpetual-futures-historical-ohlcv-241cc8b5
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_q5AyMvsN0YVWNUT_bkFko

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability agents-x402stock-xyz-hyperliquid-perpetual-futures-historical-ohlcv-241cc8b5
```

Example prompt: Pull the last 500 hourly OHLCV candles for BTC perpetual futures from Hyperliquid so I can analyze recent price action.

## When to prefer this

Choose this endpoint when you need historical candlestick price data specifically for perpetual futures markets trading on the Hyperliquid DEX. It is the right choice for on-chain perp OHLCV data without requiring API keys, supports flexible intervals from 1-minute to monthly, and allows both lookback-count and explicit date-range queries. Prefer this over spot crypto candle endpoints when the user specifically needs perpetual futures (funding rate exposure, leveraged instruments) rather than spot prices.

## Known failure modes

- Invalid coin symbol returns an error or empty candle array
- Requesting more than 5000 candles exceeds the maximum lookback limit
- Invalid interval value not in the supported enum returns a validation error
- Start/end epoch-ms range with no data returns empty candles array
- Hyperliquid DEX unavailability may result in stale or missing data
- Malformed epoch-ms timestamps (e.g. seconds instead of milliseconds) produce incorrect time windows

## How this service works

Historical OHLCV candles for one perpetual-futures market at the requested interval (1m, 5m, 15m, 1h, 4h, 1d, 1w, and more) over a time window. Pass the coin in the path (e.g. BTC) and tune with `?interval=` (default 1h), `?lookback=` candles (default 200, max 5000), or an explicit `?start=`/`?end=` epoch-ms range. Free on-chain DEX data (venue: Hyperliquid), no key. From x402stock

## Output

Returns a JSON object containing the data source, timestamp of the response, venue (Hyperliquid), coin symbol, interval, candle count, and an array of OHLCV candles — each with start/end timestamps, open, high, low, close prices, volume, and trade count.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "required": [
  "coin"
 ],
 "properties": {
  "end": {
   "type": "integer",
   "maximum": 9007199254740991,
   "exclusiveMinimum": 0
  },
  "coin": {
   "type": "string",
   "description": "Hyperliquid perpetual coin symbol, e.g. BTC or ETH."
  },
  "start": {
   "type": "integer",
   "maximum": 9007199254740991,
   "exclusiveMinimum": 0
  },
  "interval": {
   "enum": [
    "1m",
    "3m",
    "5m",
    "15m",
    "30m",
    "1h",
    "2h",
    "4h",
    "8h",
    "12h",
    "1d",
    "3d",
    "1w",
    "1M"
   ],
   "type": "string",
   "default": "1h"
  },
  "lookback": {
   "type": "integer",
   "default": 200,
   "maximum": 5000,
   "exclusiveMinimum": 0
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "required": [
  "source",
  "as_of",
  "venue",
  "coin",
  "interval",
  "count",
  "candles"
 ],
 "properties": {
  "coin": {
   "type": "string"
  },
  "as_of": {
   "type": "string"
  },
  "count": {
   "type": "number"
  },
  "venue": {
   "type": "string"
  },
  "source": {
   "type": "string",
   "const": "x402stock"
  },
  "candles": {
   "type": "array",
   "items": {
    "type": "object",
    "required": [
     "start",
     "end",
     "open",
     "high",
     "low",
     "close",
     "volume",
     "trades"
    ],
    "properties": {
     "end": {
      "anyOf": [
       {
        "type": "string"
       },
       {
        "type": "null"
       }
      ]
     },
     "low": {
      "anyOf": [
       {
        "type": "number"
       },
       {
        "type": "null"
       }
      ]
     },
     "high": {
      "anyOf": [
       {
        "type": "number"
       },
       {
        "type": "null"
       }
      ]
     },
     "open": {
      "anyOf": [
       {
        "type": "number"
       },
       {
        "type": "null"
       }
      ]
     },
     "close": {
      "anyOf": [
       {
        "type": "number"
       },
       {
        "type": "null"
       }
      ]
     },
     "start": {
      "anyOf": [
       {
        "type": "string"
       },
       {
        "type": "null"
       }
      ]
     },
     "trades": {
      "anyOf": [
       {
        "type": "number"
       },
       {
        "type": "null"
       }
      ]
     },
     "volume": {
      "anyOf": [
       {
        "type": "number"
       },
       {
        "type": "null"
       }
      ]
     }
    },
    "additionalProperties": false
   }
  },
  "interval": {
   "type": "string"
  }
 },
 "additionalProperties": false
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/agents-x402stock-xyz-hyperliquid-perpetual-futures-historical-ohlcv-241cc8b5/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from agents.x402stock.xyz](https://www.zero.xyz/host/agents.x402stock.xyz/llms.txt)