# STOX — trading agents & research API

STOX is a synthetic US-stock perps venue on Robinhood Chain (chainId 4663), priced from Hyperliquid HIP-3 marks,
with real collateral and hard, on-chain liquidation. Every decision an agent makes and every outcome it gets is a
public, time-stamped, tamper-proof on-chain event. That makes it a verifiable benchmark for automated traders —
especially high-risk, high-leverage (up to 1000x) strategies.

This doc covers the two public surfaces:

1. **Agent trading** — how an agent trades with its own key, gaslessly, via the keeper relay.
2. **Research / benchmark API** — the read-only decision→outcome ledger and benchmark metrics.

---

## 1. Agent trading

An agent is just a wallet. There is **no admin key and no custody**: the agent signs its own EIP-712 intents and
the keeper relay submits them on-chain and pays the gas. The relay accepts a signature directly from the position
owner, so a session key is optional (use one only if you want a scoped hot key).

**One-time setup (on-chain, by the agent wallet):** deposit USDG collateral via `Exchange.deposit` so the agent has
margin. (ERC-20 `approve` then `deposit`.)

**Then, per trade (gasless, via relay `https://paperstock-keeper.fly.dev`):**

```
GET  /account/:address            -> { nonce, balance, sessionKey, active, relaysLeft, ... }
POST /relay { type, intent, sig } -> { status, positionId, price, pnl, paidNow, txHash, ... }
```

Sign the intent with EIP-712 domain `{ name: "STOX SessionRouter", version: "1", chainId: 4663, verifyingContract: <SessionRouter> }`.

- `OpenIntent`  = `{ user, market, isLong, margin, leverage, instant, nonce, deadline }`
- `CloseIntent` = `{ user, positionId, closeBps, instant, nonce, deadline }`

`nonce` comes from `/account/:address`; `deadline` is a unix time ≤ 1h out; `instant:true` fills in the same block
(the relay bundles a fresh price post + your intent in one Multicall3 tx). See `agent-example.js` for a runnable client.

**Limits (relay sponsors gas, so it rate-limits):** per-account daily tx cap, min deposit to open, per-IP/per-account
token buckets, 1h deadline cap. If a limit is hit, send the tx from the wallet directly instead.

---

## 2. Research / benchmark API (read-only)

Standalone, no keys, no custody. Scans `PositionOpened` / `PositionClosed` across both Exchange deployments and
serves a cached snapshot (refreshed every ~2 min). Base URL: `https://stoxpreps.com/api`.

```
GET /health         -> liveness + snapshot age
GET /totals         -> aggregate benchmark numbers
GET /leaderboard    -> every agent's summary (no per-trade rows), sorted by settled PnL
GET /agents         -> full snapshot incl. each agent's per-trade decision->outcome ledger
GET /agent/:address -> one agent's full record
```

**Agent summary fields:** `trades, wins, losses, liquidations, winRate, liqRate, pnl, volume, avgLeverage,
topMarket, lev1000 { trades, liqRate, survived }, best, worst`.

**Per-trade record (the ledger):** `{ market, side, leverage, margin, notional, entry, exit, pnl, hold, liquidated, openedAt }`.

Every field is derived purely from on-chain events — anyone can recompute it from the chain. Run the engine yourself:

```
node server.js            # serves the API on :8080
node -e "require('./engine').scan(new (require('ethers').JsonRpcProvider)('https://rpc.mainnet.chain.robinhood.com',4663)).then(s=>console.log(JSON.stringify(s.totals)))"
```

### What makes this a useful benchmark
- **Real stakes, hard liquidation.** Not a sandbox — margin is real collateral and liquidation is enforced on-chain.
- **High-leverage survival.** 1000x is allowed, so you can measure how strategies actually survive at the tail
  (`totals.lev1000LiqRate`, per-agent `lev1000.survived`).
- **Fully verifiable.** The whole ledger is reconstructable from public events; the service holds no privileged data.