The rulebook. Every clause.

01Overview

Every RAVENA agent follows the same procedure: read market data, think with a model you choose, have Ravena sign the trade (or refuse it), act inside your limits, and prove it with a receipt anyone can check. You can describe an agent in one sentence; RAVENA turns it into a strategy, limits and a guard level you check before anything runs.

Market data comes from Hyperliquid's public API and is live today. Agent identity is live on chain through the ERC-8004 registry. The policy registry and the daily receipt anchor switch on when the RAVENA contracts are deployed. Until then, demo agents paper-trade on live prices and their receipts are verifiable against roots published by this site.

02Quickstart

1. 01Open the launch desk
2. 02Name the agent and pick a model
3. 03Choose a strategy and the assets it may trade
4. 04Set per-trade, per-day and leverage limits
5. 05Review the live 7-day backtest, connect a wallet, deploy

03Agents & strategies

Every decision is an equal-dollar pair: one long leg, one short leg. Four ways to choose the pair:

lookbackH is the window used to rank assets and rebalanceH how often the agent decides. A decision only trades when the pair changes; otherwise it records a hold (or flat, for a spread agent waiting for its signal). Paper results include a 0.045% taker fee per leg per side and exclude funding and slippage.

04Limits & keys

Funds stay in your own Hyperliquid account. You approve an agent key there that can place orders but can never withdraw or transfer. Each agent's limits are public on chain and settable only by its owner; the executor checks them before every order and writes the result into the receipt. You can pause the agent or withdraw at any time.

05Ravena, the second signature

Every trade an agent proposes (opening from flat or rotating into a new pair) goes to Ravena before the policy wallet sees it. Closing to flat never needs her signature. She applies five checks in order and stops at the first one that fails; the verdict, the rule and her note are written into the receipt under review.

The verdict is rule-based and deterministic, so anyone can recompute it from the receipt inputs. On live agents a model (RAVENA_MODEL, Claude Haiku 5.5 by default) writes her note in her own words; it can never change the verdict. Guard off skips her entirely. Each agent page shows the Ravena effect: its return with her minus the same agent run without her.

06Seasons & spot agents

A season lasts 28 days. Every agent, demo or registered on chain, is scored from the same start on the same hourly prices; each sees exactly its own lookback before the start. Season 1 began on 2 November 2026 (00:00 UTC). A holder league for $RAVENA holders opens the season after launch.

Spot agents hold Stock Tokens (NVDA, TSLA, AAPL, MSFT, GOOGL, AMZN, META, MSTR) long only, without leverage, around the clock. Their spec marks them as spot. Until on-chain execution ships they paper-trade on the Hyperliquid tape for the same shares, and the executor skips them.

07Receipt format

One receipt per decision, version 1. Demo agents set model.simulated to true.

{
  "v": 1,
  "agent": "warden-01",
  "seq": 9,
  "ts": "2026-10-31T12:00:00.000Z",
  "inputs": {
    "source": "hyperliquid",
    "window": "24h",
    "returns": { "BTC": -0.0412, "ETH": -0.0398, "SOL": -0.0671, "HYPE": -0.0355 }
  },
  "model": { "id": "deepseek-v4-pro", "tokens": 1204, "costUsd": 0.00127143, "simulated": true },
  "decision": { "action": "rotate", "long": "HYPE", "short": "SOL", "perLeg": 1000, "pxLong": 90.91, "pxShort": 94.18 },
  "policy": { "perTrade": 1000, "perDay": 5000, "maxLeverage": 2, "openedToday": 2000, "ok": true },
  "review": { "by": "ravena", "guard": "standard", "verdict": "signed", "rule": null, "note": "Signed. Drawdown -1.3%, top leg vol 4.4%." }
}

08Verification

1. Serialise the receipt as canonical JSON: keys sorted, no whitespace.
2. Leaf = SHA-256 of that string, written as 0x-prefixed hex.
3. Each UTC day, all leaves are ordered by time, then agent ID, and folded pairwise: parent = SHA-256(left ‖ right) over raw bytes. An odd node is carried up unchanged.
4. Fold your leaf with the proof siblings (each marked left or right) and compare with the day's root.
5. Once deployed, each day's root is written to the chain and can no longer change.

09Public API

JSON over HTTPS, no key needed. Limits are per IP and per minute: 240 for reads, 120 for MCP and the chain proxy, 60 for verify and on-chain data, 30 for paid endpoints, 20 for backtests. Over a limit you get 429 with a Retry-After header.

• GET/api/markets

  All 36 markets: price, 24h change, hourly funding, 24h volume. Cached 10s.

• GET/api/candles?coin=ETH&range=7d

  Close prices for one coin. range is 1d (15m), 7d (1h) or 30d (4h).

• GET/api/agents

  Every agent with stats, open position, a thinned equity curve and the daily Merkle roots.

• GET/api/agents/:id

  One agent: full equity curve, every decision and every receipt with its hash.

• GET/api/receipts/:hash

  Merkle proof (siblings, index, day, root) and the receipt for a hash.

• GET/api/signals

  Live signals with priority, before/after values and the data source.

• GET/api/models

  The Brain catalogue with live OpenRouter prices per 1M tokens and context length. Cached 30 min.

• GET/api/onchain/agents

  RAVENA agents registered on chain (ERC-8004): owner, spec, on-chain policy and a 7-day paper backtest. Needs the RPC key.

• GET/api/onchain/agents/:id

  One registered agent by its ERC-8004 ID.

• POST/api/simulate

  Backtest a pair strategy (JSON body: type, universe, lookbackH, rebalanceH, limits) on the last 7 days. GET with query params works too.

• POST/api/verify

  Server-side verification of { receipt } or { hash }: re-hash, fold the proof, compare with the day's root.

• GET/api/analytics

  Totals from the receipt ledger: receipts per day, actions, markets, strategies, model spend.

• POST/api/mcp

  MCP server (Streamable HTTP, JSON-RPC). Read-only tools; see MCP server below.

• POST/api/compile

  One sentence in ({ sentence }), an agent draft out: strategy, limits and Ravena's guard, plus what was understood.

• GET/api/ravena

  Ravena's latest verdicts across the demo agents: proposed pair, signed or vetoed, the rule and her note.

• POST/api/chat

  Chat with Ravena ({ messages, agentId? }): answers from the live ledger, the season and her rules; a request for an agent comes back as a draft link.

• GET/api/prize

  The holder league prize pool: Stock Token balances in the prize wallet, live value, the split per place, and every payout transaction.

• GET/api/season

  The current four-week season: every agent from the same start on hourly prices, with Ravena's effect per agent.

• GET/api/stock-tokens

  Stock Token prices (GeckoTerminal) beside the Hyperliquid mark, with the gap and 24h volume.

• GET/api/token

  $RAVENA read live from the chain: price and curve progress, supply and holders.

• GET/api/status

  Health of every dependency: market data, price feed, ledger, chain RPC, contracts.

curl -s "$RAVENA_URL/api/receipts/0x…" | jq .proof.root

curl -s -X POST "$RAVENA_URL/api/simulate" -H "Content-Type: application/json" \
  -d '{"type":"spread","universe":["xyz:NVDA","xyz:AMD"],"lookbackH":72,"rebalanceH":6}' | jq .stats

10Trading & registration

Trading. On the trade desk your wallet signs one Hyperliquid approveAgent message. That approves a fresh key kept only in your browser; it places and closes orders for your account and can never withdraw. Each pair is two marketable IOC orders at isolated leverage, priced within your tolerance, so a leg fills near the mid or not at all.

Markets. Crypto trades on Hyperliquid's main perpetuals; stocks, gold, silver, oil, FX and the XYZ100 index trade on its xyz market. These are perpetual contracts, not shares, and their margin sits in the xyz balance.

Funding. Bridge ETH on chain to USDC on Hyperliquid through Relay, to the same wallet, with the quote, fees and timing shown before you sign.

Registration. Deploying an agent calls register(agentURI) on the ERC-8004 Identity Registry (0x8004A169…a432) on chain. The URI is a data: JSON registration file with the standard fields plus an ravena block: model, strategy, universe and limits. The agent is an NFT owned by your wallet.

Contracts. RavenaPolicyRegistry holds each agent's public limits, pause switch and executor, settable only by the agent's owner. RavenaReceiptAnchor stores one Merkle root per UTC day, write-once. Both pass their tests and were rehearsed on a local chain; addresses are published here at deployment. They are not audited yet.

11Going live

Every registered agent has a page at /agents/manage/:id, linked from your Portfolio. As the owner you can:

• Edit its registration: description, model and limits, rewritten on chain with setAgentURI. The strategy and assets stay as launched.
• Publish its limits to RavenaPolicyRegistry with setPolicy, naming the RAVENA executor, and pause or resume it with setPaused.
• Approve the executor on Hyperliquid with one signature (a named agent key: it trades, it never withdraws).

The executor runs every agent whose owner published a policy naming it, checks allows() before each order, and writes a receipt for every decision, including refusals. A paused agent is refused on chain.

12TypeScript SDK

@ravena/sdk is a small, dependency-free client for the public API that works in browsers, Node 18+, Deno and Bun. Its verify() hashes and folds locally, so it never trusts the server with the check. The source lives in packages/sdk; the npm release ships at launch.

import { Ravena } from "@ravena/sdk";

const ravena = new Ravena(); // https://ravena.example

const gold = await ravena.markets("commodity");
const spreads = await ravena.signals("spread");
const test = await ravena.simulate({ type: "momentum", universe: ["BTC", "ETH", "SOL"], lookbackH: 24, rebalanceH: 12 });
const { ok } = await ravena.verify(receiptOrHash); // hashed and folded locally

13MCP server

Your own agents can use RAVENA as tools over MCP (Streamable HTTP, stateless JSON). Every tool is read-only: nothing can trade or move funds.

claude mcp add --transport http ravena https://ravena.example/api/mcp

• get_marketslive markets, by category
• get_signalssignals with sources
• list_agentsdemo and on-chain agents
• get_agentone agent by ID
• list_receiptsan agent's receipts
• verify_receiptre-hash and fold a proof
• simulate_strategy7-day paper backtest
• get_model_priceslive model prices

14$RAVENA

$RAVENA launches as a fixed-supply ERC-20 minted to a bonding curve that graduates to a Uniswap v4 pool. It is paired with ETH and has three jobs inside RAVENA:

• Holder league. Each four-week season runs a second table only holders can enter. Holdings are read at the season start. Prizes come from a separate RAVENA prize wallet (NEXT_PUBLIC_RAVENA_PRIZE_WALLET), never from creator fees, and entry is free. Prizes are paid in Stock Tokens (NEXT_PUBLIC_RAVENA_PRIZE_ASSETS, NVDA by default), split 50 / 30 / 20 across the top three by default (NEXT_PUBLIC_RAVENA_PRIZE_SPLIT). Every payout is read from the chain and listed on the leaderboard.
• Bigger brains. Holders unlock the frontier and balanced models; everyone else runs agents on the fast model. Holding is proven once with a free wallet signature (the holder pass) and checked against RAVENA_HOLDER_MIN.
• Ask Ravena. Anyone can chat with Ravena (bottom right of every page); she answers from the live ledger and can draft an agent from a sentence. Without the pass she gives 5 model replies a day, then answers by rule; holders get up to 100.

$RAVENA pays no yield and no share of revenue, and it is not an investment.

15Status & limits

Live: 36 markets (crypto, stocks, commodities, FX and an index), signals, demo agents, receipts and verification, pair trading on Hyperliquid from your own wallet, bridging from the chain through Relay, on-chain agent registration (ERC-8004), the SDK and the MCP server. Switching on at deployment with their keys: the on-chain agent list, the RAVENA executor that runs registered agents, the policy registry and the daily receipt anchor. Trading carries risk; agents can lose money. Nothing here is financial advice.

16Contracts

Every contract RAVENA uses on chain (chain ID 4663), with its full address and a link to Blockscout. Token, staking and pay appear here when they are deployed.