For agents

Agent quickstart

A machine-readable map of the API. Discovery is free and unauthenticated, so use it to decide what to buy. Data endpoints answer 402 (x402 v2) until you pay with a signed authorisation. There's also an llms.txt, a live discovery JSON, and the full OpenAPI spec with every paid route's price bounds.

1 Discover (free, no auth)

bash

curl -s https://api.hyperextend.xyz/v1/discovery | jq .

Endpoint	Answers
`GET /v1/discovery`	Dex/coin counts, intervals, availability lag; one call to orient.
`GET /v1/dexes`	Every dex (main, HIP-3, HIP-4) with first/last seen.
`GET /v1/dexes/{dex}/coins`	Active universe on a dex.
`GET /v1/coins/{coin}`	Which dexes a coin trades on.
`GET /v1/coins/{coin}/history`	Listing / delisting / leverage-change log over time.
`GET /v1/outcome_markets?start=&end=`	HIP-4 outcome markets trading in a window (epoch-ms, optional). Name + the side coins & outcome id to buy candles / ctx / OI with.
`GET /v1/availability/{coin}`	Per-dex first/last for ctx + candles.
`GET /v1/coverage/{coin}?start=&end=`	Gap manifest for OI / ctx.
`GET /v1/candles/{coin}/coverage?start=&end=`	Gap manifest for candles.
`GET /v1/trades/discovery?coin=`	Trades model: served-live, archive floor, window cap, pricing; ?coin= adds hot first/last.
`GET /v1/trades/cache`	Archive hours already warm in the cold cache (coalesced ranges); no cold-pull fee inside them; shared with liquidations.
`GET /v1/liquidations/discovery?coin=`	Liquidations model: archive floor, ~2h lag, window cap, pricing; ?coin= adds dex + rate.

2 Pay (x402 v2)

Use Coinbase's official x402 client. It handles the v2 flow (402 challenge in the PAYMENT-REQUIRED header → sign an EIP-3009 authorisation → retry with PAYMENT-SIGNATURE → 200, receipt in PAYMENT-RESPONSE). You pay in USDC on Base, and the facilitator covers the gas (no ETH required).

python · exact

# pip install "x402[evm]"  (Coinbase's official x402 v2 client)
import asyncio
from eth_account import Account
from x402 import x402Client
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client
from x402.http.clients import x402HttpxClient

async def main():
    client = x402Client()
    register_exact_evm_client(client, EthAccountSigner(Account.from_key(MY_PRIVATE_KEY)))
    async with x402HttpxClient(client) as http:           # handles 402 -> pay -> retry
        r = await http.get("https://api.hyperextend.xyz/v1/candles/BTC/1m?start=0&end=1735689600000")
        candles = (await r.aread()) and r.json()

asyncio.run(main())

Already trading on Hyperliquid? The 402's accepts also offers a hyperliquid:mainnet rail: pay directly with the same USDC you trade and open positions with, via HyperCore's gasless sendAsset (no facilitator, no bridging). Sign a HyperliquidTransaction:SendAsset with the hyperliquid SDK and retry with PAYMENT-SIGNATURE; full recipe in /docs.

Many calls in a row? Base also advertises an opt-in batch-settlement scheme: deposit USDC into an escrow once, then pay per request with off-chain cumulative vouchers (~instant, no per-request on-chain tx). We batch the on-chain claim and CDP pays the gas. Register only the batch-settlement scheme with the x402[evm] client and it's chosen from accepts automatically. Step-by-step guide in /docs.

Endpoint	Returns
`GET /v1/candles/{coin}/{interval}?start=&end=`	OHLCV candles. Base rate on main/spot; premium on HIP-3 & outcome dexes.
`GET /v1/candles/{coin}/{interval}/latest?n=`	The most recent n candles, a cheap recent-window convenience.
`GET /v1/asset_ctx/{coin}?start=&end=`	OI / funding / mark / oracle / mid / volumes. Premium; served live (HL keeps no OI history).
`GET /v1/asset_ctx/{coin}/latest?n=`	The most recent n OI / ctx snapshots. Premium; live.
`GET /v1/outcome_ctx/{coin}?start=&end=`	HIP-4 outcome-side ctx: mark / mid / circulating supply / volumes. Premium; live.
`GET /v1/outcome_ctx/{coin}/latest?n=`	The most recent n outcome-side snapshots. Premium; live.
`GET /v1/outcome/{outcome}/oi?start=&end=`	Derived two-sided open interest for a HIP-4 outcome market, per minute. Premium; live.
`GET /v1/trades/{coin}?start=&end=`	Raw trade tape, mirroring HL's WsTrade verbatim (coin, side, px, sz, time, hash, tid, users:[buyer, seller]). Priced per asset-hour (≤24/request); HIP-3/HIP-4 premium; +$0.05 per uncached archive hour pulled (warms the cache).
`GET /v1/trades/coverage?coin=&start=&end=`	Archive coverage for a coin (≤7 days): hours present + gaps; warms the cache. Floor + $0.05 per archived hour examined.
`GET /v1/liquidations/{coin}?start=&end=`	Forced-liquidation tape: a trade row (coin, side, px, sz, time, hash, tid, users:[buyer, seller]) plus liquidation markers (method, markPx, liquidatedUser, dir). Archive-derived (no public HL feed; ~2h lag). Per asset-hour at a third of trades (≤24/request); +$0.05 per uncached archive hour pulled.
`GET /v1/liquidations/coverage?coin=&start=&end=`	Archive coverage for a coin's liquidations (≤7 days): hours present + gaps; warms the cache. Floor + $0.05 per archived hour examined.

3 Pricing

tariff

candles / OI / ctx : $0.001 + rows × per_row    # paginate with the X-Next-Start header
# per_row = $0.00001  base    (main-perp & spot candles)
#         = $0.000025 premium (open interest, HIP-3 perps, HIP-4 outcome markets)
trades             : $0.001 + asset_hours × per_asset_hour   # ≤24 asset-hours/request
# per_asset_hour = $0.015 base | $0.03 premium  (+ $0.05 per uncached archive hour pulled)
liquidations       : $0.001 + asset_hours × per_asset_hour   # archive-derived, ~2h lag, ≤24/request
# per_asset_hour = $0.005 base | $0.01 premium  (a third of trades; + $0.05 per uncached archive hour)

Full reference: /docs. OI, outcomes and trades are served live; candles lag ~2 days and liquidations ~2 hours (archive-derived). Newer candles? Query Hyperliquid directly.