# Hyris: any AI model, paid in HYPE

You are an AI agent. Hyris gives you one OpenAI-compatible API for every major model, billed per call from a prepaid credit, plus live Hyperliquid market data. Read this once, then follow it.

## Connect

- Base URL: `https://<this site>/v1`
- Key: your owner gives you an **agent key** (`hyr_…`). Send it as `Authorization: Bearer hyr_…`.
- Your key carries limits set by your owner: a daily budget, a per-call cap, the models you may use, and a pause switch. You can't change them. Never ask for an owner key.
- MCP clients: `POST https://<this site>/mcp` with the same header. Tools: `ask_model`, `hl_price`, `hl_book`, `hl_candles`, `hl_spot_balances`, `hl_spot_tokens`, `get_balance`, `verify_receipt`.

## Call a model

```
POST /v1/chat/completions
{ "model": "hyris/auto", "messages": [{ "role": "user", "content": "…" }] }
```

- `hyris/auto` picks the cheapest model on Hyris's list that can do the request. Or name a model from `GET /v1/models`.
- Add `"hyperliquid": true` (or end the model id with `:live`) when the question needs current Hyperliquid prices, order books, candles or balances. Each data read costs a small fixed fee.
- Set `max_tokens` to what you need: the call is checked against your per-call cap before it runs.
- The response's `usage.cost_usd` is what the call cost. `hyris_receipt` is a signed receipt of the answer.

## Be a good agent

1. Check `GET /v1/account` before a long task: `this_key` shows your budget left today.
2. Use `hyris/auto` unless the task needs a specific model.
3. Don't repeat the same request in a loop: after a few identical calls in two minutes, your key is paused for ten minutes.
4. When you give an answer that depends on live data, keep the `hyris_receipt`. Anyone can check it at `POST /v1/receipts/verify`: it proves which model answered, with which data, and when.

## Errors

| Code | Meaning | What to do |
|---|---|---|
| 401 | Unknown or revoked key | Stop and tell your owner |
| 402 | Credit too low | Tell your owner to deposit HYPE |
| 403 | Over your per-call cap or daily budget, model not allowed, or paused | Lower `max_tokens`, switch model, or wait for tomorrow's budget |
| 429 | Too many requests, or a loop was detected | Wait, and change your approach |

## How the money works

Credit is prepaid HYPE, converted to dollars at the live price when it lands. It's spent call by call at the public price list (provider price plus a small fixed margin). It earns no yield, isn't lent out, and carries no leverage.