Documentation

Build with Orbyt

Everything the app does is available over a small JSON API and an MCP server, so you can run agents from scripts or straight from your coding assistant.

Paper trading. Prices are live from Lighter's Robinhood Chain spot markets (USDG), agents run 24/7 on the server, but every fill is simulated. No order is ever sent and no funds move.

Overview

Presets: DCA (buys only), PROTECT (sells only), TREND, REBALANCE, MOMENTUM. Cadences: 1m (rules only), 15m, 1h, 1d, 1w. Strategies read closing prices at a timeframe matching the cadence: 1-minute bars for 1m, 15-minute for 15m, 1-hour for 1h/1d/1w.

Quickstart

1. Open the app, sign in (wallet or guest), go to Account → API keys and create a key. 2. Call the API:

# draft an agent from a sentence (nothing is created yet)
curl -s /v1/drafts \
  -H "Authorization: Bearer $ORBYT_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"buy $50 of SPY every week, max 10% per trade"}'

# deploy it
curl -s /v1/agents \
  -H "Authorization: Bearer $ORBYT_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"SPY weekly","preset":"DCA","assets":["SPY"],"cadence":"1w",
       "limits":{"budget":1000,"maxTrade":5,"daily":3},"brain":"rules"}'

Authentication

Scripts and MCP use an API key: Authorization: Bearer orb_…. The web app uses an HTTP-only session cookie. Keys can only be created and revoked from a signed-in browser session (an API key can't mint keys). Keys are stored hashed; the full key is shown once.

Wallet sign-in: POST /v1/auth/nonce {address} returns a message, the wallet signs it with personal_sign, then POST /v1/auth/verify {address, signature}. The message states it authorizes no transaction. POST /v1/auth/guest creates a guest account whose agents move to the wallet on first wallet sign-in.

Markets

GET/v1/marketsAll active USDG pairs: sym, name, px, chg24h, vol24h, hist[]. Add ?lite to skip history. No auth.
GET/v1/statusServer capabilities: AI on/off and model, market status, storage, presets, cadences. No auth.

Agents

POST/v1/drafts{prompt} → proposed config {preset, assets, weights, limits, cadence, name, summary, warnings, source}. Creates nothing.
POST/v1/backtestReplay a config over real Lighter candles with the built-in rules and the same risk engine. Body: same fields as create, plus optional days. Bars match the cadence (1m → 1-minute, 15m → 15-minute, 1h/1d/1w → 1-hour); max history 1 / 7 / 30 days. Returns returnPct, buyHoldPct, maxDrawdownPct, fills, rejects, trades, curve, benchmark.
POST/v1/agentsCreate. Body: name, preset, assets[], limits{budget 100–25000, maxTrade 1–30, daily 1–15, floor 2–30}, cadence, brain ("rules"|"ai"), weights[] (REBALANCE), prompt. AI agents need cadence ≥ 15m. Max 20 active agents.
GET/v1/agentsYour agents with equity, pnl, pnlPct, positions, fills, rejects, status.
GET/v1/agents/:idOne agent plus equityCurve (5-minute points; ?equity=N), last 60 events and its listing.
GET/v1/agents/:id/eventsDecision log: DEPLOY, PROPOSE, REJECT, FILL, HOLD, HALT, PAUSE, RESUME, CLOSE, AI ERR. ?limit= up to 500.
POST/v1/agents/:id/pauseStop deciding. /resume restarts and resets the daily-loss baseline. /close sells all positions and stops permanently.
GET/v1/fillsYour paper fills, newest first. ?limit= up to 500. tx_hash is the receipt hash, block its position in the agent's chain.
GET/v1/receipts/:hashPublic. One receipt with fill, prev, next, canonical and checks{hashMatches, prevLinked}. No auth — the hash is the link.

Verifying a receipt

Each fill's hash is sha256(canonical), where canonical is the pipe-joined string orbyt-receipt-v1|agent_id|block|ts_ms|side|sym|qty|price|usd|prev_hash and prev_hash is the previous fill of the same agent (0x000…0 for the first). Changing or deleting any past fill breaks every later hash. Open /receipt?h=0x… to recompute it in your browser. Fills are paper fills: nothing is written on-chain.

Marketplace

GET/v1/listingsListed agents with full strategy, stats{returnPct, maxDrawdownPct, fills, since} and an equity curve. ?preset= filter. No auth.
POST/v1/listings{agentId, title, description, priceMonth} — list (or update) one of your agents. priceMonth is USDG per 30 days; a price above 0 needs a wallet sign-in (buyers pay that wallet).
POST/v1/listings/:id/pay{txHash} — after sending priceMonth USDG from your signed-in wallet to the listing's payTo on Robinhood Chain (chain 4663). The server reads the transaction and grants 30 days. 409 = not confirmed yet, retry.
POST/v1/listings/:id/copyStart your own agent with that strategy; optional {limits} overrides (e.g. budget). Paid listings return 402 until you've paid.
GET/v1/me/subscriptionsYour paid access: [{listingId, paidUntil, active}].
GET/v1/chainPayment chain info: chainId, usdg, usdgDecimals, explorer, rpc, ok.

Payments are non-custodial: USDG goes from the buyer's wallet straight to the seller's. Orbyt never holds funds or keys, takes no fee, and only reads the transaction receipt. Listings by Orbyt Labs and by sellers without a wallet are free.

DELETE/v1/listings/:idUnlist your agent.

Account

GET/v1/meCurrent user (guest or wallet).
GET/v1/me/balancesRead-only Lighter (Robinhood Chain) accounts for your wallet: collateral, asset balances, perp positions.
GET/v1/keysList keys. POST /v1/keys {name} creates one (session only). DELETE /v1/keys/:id revokes.

Errors & limits

Errors are JSON {"error": "…"} with a 4xx/5xx status. POST bodies must be application/json, max 64 KB. The server caps Claude calls per hour (AI_MAX_CALLS_PER_HOUR); when the cap is hit, AI agents fall back to rules for that decision.

MCP server

The MCP server exposes these tools to any MCP client: list_markets, draft_agent, backtest_agent, create_agent, list_agents, get_agent, pause_agent, resume_agent, close_agent, list_fills, browse_marketplace, copy_listing.

Claude Code

claude mcp add orbyt \
  --env ORBYT_API_KEY=orb_your_key --env ORBYT_URL= \
  -- node /path/to/orbyt/mcp/orbyt-mcp.mjs

Codex (~/.codex/config.toml)

[mcp_servers.orbyt]
command = "node"
args = ["/path/to/orbyt/mcp/orbyt-mcp.mjs"]
env = { ORBYT_API_KEY = "orb_your_key", ORBYT_URL = "" }

Then ask things like "create an agent that buys $50 of SPY every week" or "how are my agents doing?". The assistant drafts first and should confirm before creating or closing anything.

Self-hosting

cd orbyt
npm install
cp .env.example .env     # add keys (all optional)
npm start                # http://localhost:5173