> ## 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.

# Ironbox: run a trading agent next to Hyperliquid

> Create a secure, sandboxed Ironbox in Tokyo for your Hyperliquid trading agent from code: get a key, create a box, poll it, delete it. curl and Python.

An Ironbox is a secure, sandboxed environment in Tokyo, next to Hyperliquid, where your trading agent runs with Ironflow's API, data, analytics, alerts and execution on the box. Perps, prediction markets and spot.

## 1. Get a key

Any key works, a free one included. From code:

```bash theme={null}
curl -X POST https://api.ironflow.sh/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'
```

The key arrives by email. Or get one at [ironflow.sh/key](https://ironflow.sh/key).

## 2. Create an Ironbox

```bash curl theme={null}
curl -X POST https://api.ironflow.sh/v1/ironbox \
  -H "Authorization: Bearer if_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "grid-bot", "mode": "paper", "runtime": "python", "markets": ["perps"]}'
```

```python Python theme={null}
import requests

API = "https://api.ironflow.sh/v1/ironbox"
HEADERS = {"Authorization": "Bearer if_your_key"}

box = requests.post(API, headers=HEADERS, json={
    "name": "grid-bot",
    "mode": "paper",
    "runtime": "python",
    "markets": ["perps"],
}).json()
print(box["id"], box["state"])
```

```json theme={null}
{
  "id": "ibx_3f9a0c7e12d4",
  "name": "grid-bot",
  "state": "creating",
  "size": "small",
  "mode": "paper",
  "runtime": "python",
  "markets": ["perps"],
  "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."
}
```

Every field is optional:

| Field | Values | Default |
| - | - | - |
| `name` | Up to 64 characters | none |
| `size` | `small`, `medium`, `large` | `small` |
| `mode` | `paper`, `live` | `paper` |
| `runtime` | `python`, `node` | `python` |
| `markets` | Any of `perps`, `outcomes`, `spot` | `["perps"]` |
| `note` | Up to 500 characters: your strategy, markets, volume | none |

A key can have 3 Ironboxes at a time.

## 3. Poll its state

```bash curl theme={null}
curl https://api.ironflow.sh/v1/ironbox/ibx_3f9a0c7e12d4 \
  -H "Authorization: Bearer if_your_key"
```

```python Python theme={null}
import time

while box["state"] == "creating":
    time.sleep(30)
    box = requests.get(box["url"], headers=HEADERS).json()
print(box["state"], box["message"])
```

States: `creating`, `running`, `stopped`, `deleted`, `error`. We email you when the box is ready. `GET /v1/ironbox` lists your boxes, newest first.

## 4. Delete it

```bash curl theme={null}
curl -X DELETE https://api.ironflow.sh/v1/ironbox/ibx_3f9a0c7e12d4 \
  -H "Authorization: Bearer if_your_key"
```

```python Python theme={null}
requests.delete(box["url"], headers=HEADERS)
```

The answer is the box in state `deleted`.

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | `INVALID_PARAMETER` | A value is not allowed; the message names the allowed ones |
| 401 | `UNAUTHORIZED`, `KEY_REQUIRED` | No key; the message says how to get a free one |
| 404 | `NOT_FOUND` | No Ironbox with that id on this key |
| 429 | `IRONBOX_LIMIT` | The key has 3 Ironboxes; delete one first |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.