> ## 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. # Explorer trial status > GET /v1/billing/trial says whether a key's account may start its 7-day Explorer trial, why not, and when a running trial ends. ## OpenAPI ````yaml GET /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: get: tags: - Billing summary: Explorer trial status and eligibility description: > Whether the key's account may start its 7-day Explorer trial, and why not when it may not, with the trial it had (if any). Free accounts that have used up their daily or monthly credits in the last 30 days may try Explorer once: 25,000 credits a day, no monthly cap, the same key. One trial per person (per email inbox, and at most one per network in 30 days); accounts that paid before do not get one. Costs no credits. `eligible: true` comes with `start`, the call that starts it. Otherwise `code` and `reason` say why: `TRIAL_ACTIVE` (it runs now), `TRIAL_USED`, `TRIAL_NOT_FREE`, `TRIAL_PAID_BEFORE`, `TRIAL_NO_CAP` (the account has not hit a credit cap), `TRIAL_LIMIT` (a trial was started from this network in the last 30 days) or `TRIAL_NOT_ELIGIBLE`. operationId: getTrial responses: '200': description: The account's trial standing. content: application/json: schema: $ref: '#/components/schemas/TrialStatus' example: eligible: true 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 start: POST https://api.ironflow.sh/v1/billing/trial trial: null '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimited' security: - bearerAuth: [] components: 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 RateLimited: description: >- Rate limit exceeded: `RATE_LIMIT_EXCEEDED` (per minute), `KEYLESS_DAILY_LIMIT` (keyless credits per IP or per app), `DAILY_QUOTA_EXCEEDED` (the call does not fit in the account's credits left for the UTC day; `Retry-After` runs to 00:00 UTC) or `MONTHLY_QUOTA_EXCEEDED` (a free key's credits for the UTC month; `Retry-After` runs to the 1st at 00:00 UTC). On the credit refusals `upgrade` names the plan: Explorer for a free key, Builder for Explorer. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer example: 60 X-Credits-Cost: description: What the refused call would cost in credits. schema: type: integer example: 10 X-Credits-Daily-Remaining: description: The credits left today (keyless, over the rolling 24 hours). schema: type: integer example: 5 content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Retry after 60 seconds. 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.