# Get Hyperliquid perpetual futures and spot data with x402stock's API

x402stock's API returns Hyperliquid perpetual-futures and spot market data from four GET requests: every perp market at once, one coin's market, one coin's hourly funding-rate history, and every Hyperliquid-listed spot token. Each request is priced on its own, from $0.01 for one coin to $0.02 for every perp market, with no account or API key. Send the GET, pay the 402 price quote over x402 or MPP, and retry the same request to receive the JSON.

## At a glance

- **Endpoints:** `GET https://agents.x402stock.xyz/zcj/fu327twk2mut/api/v1/perps`, `/api/v1/perps/{coin}`, `/api/v1/perps/funding/{coin}`, `/api/v1/spot`
- **Inputs:** `{coin}` is a Hyperliquid perpetual coin symbol, such as `BTC` or `ETH`. Funding history takes `?hours=` (default 24, max 720) or `?start=`/`?end=` in epoch milliseconds.
- **Price per request:** all perps $0.02, one coin $0.01, funding history $0.01, all spot $0.02
- **Payment:** a 402 price quote, paid over x402 (Base USDC) or MPP (Tempo USDC) and retried. No account or API key.
- **Response:** JSON with `source`, `as_of` and `venue` (Hyperliquid), plus the market data for the request
- **Limits:** one coin per per-coin request, funding history up to 720 hours, market data only
- **Full purchase flow:** [the buyer skill](https://agents.x402stock.xyz/zcj/fu327twk2mut/SKILL.md)

## Choose the request

The all-markets call shows what is moving across every perp. The per-coin calls show one market's state and how its funding has moved.

| You want | Request | Price |
| --- | --- | --- |
| Every perpetual market's state in one response | `GET /api/v1/perps` | $0.02 |
| One perpetual market's state | `GET /api/v1/perps/{coin}` | $0.01 |
| One market's hourly funding-rate history | `GET /api/v1/perps/funding/{coin}?hours=24` | $0.01 |
| Every Hyperliquid-listed spot token's market | `GET /api/v1/spot` | $0.02 |

## Read every perpetual market in one call

1. Send the request:

   ```bash
   curl -i https://agents.x402stock.xyz/zcj/fu327twk2mut/api/v1/perps
   ```

   The storefront answers `402 Payment Required` with the price. Nothing is charged at this point.

2. Pay the 402 with your x402 or MPP client and retry the same request with the proof attached. An x402 client sends it in the `x-payment` header:

   ```bash
   curl https://agents.x402stock.xyz/zcj/fu327twk2mut/api/v1/perps -H "x-payment: <signed payload>"
   ```

3. Read the response. It is a JSON object with `source`, `as_of`, `venue`, `market`, `count` and a `perps` array with one entry per market. Each entry includes `coin`, `mark_price`, `oracle_price`, `mid_price`, `prev_day_price`, `funding_rate_hourly`, `funding_apr_percent`, `premium`, `open_interest`, `day_volume_usd` and `day_volume_base`. The example request paid $0.02.

   ```json
   {"source": "<string>", "as_of": "<string>", "venue": "<string>", "market": "<string>", "count": 0, "perps": [{"coin": "<string>", "mark_price": 0, "funding_rate_hourly": 0, "funding_apr_percent": 0, "open_interest": 0, "...": "..."}]}
   ```

## Read one coin and its funding-rate history

The per-coin requests use the same 402 and retry as above.

1. Request one market by coin symbol:

   ```bash
   curl -i https://agents.x402stock.xyz/zcj/fu327twk2mut/api/v1/perps/BTC
   ```

   The response carries `source`, `as_of`, `venue`, `market` and a `data` object with the same fields as one entry of the all-markets `perps` array. The example request paid $0.01.

2. Request that coin's funding-rate history for a window:

   ```bash
   curl -i "https://agents.x402stock.xyz/zcj/fu327twk2mut/api/v1/perps/funding/BTC?hours=24"
   ```

   The response carries `source`, `as_of`, `venue`, `coin`, `count` and a `history` array, most recent first, with one entry per hour. Each entry has `time`, `funding_rate_hourly`, `funding_apr_percent` and `premium`. The example request paid $0.01.

   ```json
   {"source": "<string>", "as_of": "<string>", "venue": "<string>", "coin": "<string>", "count": 0, "history": [{"time": "<string>", "funding_rate_hourly": 0, "funding_apr_percent": 0, "premium": 0}]}
   ```

   Widen the window with `hours` up to 720. To set an exact range, send `start` and `end` in epoch milliseconds.

## Read on-chain spot prices for every token

Send `GET https://agents.x402stock.xyz/zcj/fu327twk2mut/api/v1/spot` and settle its 402 the same way. The response covers the spot market for every Hyperliquid-listed token. The example request paid $0.02. The service's [API reference](https://agents.x402stock.xyz/zcj/fu327twk2mut/services/crypto-perps/openapi.json) defines the response fields.

## Budget a monitoring run

Each request is charged on its own, so a run costs the sum of its calls.

| Run | Cost |
| --- | --- |
| One all-markets read, then funding history for three coins | $0.05 |
| Ten single-coin reads | $0.10 |
| One read of each of the four requests | $0.06 |

## Limits

- These calls read market data only. They place no orders and take no wallet address.
- The per-coin requests take one coin each. For several coins, send one request per coin, or read the all-markets response.
- Each read is a separate paid request. A 402 you have not paid charges nothing, so it is safe to stop there.
- Card payment and prepaid Credits are covered in [the buyer skill](https://agents.x402stock.xyz/zcj/fu327twk2mut/SKILL.md).
- Other Crypto & Perps requests are in the service's API reference.

## Errors

| Response | Meaning | Action |
| --- | --- | --- |
| `402` with a `payment` block and no `reason` | The normal per-call price quote | Pay it and retry the same request with the proof |
| `settlement_failed` | The signed payment did not settle; `settlementReason` says why | Fix the wallet, then send the request again for a fresh 402 |
| `payment_request_mismatch` (409) | A payment was reused for a different request | Request a fresh 402 for this request and settle that one |
| `usage_exhausted` | The Credits balance ran out | Top up the balance; [the buyer skill](https://agents.x402stock.xyz/zcj/fu327twk2mut/SKILL.md) has the steps |
| Any other status after payment | The upstream API's own status and body | Read the upstream body and check the request against the API reference |

## Frequently asked questions

### Is there a Hyperliquid funding rate API that needs no API key?

Yes. `GET /api/v1/perps/funding/{coin}` on x402stock's storefront returns a coin's hourly funding-rate history for $0.01 per request, paid at the request over x402 or MPP, with no account or key.

### How far back does the funding-rate history go?

Set `hours` up to 720 for a window ending now, or send `start` and `end` in epoch milliseconds for a fixed range. The default window is 24 hours.

### Should I call all perps or one coin?

Call `/api/v1/perps` to compare every market in one response for $0.02. Call `/api/v1/perps/{coin}` for $0.01 when you follow a single market.

### What does each perpetual market entry contain?

Mark, oracle and mid prices, the previous-day price, the hourly funding rate with its annualized APR, the premium, open interest, and day volume in USD and in the base asset.

### Can I pay for these calls by card?

Not per call, since card pay-as-you-go starts at $0.50. Buy prepaid Credits by card instead and let each call draw down the balance.

## Keep reading

- [Buyer skill](https://agents.x402stock.xyz/zcj/fu327twk2mut/SKILL.md): the full purchase flow
- [How to pay](https://agents.x402stock.xyz/zcj/fu327twk2mut/payment.md): x402, MPP, card and Credits
- [Crypto & Perps API reference](https://agents.x402stock.xyz/zcj/fu327twk2mut/services/crypto-perps/openapi.json): every operation and parameter
- [Error reference](https://agents.x402stock.xyz/zcj/fu327twk2mut/errors.md): every error code and the action to take

---

Updated 2026-10-16. All x402stock guides: https://agents.x402stock.xyz/guides.md. Storefront: https://agents.x402stock.xyz/zcj/fu327twk2mut/llms.txt.