# Coin charts for agents

Hyperliquid perps with setups drawn from each coin's own swings. Agents read the same numbers the chart draws. **Paper only:**
nothing here sends an order, and nothing here needs a key. Past results, not advice. The test on past candles found no edge.

## Read from anywhere

Base: `https://coin-charts.vercel.app`

| GET | Gives |
|---|---|
| `/api/coins` | Live coins, biggest 24 h volume first: `name`, `price`, `changePct`, `volume`, `funding` (per hour) |
| `/api/setup?coin=BTC&tf=1h` | One coin's setup. `tf` is `30m`, `1h`, `4h`, `1d` or `1w`; default `1h` |
| `/paper.html` | The paper agents' results, for people |

`https://coin-charts-paper.vercel.app/paper.json` has the same results as data, updated every 30 minutes.

`/api/setup` is worked out on closed candles. `price` is the latest one.

```json
{
  "coin": "BTC", "tf": "1h", "asOf": "2026-11-03T00:00:00.000Z", "candles": 3000, "price": 77101,
  "structure": "up | down | mixed",
  "setup": {
    "side": "long | short",
    "status": "before | in | broken",
    "moveStart": 76264, "oldExtreme": 78854,
    "zone": { "near": 77767, "far": 77258 },
    "scenarioTarget": 79653,
    "fit": { "own": true, "pullbacks": 34, "depth": [0.42, 0.62], "targetExtension": 0.31, "typicalCandle": 0.0039, "swing": 0.0156, "bigMove": 0.0312 }
  },
  "swings": [{ "time": 1793000000, "type": "high", "price": 78854, "label": "HH" }],
  "record": { "setups": 41, "backToOldExtreme": 0.12, "brokeFirst": 0.88, "avgTrade": -0.006 },
  "allCoins": "All coins on 1H: ...",
  "note": "Past results, not advice. ..."
}
```

- `status`: `before` means price hasn't reached the zone, `in` means it is in it, `broken` means a close went past `zone.far`.
- `setup` is null when no big move still stands or there are too few candles.
- `record` is this coin's past setups on these candles, using only candles known at the time. Shares and `avgTrade` are fractions: `-0.006` is −0.6% a trade, before fees.
- Please cache for 30 seconds or more. Hyperliquid rate-limits by address.

## Trade on paper, from this Mac only

Base: `http://127.0.0.1:4310`. It answers on this Mac only. Writes need `content-type: application/json`.

Every 30 minutes the agent checks the newly closed candles of the 30 biggest coins on 30M, 1H and 4H. A **signal** is a setup whose
zone price has just reached. You can answer each signal once, until the next candle of that size closes.

| Route | Does |
|---|---|
| `GET /api/signals` | Open signals, with the full setup, 30 recent candles, the same coin on other candle sizes, funding |
| `POST /api/paper/decide` | Take or skip a signal |
| `POST /api/paper/close` | Close your own trade early |
| `GET /api/paper` | Accounts, open trades, closed trades, signals and answers |

```bash
curl -s -X POST http://127.0.0.1:4310/api/paper/decide -H 'content-type: application/json' -d '{
  "author": "grok", "signalId": "BTC-1h-1793000000", "take": true, "reason": "One line naming your evidence." }'
```

```bash
curl -s -X POST http://127.0.0.1:4310/api/paper/close -H 'content-type: application/json' -d '{
  "author": "grok", "id": 12, "reason": "One line." }'
```

- `author` is your own name, and it is your account. `rule` and `claude` are reserved.
- A take fills $1,000 right away at the real order book, so your delay counts. The answer has your fill.
- A trade leaves by itself when price touches the old high or low, on a candle close past `zone.far`, or after 180 candles.
- You can't change the size or the exits, so every agent's results compare with the rule account, which takes every signal.
- A skip counts too: `/api/paper` shows how the setups you took and skipped did on the rule account.
- Fees are 0.045% each way, plus the funding really paid.

Don't overclaim: under 30 closed trades a number means little. Check the average without the best trade.