> ## 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. # Create an Ironbox > POST /v1/ironbox creates a secure, sandboxed environment in Tokyo, next to Hyperliquid, for your trading agent. See the [Ironbox guide](https://docs.ironflow.sh/guides/ironbox.md) for the full flow in curl and Python. ## OpenAPI ````yaml POST /v1/ironbox 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 | History | Max range per request | |---|---|---|---| | No key | 30 per IP (2,000 a day) | 24 hours | 1 hour | | Free key | 60 | 30 days | 6 hours | | Explorer | 100 | 90 days | 24 hours | | Builder | 1,000 | 1 year | 7 days | | Enterprise | 10,000 | full | unlimited | 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. A header that is present but malformed returns 401; keyless access applies only when no `Authorization` header is sent. **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`, and `/v1/liquidations/map/BTC-PERP` by `/v1/liquidations/map?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. 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: 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 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/ironbox: post: tags: - Ironbox summary: Create an Ironbox description: | Spins up a secure, sandboxed environment in Tokyo, next to Hyperliquid, for your trading agent, with Ironflow's API, data, analytics, alerts and execution on the box. Every field is optional. The box starts in state `creating`; poll its `url` for the state, and we email you when it is ready. Any API key works, a free one included (no key: `POST /v1/keys` with `{"email": ...}` sends one). A key can have 3 Ironboxes that are not deleted. operationId: createIronbox requestBody: required: false content: application/json: schema: type: object properties: name: type: string maxLength: 64 description: Your name for the box. example: grid-bot size: type: string enum: - small - medium - large default: small mode: type: string enum: - paper - live default: paper description: '`paper` trades on paper, `live` on Hyperliquid.' runtime: type: string enum: - python - node default: python markets: type: array items: type: string enum: - perps - outcomes - spot default: - perps description: >- What the agent trades: perps (native and HIP-3), outcomes (HIP-4 prediction markets), spot. note: type: string maxLength: 500 description: 'Anything we should know: strategy, markets, volume.' example: name: grid-bot size: small mode: paper runtime: python markets: - perps - outcomes responses: '201': description: The Ironbox, in state `creating`. headers: Location: description: The box's `url`. schema: type: string format: uri content: application/json: schema: $ref: '#/components/schemas/Ironbox' '400': description: >- A field has a value that is not allowed (`INVALID_PARAMETER`, naming the allowed values) or the body is not JSON (`INVALID_BODY`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_PARAMETER message: size must be one of small, medium, large (got "xl") '401': $ref: '#/components/responses/IronboxKeyRequired' '429': description: >- The key already has 3 Ironboxes (`IRONBOX_LIMIT`; delete one first), or made too many creates this hour (`RATE_LIMITED`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: IRONBOX_LIMIT message: >- this key already has 3 Ironboxes, the most one key can have. Delete one first: DELETE https://api.ironflow.sh/v1/ironbox/{id} (GET https://api.ironflow.sh/v1/ironbox lists them) security: - bearerAuth: [] components: schemas: Ironbox: type: object required: - id - name - state - size - mode - runtime - markets - region - created_at - url - dashboard - message properties: id: type: string pattern: ^ibx_[0-9a-f]{12}$ example: ibx_3f9a0c7e12d4 name: type: string description: Empty when none was given. example: grid-bot state: type: string enum: - creating - running - stopped - deleted - error size: type: string enum: - small - medium - large mode: type: string enum: - paper - live runtime: type: string enum: - python - node markets: type: array items: type: string enum: - perps - outcomes - spot region: type: string enum: - tokyo created_at: type: integer format: int64 description: Unix milliseconds url: type: string format: uri description: GET it for the box's state; DELETE it to delete the box. dashboard: type: string format: uri message: type: string description: What the state means in one line.: null example: id: ibx_3f9a0c7e12d4 name: grid-bot state: creating size: small mode: paper runtime: python markets: - perps - outcomes region: tokyo created_at: 1762520000000 url: https://api.ironflow.sh/v1/ironbox/ibx_3f9a0c7e12d4 dashboard: https://ironflow.sh/ironbox message: Your Ironbox is being set up. We email you when it is ready. 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. ironbox: type: object description: >- On a rate limit, the keyless daily cap, the stream limit and the SQL time 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 limit of `/v1/liquidations` and `/v1/trades`, the live stream that replaces polling. example: >- GET https://api.ironflow.sh/v1/liquidations/stream (no daily limit for keyless streams) responses: IronboxKeyRequired: description: No API key. Any key works, a free one included. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: >- this request needs an API key. Free keys: https://ironflow.sh/key?utm_source=api, or POST https://api.ironflow.sh/v1/keys with {"email": "you@example.com"} (the key arrives by email) 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.