> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hizz.io/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Trading API

> Use Hizz trading modules and published strategies from Codex, agents, scripts, or any HTTP client.

The public AI Trading API gives external agents a stable, machine-readable
interface to Hizz's deterministic strategy layer. Codex and other AI systems
can discover approved modules, read published manifests, validate a new JSON
composition, and run bounded historical backtests.

If you are starting from an idea rather than an existing manifest, follow
[Write your own strategy](/ai-trading/write-a-strategy) and copy one of the
inline [strategy examples](/ai-trading/strategy-examples) before working
through the endpoint reference below.

```text theme={null}
Base URL: https://hizz.io/api/v1/ai-trading
OpenAPI:  https://hizz.io/api/v1/ai-trading/openapi.json
```

<Info>
  Public v1 is read-only or simulation-only. Saving a private strategy,
  deploying an agent, arming live execution, and placing orders still require
  a Hizz login or signed wallet session. API input never accepts executable
  JavaScript, Python, or arbitrary server code.
</Info>

## Endpoints

| Method | Endpoint                                        | Purpose                                                 | Authentication       |
| ------ | ----------------------------------------------- | ------------------------------------------------------- | -------------------- |
| `GET`  | `/api/v1/ai-trading`                            | Capability and link discovery                           | Public               |
| `GET`  | `/api/v1/ai-trading/modules`                    | Approved blocks, ports, parameter schemas, and examples | Public               |
| `GET`  | `/api/v1/ai-trading/strategy-template`          | Canonical runnable JSON template                        | Public               |
| `GET`  | `/api/v1/ai-trading/strategies`                 | Published strategy summaries                            | Public               |
| `GET`  | `/api/v1/ai-trading/strategies/{slug}`          | Full manifest and compiled node graph                   | Public               |
| `POST` | `/api/v1/ai-trading/strategies/validate`        | Normalize, validate, and graph declarative JSON         | Public               |
| `POST` | `/api/v1/ai-trading/strategies/{slug}/backtest` | Run a bounded historical simulation                     | Public, rate limited |

All public routes return CORS headers, JSON, and an `X-Hizz-API-Version`
response header. Backtests are limited to eight requests per minute per warm
service instance and accept no more than 2,000 days per request.

## Call it from Codex

Give Codex the OpenAPI URL and an explicit safety scope:

```text theme={null}
Read https://hizz.io/api/v1/ai-trading/openapi.json.
List directional strategies, inspect zec-4h-breakout-maker, and run a
180-day 4h backtest with $10,000 capital. Do not deploy or place live orders.
Summarize the configured risk/reward, realized payoff, fees, and drawdown.
```

Codex can also call the REST endpoints directly:

```bash theme={null}
curl https://hizz.io/api/v1/ai-trading/modules?category=risk

curl https://hizz.io/api/v1/ai-trading/strategies/zec-4h-breakout-maker

curl -X POST \
  https://hizz.io/api/v1/ai-trading/strategies/zec-4h-breakout-maker/backtest \
  -H "Content-Type: application/json" \
  -d '{"capital":10000,"lookbackDays":180,"interval":"4h"}'
```

## Validate a composition

Start with the [strategy template](/ai-trading/strategy-template), edit its
approved blocks, then post the complete object:

```bash theme={null}
curl -X POST https://hizz.io/api/v1/ai-trading/strategies/validate \
  -H "Content-Type: application/json" \
  --data-binary @strategy.json
```

A successful response returns the normalized strategy plus the same serializable
`graph` model used by the Hizz node workbench. Nodes include canonical typed
input/output ports, descriptions, parameters, and parameter help. Edges include
`sourcePort`, `targetPort`, and `dataType`; the compiler rejects incompatible
cables. A rejected response uses HTTP `422` and returns an `issues` array.
Unknown module kinds are never silently compiled.

## Backtest options

| Field                      | Type    | Bounds                                          | Notes                                                                |
| -------------------------- | ------- | ----------------------------------------------- | -------------------------------------------------------------------- |
| `capital`                  | number  | 100–1,000,000                                   | Defaults to 10,000                                                   |
| `lookbackDays`             | integer | 7–2,000                                         | Historical window                                                    |
| `interval`                 | string  | Supported provider interval                     | Example: `1h`, `4h`, `1d`                                            |
| `leverage`                 | number  | 1–125                                           | Simulation override                                                  |
| `feeBps`                   | number  | 0–100                                           | Uniform stress override; omit to preserve strategy maker/taker costs |
| `allowLong` / `allowShort` | boolean | —                                               | At least one side must remain enabled                                |
| `dataSource`               | string  | `default`, `pyth`, `binance`, `strike`, `yahoo` | Coverage is validated before execution                               |
| `from` / `to`              | date    | `YYYY-MM-DD`                                    | Must be supplied together                                            |
| `symbol`                   | string  | `BASE-USD`                                      | Only supported market/provider combinations run                      |

Backtest `nav` is a mark-to-market equity series recorded on each processed
market bar. While a position is open it includes unrealized profit or loss and
already-paid entry costs; the final point includes closing costs. Chart clients
should preserve local highs and lows when downsampling instead of keeping only
every Nth point.

<Warning>
  Historical results are simulations. They do not guarantee matching fills,
  liquidity, latency, funding, slippage, or future returns.
</Warning>

## Live execution boundary

The browser application already exposes authenticated strategy-save and agent
deployment routes, but those routes intentionally rely on a signed Hizz session
and are not part of anonymous v1. This prevents an AI holding only a public URL
from moving funds. A human must review the compiled definition, authenticate,
deploy, and arm live execution inside Hizz.