> ## Documentation Index > Fetch the complete documentation index at: https://docs.ironflow.sh/llms.txt > Use this file to discover all available pages before exploring further. # Start a 7-day Explorer trial > POST /v1/billing/trial gives a free account that used up its credits Explorer's limits for 7 days, once per person, with the same key and no payment details. ## OpenAPI ````yaml POST /v1/billing/trial openapi: 3.1.0 info: title: Ironflow API version: 1.0.0 description: > Hyperliquid market data from Ironflow's own nodes: tick-level fills and trades, candles, funding rates, liquidations, mark prices, open interest, markets and wallet analytics over REST, live Server-Sent Events streams and read-only SQL. One schema across native HL perps, HIP-3 builder markets, HIP-4 outcome contracts and HL spot. The same data is a hosted MCP server for AI agents at `https://mcp.ironflow.sh/mcp`, and agents with a USDC wallet on Base can pay per call with x402, no key: the data GET endpoints are also served at `/x402/v1/...` (discovery: `https://api.ironflow.sh/openapi.json` and `https://api.ironflow.sh/.well-known/x402`). **Base URL:** `https://api.ironflow.sh` **Authentication:** Read endpoints work without a key (keyless access) or with a Bearer token in the `Authorization` header. Writes always need a key. ``` Authorization: Bearer if_your_api_key ``` Get a free key at https://ironflow.sh/key. **Access levels:** | Access | Requests per minute | Credits | History | Max range per request | |---|---|---|---|---| | No key | 30 per IP | 100 a day per IP (300 per app) | 24 hours | 1 hour | | Free key | 60 | 1,000 a day, 3,000 a month | 14 days | 6 hours | | Explorer | 100 | 25,000 a day | 90 days | 24 hours | | Builder | 1,000 | 250,000 a day | 1 year | 7 days | | Enterprise | 10,000 | no cap | everything stored | unlimited | No key, free keys, Explorer and calls paid with x402 are for personal and non-commercial use; Builder and Enterprise include commercial use (Terms 15.2, https://ironflow.sh/terms). **Credits:** every call costs credits by what it does. A read (trades, fills, liquidations, candles, funding, open interest, prices, markets) costs 1, analytics (the liquidation map, summary and heatmap, positions at a past time, wallet analytics, top traders, open interest changes, the hourly market panel) 5, SQL (`/v1/query`, also as `/v1/run_query` and `/v1/sql`, and the export) 10, and a live stream 1 to open and 1 a minute while it is open. Status, getting a key, plans and payment and the SQL schema cost nothing, and so does a call paid with x402. Any other endpoint costs 1. The full table: https://docs.ironflow.sh/concepts/rate-limits#credits Without a market filter, high-volume endpoints allow at most 4 hours per request. `/v1/trades` filtered to one perp or spot market allows 24 hours per request without a key and on a free key. Each caller can also read a set number of rows per hour: 2 billion without a key, 10 billion on a free key, 100 billion on Explorer, 500 billion on Builder, none set on Enterprise. REST and SQL count separately. Over it, REST answers 429 `READ_BUDGET_EXCEEDED` until the next hour. A header that is present but malformed returns 401; keyless access applies only when no `Authorization` header is sent. The keyless 100 credits a day are a rolling 24 hours per IP: past them, `KEYLESS_DAILY_LIMIT` (429, or 402 with x402 payment terms) carries a `Retry-After` of the seconds until the next call fits, and its `upgrade` object has `resets_at`, the early-customer Builder offer and, for a stream open (a stream open all day needs about 1,460 credits a day), Explorer next to the free key. An app that names itself in its `User-Agent` (not an HTTP library, a browser or curl) also shares 300 keyless credits per rolling 24 hours across all its IPs, with the same error past them; a free key lifts both. Through the hosted MCP server, each claude.ai conversation gets 30 keyless credits per rolling 24 hours of its own instead of the per-IP ones, up to 3,000 for all claude.ai conversations together. A key's credits count per account across all its keys over the UTC day, and on a free key also over the UTC month (free keys from one address share one free quota). Keyed responses carry `X-Credits-Cost` (this call), `X-Credits-Daily-Limit`, `X-Credits-Daily-Remaining` and `X-Credits-Daily-Reset` (the next 00:00 UTC in Unix seconds), on a free key also `X-Credits-Monthly-Limit`, `X-Credits-Monthly-Remaining` and `X-Credits-Monthly-Reset` (the 1st at 00:00 UTC); `X-RateLimit-Daily-Limit`, `X-RateLimit-Daily-Remaining` and `X-RateLimit-Daily-Reset` repeat the daily values. List answers and SQL results repeat them in a `credits` object. From 80% a notice says so. A call that does not fit in what is left gets `429 DAILY_QUOTA_EXCEEDED` (back at 00:00 UTC), or on a free key past the month `429 MONTHLY_QUOTA_EXCEEDED` (back on the 1st at 00:00 UTC), with an `upgrade` object: Explorer for a free key, Builder for Explorer, `resets_at`, and below Builder the early-customer Builder offer (`early_offer`). A free key whose account never had a trial gets `upgrade.trial` first: 7 days of Explorer with the same key (`POST /v1/billing/trial`); a key on a running trial is pointed at keeping Explorer after it. Their `Retry-After` starts at 60 seconds and doubles with each refusal in a row, up to the reset, so a key that is upgraded resumes within minutes; after 100 refusals in an hour it is the whole wait. Opening a stream past 10 opens a minute from one IP gets `429 STREAM_OPEN_LIMIT` before any credits are charged. Calls paid with x402 cost no credits and keep working. **Data availability:** fills and trades start on 25 May 2025; other datasets start later (funding 2025-09-27, open interest and mark prices 2026-04-29). Bulk history is free to download from https://huggingface.co/ironflow. **Timestamps:** All timestamps are Unix milliseconds (int64). **Pagination:** Paginated endpoints return a `cursor` in `pagination.next_cursor`. Pass it as the `cursor` query parameter to fetch the next page. When `pagination.has_more` is `false`, you have reached the last page. **Notices:** a successful JSON object may start with `notice`, the `X-Ironflow-Notice` header in the body: what was served when it differs from what was asked (a keyless sample, a shortened history, a guessed path) and how to get the rest. **Guessed paths:** a few paths callers guess are answered by the endpoint they mean, with a `notice` and the `X-Ironflow-Canonical` header naming it: `/v1/liquidations/aggregate`, `/v1/summary/liquidations` and similar by `/v1/liquidations/summary`, `/v1/liquidations/buckets` and `heatmap` by `/v1/analytics/liquidation-levels`, `/v1/liquidations/map/BTC-PERP` and `/v1/liquidation-map/BTC-PERP` by `/v1/liquidations/map?market=BTC-PERP`, and `/v1/trades/BTC-PERP` by `/v1/trades?market=BTC-PERP`. A path with trailing `.`, `,`, `;` or `)` (`/v1/query.`, copied from a sentence) is answered by the endpoint without them, with the same method, query and body. Any other path with no endpoint answers `404 NOT_FOUND` naming up to three endpoints closest to it, also as `nearest_routes`. OpenAI-style paths (`/v1/models`, `/v1/chat/completions`) answer 404: this is not an LLM API, and agents use the MCP server above. contact: name: Ironflow Support url: https://ironflow.sh servers: - url: https://api.ironflow.sh description: Production security: - bearerAuth: [] - {} tags: - name: Hyperliquid RPC description: Your API key as a Hyperliquid /info URL, on your plan's limits. - name: Market Data description: Historical tick-level market data stored in ClickHouse. - name: Analytics description: >- Aggregated analytics. Net flows, funding stats and the liquidation map markets work without a key; liquidation levels, the liquidation map and the vault leaderboard return a sample without one; order flow needs a key (a free key works). - name: Cohorts description: Predefined and custom address groups for filtering market data. - name: Alerts description: >- Liquidation alerts that Ironflow posts to your webhook, Discord channel, Slack channel or Telegram chat. - name: Ironbox description: >- Secure, sandboxed environments in Tokyo, next to Hyperliquid, where a trading agent runs with Ironflow's data, analytics, alerts and execution. Any API key, free included. - name: Query description: >- Read-only ClickHouse SQL over curated Hyperliquid tables (hl.*), limited by tier. - name: Billing description: >- Paid plans, paid in USDC on Base or Hyperliquid, or with x402 on Base. No card, no account page. - name: System description: Health checks and metadata endpoints. - name: TradingApp description: >- The trading terminal's own endpoints (terminal.ironflow.sh), wallet-session auth. Not part of the public data API; left out of the docs copy. paths: /v1/billing/trial: post: tags: - Billing summary: Start the 7-day Explorer trial description: > Starts the key's account on Explorer's limits for 7 days: 25,000 credits a day and no monthly cap, on every key of the account, at once. No payment details. While it runs, every answer to the key carries `X-Ironflow-Trial-Ends` (when it ends) and `X-Ironflow-Trial-Pay` (where to pay to keep the plan). We email you 2 days before the end and at the end; after it the account is back on the free limits by itself. Paying for a plan during or after the trial works as usual (POST /v1/billing/upgrade): the plan runs 30 days from the payment. For free accounts that used up their daily or monthly credits in the last 30 days, once per person. GET /v1/billing/trial says whether this key's account may start it. operationId: startTrial responses: '201': description: The trial started. headers: X-Ironflow-Trial-Ends: $ref: '#/components/headers/TrialEnds' X-Ironflow-Trial-Pay: $ref: '#/components/headers/TrialPay' content: application/json: schema: $ref: '#/components/schemas/TrialStatus' example: eligible: false plan: explorer days: 7 credits_per_day: 25000 price_usdc: 49 pay_url: >- https://ironflow.sh/upgrade?plan=explorer&utm_source=api&utm_medium=trial trial: status: running started_at: '2026-11-15T14:21:00Z' ends_at: '2026-11-22T14:21:00Z' message: >- Your key has Explorer limits until 22 November 2026 14:21 UTC: 25,000 credits a day and no monthly cap. After that it goes back to the free limits, unless you pay: Explorer is 49 USDC for 30 days at https://ironflow.sh/upgrade?plan=explorer&utm_source=api&utm_medium=trial. We email you 2 days before the end. '401': $ref: '#/components/responses/Unauthorized' '403': description: >- Not eligible (`TRIAL_NOT_FREE`, `TRIAL_PAID_BEFORE`, `TRIAL_NO_CAP`, `TRIAL_NOT_ELIGIBLE`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: TRIAL_NO_CAP message: >- the trial is for free accounts that used up their credits: this account has not hit its daily (1,000) or monthly (3,000) credits in the last 30 days '409': description: The trial runs now (`TRIAL_ACTIVE`) or was used (`TRIAL_USED`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: TRIAL_USED message: >- there is one trial per person, and this account (or its email) had it; Explorer is 49 USDC for 30 days at https://ironflow.sh/upgrade?plan=explorer&utm_source=api&utm_medium=trial '429': description: >- A trial was started from this network in the last 30 days (`TRIAL_LIMIT`, with `Retry-After`), or the rate limit. headers: Retry-After: schema: type: integer description: Seconds until a trial from this network is possible content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: headers: TrialEnds: description: >- On every answer to a key on a running Explorer trial; when it ends (RFC 3339). After it the key is back on the free limits unless a plan is paid. schema: type: string format: date-time example: '2026-11-22T14:21:00Z' TrialPay: description: >- On every answer to a key on a running Explorer trial; the link that keeps the plan after it. schema: type: string format: uri example: >- https://ironflow.sh/upgrade?plan=explorer&utm_source=api&utm_medium=trial schemas: TrialStatus: type: object required: - eligible - plan - days - credits_per_day - price_usdc - pay_url - trial properties: eligible: type: boolean description: Whether this key's account may start the trial now code: type: string enum: - TRIAL_ACTIVE - TRIAL_USED - TRIAL_NOT_FREE - TRIAL_PAID_BEFORE - TRIAL_NO_CAP - TRIAL_LIMIT - TRIAL_NOT_ELIGIBLE description: Why not when eligible is false: null reason: type: string description: The same in plain words plan: type: string example: explorer description: The plan whose limits the trial gives days: type: integer example: 7 credits_per_day: type: integer example: 25000 price_usdc: type: number example: 49 description: What the plan costs per 30 days after the trial pay_url: type: string format: uri description: Where to pay for the plan start: type: string description: The call that starts the trial present when eligible: null trial: type: - object - 'null' description: The account's trial; null when it never had one. required: - status - started_at - ends_at properties: status: type: string enum: - running - ended - converted started_at: type: string format: date-time ends_at: type: string format: date-time converted_plan: type: string description: The plan paid after the trial started when status is converted: null message: type: string description: Present on POST what the trial gives and what happens after it: null Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Machine-readable error code. example: RATE_LIMIT_EXCEEDED message: type: string description: Human-readable error description. example: Rate limit exceeded. Retry after 60 seconds. upgrade: type: object description: >- On a limit a higher plan lifts, the next plan, its price, what it lifts and the call that gets it. properties: trial: type: object description: >- On `DAILY_QUOTA_EXCEEDED` and `MONTHLY_QUOTA_EXCEEDED` for a free key whose account never had a trial, the first option: 7 days of Explorer with the same key and no payment, started with `start`. The plan below is the paid option. A key on a running trial gets no `trial`; its `url` keeps Explorer after the trial. properties: plan: type: string example: explorer days: type: integer example: 7 credits_per_day: type: integer example: 25000 start: type: string example: POST https://api.ironflow.sh/v1/billing/trial message: type: string plan: type: string example: explorer price_usdc: type: number example: 49 days: type: integer example: 30 unlocks: type: string description: >- What the plan adds, starting with SQL export to Parquet or CSV limit: type: string description: >- The limit this error hit: rate, history, window, sql_budget, read_budget, streams, alerts, keyless_day or tier example: rate lifts: type: string description: What the plan changes about that limit example: 60 requests a minute now, 100 on Explorer url: type: string format: uri description: Where to upgrade; the link carries the plan and the limit how: type: string description: The API call that opens the upgrade request buy_url: type: string format: uri description: Buy this plan in one x402 call (USDC on Base) when x402 is on: null pay_per_call: type: object description: On limits one paid call lifts how to pay for this call with x402: null resets_at: type: string format: date-time description: >- On `DAILY_QUOTA_EXCEEDED`, `MONTHLY_QUOTA_EXCEEDED` and `KEYLESS_DAILY_LIMIT`, when the refused credits come back: the next 00:00 UTC, the 1st of the next month at 00:00 UTC, or for a keyless caller the moment its rolling 24 hours fit the call. example: '2026-12-01T00:00:00Z' early_offer: type: object description: >- On the same credit refusals below Builder, Builder at the early-customer price for an account's first payments, while places last. properties: plan: type: string example: builder-early price_usdc: type: number example: 49 days: type: integer example: 30 payments: type: integer description: Payments at this price then_price_usdc after them: null example: 3 then_price_usdc: type: number example: 149 unlocks: type: string url: type: string format: uri example: >- https://ironflow.sh/upgrade?utm_source=api&plan=builder-early&limit=monthly_quota how: type: string description: The API call that opens the upgrade request get_key: type: object description: >- On every keyless 429 (daily cap, per-minute rate, SQL and read budgets, stream cap) and keyless history refusal, the one call that gets a free key. `page` is the key page tagged with the refusal (utm_campaign). properties: method: type: string example: POST url: type: string format: uri example: https://api.ironflow.sh/v1/keys body: type: object additionalProperties: type: string example: email: you@example.com page: type: string format: uri dataset: type: object description: >- On `HISTORY_OUT_OF_RANGE`, and on a rate limit for a closed past range, the free download that holds the requested rows, when one does. The message repeats it with its dates. properties: name: type: string example: Hyperliquid Liquidations url: type: string format: uri example: >- https://huggingface.co/datasets/ironflow/hyperliquid-liquidations?utm_source=api holds: type: string example: every liquidation from: type: string format: date example: '2025-05-25' through: type: string format: date example: '2026-10-31' ironbox: type: object description: >- On a rate limit, the keyless credits, the daily and monthly credits, the stream limit, the SQL budget and the read budget, how to run the agent in an Ironbox instead. properties: why: type: string example: >- No rate limits inside an Ironbox: your agent runs next to Hyperliquid with the data on the box. create: type: string example: POST https://api.ironflow.sh/v1/ironbox url: type: string format: uri example: https://ironflow.sh/ironbox?utm_source=api stream: type: string description: >- On the keyless daily credits, a per-minute rate limit, the read budget and a keyless history refusal of `/v1/liquidations` and `/v1/trades`, the live stream that replaces polling. example: >- GET https://api.ironflow.sh/v1/liquidations/stream (1 credit a minute) allowed_from: type: integer format: int64 description: >- On `HISTORY_OUT_OF_RANGE`, the earliest `from` (Unix ms; `at` on `/v1/positions`) the caller's history reaches; a request from there is served. example: 1794394800000 did_you_mean: type: array items: type: string description: >- On an unknown market (the liquidation map, the order book), the markets the name most likely meant. The message repeats them. example: - xyz:GOLD-PERP - PAXG-PERP detail: type: string description: >- More context when there is some. On a credit refusal, what calls cost and how the `Retry-After` grows. nearest_routes: type: array items: type: string description: >- On `NOT_FOUND` for a path with no endpoint, up to 3 endpoints closest to it. The message repeats them. example: - /v1/liquidations - /v1/liquidations/summary responses: Unauthorized: description: Missing or invalid API key. headers: WWW-Authenticate: schema: type: string example: Bearer content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Invalid or missing API key securitySchemes: bearerAuth: type: http scheme: bearer description: >- Ironflow API key, format `if_xxxx`. Free keys at https://ironflow.sh/key. Optional on read endpoints. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.