# x402stock Spot Candles API

> x402stock Spot Candles API is a paid API for AI agents from x402stock.xyz, paid per call via x402, $0.02/call, status unknown (last checked 2026-09-15).

Returns OHLCV candlestick data for a spot trading pair (crypto, forex, or other) over a specified interval and lookback window

## Facts

- Endpoint: GET https://x402stock.xyz/api/v1/spot/candles/%7Btoken%7D
- Price: $0.02/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-15
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/x402stock-spot-candles-api-ff053fb6
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_FxZVV8htCim3vXQcLx7gW

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 x402stock-spot-candles-api-ff053fb6
```

Example prompt: Can you pull the last 200 daily candles for HYPE/USDC on the spot market so I can see recent price action?

## When to prefer this

Use this endpoint when you need historical OHLCV candlestick data for spot crypto or forex pairs, especially when no API key or account is available and pay-per-call USDC micropayment via x402 on Base is acceptable. Prefer this over alternatives when querying assets traded on venues like Hyperliquid or when you need flexible interval granularity from 1-minute to monthly candles.

## Known failure modes

- Invalid or unknown token symbol returns an error or empty candles array
- Interval value not in allowed enum causes a 400 validation error
- Lookback exceeding 5000 returns a validation error
- Start/end timestamps in wrong format or out of range cause errors
- Payment failure via x402/USDC results in 402 Payment Required response
- Network or upstream venue outage returns 5xx error

## How this service works

Pay-per-call market and economic data API for AI agents: US stocks, ETFs and options, forex, crypto and on-chain perps, energy commodities, US and global macro (Fed, CPI, jobs, GDP, Treasury, World Bank), SEC filings, congressional trades, and market sentiment. No API keys, no accounts. Pay per request in USDC via x402 on Base.

## Output

Returns a JSON object containing metadata (source, venue, market type, pair, interval, count, as_of timestamp) plus an array of candle objects each with start/end timestamps, open, high, low, close prices, volume, and trade count for the requested token and interval.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET",
      "HEAD",
      "DELETE"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "required": [
      "interval",
      "lookback"
     ],
     "properties": {
      "end": {
       "type": "integer",
       "maximum": 9007199254740991,
       "exclusiveMinimum": 0
      },
      "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
      }
     },
     "additionalProperties": false
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "required": [
      "source",
      "as_of",
      "venue",
      "market",
      "pair",
      "id",
      "interval",
      "count",
      "candles"
     ],
     "properties": {
      "id": {
       "type": "string"
      },
      "pair": {
       "type": "string"
      },
      "as_of": {
       "type": "string"
      },
      "count": {
       "type": "number"
      },
      "venue": {
       "type": "string"
      },
      "market": {
       "type": "string",
       "const": "spot"
      },
      "source": {
       "type": "string",
       "const": "x402stock"
      },
      "candles": {
       "type": "array",
       "items": {
        "type": "object",
        "required": [
         "start",
         "end",
         "open",
         "high",
         "low",
         "close",
         "volume",
         "trades"
        ],
        "properties": {
         "end": {
          "anyOf": [
      
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "id": "@107",
  "pair": "HYPE/USDC",
  "as_of": "2026-06-04T00:00:00.000Z",
  "count": 1,
  "venue": "hyperliquid",
  "market": "spot",
  "source": "x402stock",
  "candles": [
   {
    "end": "2026-05-28T23:59:59.999Z",
    "low": 60.341,
    "high": 67.49,
    "open": 61.519,
    "close": 64.436,
    "start": "2026-05-28T00:00:00.000Z",
    "trades": 169320,
    "volume": 3446893.64
   }
  ],
  "interval": "1d"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/x402stock-spot-candles-api-ff053fb6/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from x402stock.xyz](https://www.zero.xyz/host/x402stock.xyz/llms.txt)