# Epsilon Developers — full context

> Verbose companion to /llms.txt: everything an AI agent or developer needs
> to integrate Epsilon inline, without following links. Epsilon is the
> limit-order DEX on Robinhood Chain — non-custodial limit, stop-loss, and
> DCA orders for memecoins and RWAs, filled on-chain by keepers.

## What Epsilon is

- App: https://app.epsilon.exchange (Privy login: wallet or passkey)
- Chain: Robinhood Chain, chain id 4663
  - RPC: https://rpc.mainnet.chain.robinhood.com
  - Explorer: https://robinhoodchain.blockscout.com
  - Dollar stable: USDG 0x5fc5360d0400a0fd4f2af552add042d716f1d168 (6 decimals)
  - Epsilon router (v7.1): 0xdb41FA80016DC946cEB7B8512c3423463d3F260f
- Trust model: NON-CUSTODIAL end to end. Orders are EIP-712 typed-data
  messages signed by the maker's own wallet, locally. The API receives only
  the signature; funds stay in the maker's wallet until a keeper fills the
  order on-chain. Epsilon infrastructure never holds private keys.

## REST API (/v1)

Base URL: https://api.epsilon.exchange — all endpoints under /v1.
Auth: API key with `eps_` prefix, sent as `X-API-Key: eps_...` or
`Authorization: Bearer eps_...`. Free self-serve keys (Privy sign-in):
https://developers.epsilon.exchange/dashboard

Endpoints (full schemas: https://developers.epsilon.exchange/openapi.json,
also served live at GET /v1/openapi.json without a key):

- GET  /v1/quote          — best executable quote for tokenIn/tokenOut/amountIn
- GET  /v1/route          — full route breakdown incl. feeLegs (REQUIRED input
                            for order signing: fetch the route, pass feeLegs
                            into the SDK's buildAndSignOrder)
- POST /v1/orders         — submit a signed order (orderType: limit |
                            stop_loss | dca + the signed payload from an SDK)
- GET  /v1/orders/{hash}  — order status + fills
- GET  /v1/orders         — list orders by wallet/status/type
- DELETE /v1/orders/{hash} — cancel with a maker-signed OrderCancel message
- GET  /v1/orderbook      — open orders on both sides of a pair
- GET  /v1/tokens?search= — token discovery: symbol/name → address +
                            decimals, ranked by 30-day USD volume
- GET  /v1/swaps · /v1/volume · /v1/stats — market data
- GET  /v1/errors         — machine-readable error catalog with retry guidance (no key)
- GET  /v1/config         — live contract addresses + chain config (no key)

Rate limits are per key and tier-driven, with X-RateLimit-Limit /
X-RateLimit-Remaining / X-RateLimit-Reset headers on every response:

- free:     120 quote / 600 read / 30 order per minute
- builder:  5× free (apply on the dashboard) — rev-share needs NO tier, see below
- enterprise: by contract (team@epsilon.exchange)

Agent etiquette: quotes are the scarce resource — quote once per decision,
poll order state via /v1/orders instead. On 429, back off until
X-RateLimit-Reset. Error bodies carry actionable `code` + `error` fields.

## Order signing (EIP-712)

Domain: { name: "EpsilonRouter", version: "7", chainId: 4663,
verifyingContract: 0xdb41FA80016DC946cEB7B8512c3423463d3F260f }

The v7.1 Order struct fields, in order: salt, maker, receiver, tokenIn,
tokenOut, amountIn, triggerPrice, triggerAmountOut, makerTraits, referrer,
referralFeePpm. Do NOT hand-roll this struct — use an SDK. Omitting
triggerAmountOut (added in v7.1) or mis-encoding makerTraits produces
signatures the verifier rejects. Cancels are a separate signed message:
OrderCancel { orderHash }. ERC-20 tokenIn needs a router allowance before
placement.

## TypeScript SDK — @epsilon-exchange/sdk (npm)

Function-based: shared ApiConfig + apiGet/apiPost helpers, dedicated
functions for signing-critical paths. Node ≥ 20 or browser (viem-based).

    import {
      apiGet, apiPost, fetchOrderRoute,
      buildAndSignOrder, calculateTriggerPrice, approveRouter,
      USDG_ADDRESS, DEFAULT_RPC_URL,
    } from '@epsilon-exchange/sdk'
    import { privateKeyToAccount } from 'viem/accounts'

    const cfg = { baseUrl: 'https://api.epsilon.exchange', apiKey: process.env.EPSILON_API_KEY! }
    const account = privateKeyToAccount(process.env.WALLET_KEY as `0x${string}`)

    const { tokens } = await apiGet(cfg, '/v1/tokens?search=WETH')
    const weth = tokens[0]
    const amountIn = 100_000_000n // 100 USDG (6 decimals)
    const route = await fetchOrderRoute(cfg, {
      tokenIn: USDG_ADDRESS, tokenOut: weth.address,
      amountIn: amountIn.toString(), slippagePpm: 10_000, wallet: account.address,
    })
    await approveRouter(DEFAULT_RPC_URL, account, USDG_ADDRESS, amountIn)
    const signed = await buildAndSignOrder({
      account, tokenIn: USDG_ADDRESS, tokenOut: weth.address,
      amountIn, triggerPrice: calculateTriggerPrice('0.00025', weth.decimals),
      tokenInDecimals: 6, deadline: Math.floor(Date.now() / 1000) + 86_400,
      slippagePpm: 10_000, kind: 'limit', feeLegs: route.feeLegs,
    })
    const { orderHash } = await apiPost(cfg, '/v1/orders', { orderType: 'limit', ...signed })

## Python SDK — epsilon-exchange (PyPI)

Client class + free-standing signing functions (eth-account based):

    from epsilon_exchange import EpsilonClient, build_and_sign_order, calculate_trigger_price

    client = EpsilonClient(api_key="eps_...")
    route = client.order_route(token_in, token_out, amount_in, slippage_ppm=10_000, wallet=my_address)
    signed = build_and_sign_order(
        private_key, token_in, token_out, amount_in,
        trigger_price=calculate_trigger_price("3000", token_out_decimals),
        token_in_decimals=18, fee_legs=route.get("feeLegs"),
    )
    client.submit_order(signed, "limit")

Both SDKs are golden-fixture-tested against the on-chain verifier — trust
their output over any manual re-derivation of the EIP-712 struct.

## CLI — @epsilon-exchange/cli (npm)

The TS SDK as shell commands, for cron jobs and CLI-first agents:

    export EPSILON_API_KEY=eps_...          # required
    export EPSILON_WALLET_KEY=0x...         # dedicated trading wallet (orders only)
    npx @epsilon-exchange/cli quote 0.5 WETH USDG
    npx @epsilon-exchange/cli order 0.5 WETH USDG --price 3100 --expiry-hours 72 --yes
    npx @epsilon-exchange/cli orders --status active
    npx @epsilon-exchange/cli portfolio
    npx @epsilon-exchange/cli cancel 0xORDER_HASH

Tokens accept symbols or 0x addresses; amounts/prices are human units.
Orders confirm interactively unless --yes; --json on any command for
machine output; EPSILON_MAX_ORDER_USD and EPSILON_REFERRER honored.

## MCP for AI agents

Two servers; setup guide with per-client instructions (Cursor, Claude Code,
Claude Desktop, ChatGPT, Codex, Grok): https://developers.epsilon.exchange/mcp.html

1. Hosted read-only (Streamable HTTP): https://api.epsilon.exchange/mcp.
   Lazy auth: the docs-discovery tools — search_docs (searches these docs),
   list_examples, get_example (full example source) — work with NO API key,
   so any agent can research the integration with zero setup. Market tools
   take the X-API-Key header: get_quote, get_route, order_preflight,
   get_order_status, get_orderbook, market_stats, recent_swaps,
   token_volume, search_tokens, list_orders, error_catalog,
   get_market_overview (one-call snapshot: top tokens, 24h volume, stats).
   Cannot trade, by design — it holds no keys.
2. Local trading package: `npx -y @epsilon-exchange/mcp` (stdio, Node ≥ 20).
   Adds get_portfolio, token_info, wallet_info, approve_token,
   place_limit_order (limit + stop-loss), place_dca_order, cancel_order.
   Env: EPSILON_API_KEY (required), EPSILON_WALLET_KEY (only for trading;
   use a DEDICATED trading wallet), EPSILON_MAX_ORDER_USD (per-order USD
   spend cap, fails closed), EPSILON_REQUIRE_CONFIRM (two-step confirm:
   placement tools return a preview, must be re-called with confirm=true).
   MCP registry entry: io.github.alienbase-xyz/epsilon

## Skills and plugin

- One-command skill install into 17+ agent runtimes:
  `npx skills add alienbase-xyz/epsilon-plugin`
  (skills: epsilon-trading — safe trading workflow; epsilon-api-dev — API/SDK
  integration guidance)
- Claude Code marketplace: `/plugin marketplace add alienbase-xyz/epsilon-plugin`
  then `/plugin install epsilon`
- Repo: https://github.com/alienbase-xyz/epsilon-plugin
- Working examples (copy-paste starting points): LangChain tools, Vercel AI
  SDK tools, a grammY Telegram bot with two-step confirm, and a Python cron
  DCA trader — https://github.com/alienbase-xyz/epsilon-examples

## Webhooks

Register up to 3 HTTPS endpoints on the dashboard (POST /v1/developer/webhooks
via the dashboard UI) and Epsilon POSTs the order-lifecycle events of your
linked wallets — order.filled, order.cancelled, order.expired, order.failed,
stop.triggered, dca.completed, dca.stalled — instead of you polling
GET /v1/orders. Each endpoint subscribes to all triggers or a subset.

Delivery contract: body is { id, trigger, createdAt, data } where data carries
orderType, pair, tokenIn/tokenOut, amountIn/amountOut, txHash, orderHash (and
reason/revertName on failures). Headers: X-Epsilon-Event (trigger),
X-Epsilon-Delivery (unique event id — dedupe on it), X-Epsilon-Signature
(t=<unix>,v1=<hex>). Verify v1 = HMAC-SHA256(secret, t + "." + rawBody) in
constant time and reject stale t (~5 min). At-least-once with exponential
retries (~a day); respond 2xx fast, process async. Persistently failing
endpoints are auto-disabled. A Test button on the dashboard sends a synthetic
test.ping delivery.

## Rev-share (permissionless) and builder tier

Rev-share needs no application: add ?referrer=0xYourAddress to GET
/v1/route and the served feeLegs carry your payout address — the maker
signs it into the order and the router pays you the referral leg of every
fill on-chain, from fill one. The fee ppm is policy-set server-side: you
choose the destination, never the size, so users pay exactly what they
would anyway. Pass-throughs: fetchOrderRoute({ …, referrer }) in the TS
SDK, order_route(…, referrer=…) in Python, EPSILON_REFERRER env on the MCP
server.

The builder tier (apply on the dashboard) adds ~5× rate limits and the
dashboard earnings view for your referrer address. Enterprise (custom
rates, allowlists, contracts): team@epsilon.exchange

Distinct from the in-app user referral program (invites, ranks, points):
that pays for bringing USERS and requires an Epsilon account; rev-share
pays for routing ORDERS and needs only an address. The maker always pays
their own policy rate — the referrer param changes the leg's destination,
never its size, and never the user's cost.

## AGENTS.md block (paste into your repo for coding agents)

    ## Epsilon (Robinhood Chain DEX)
    - Chain: Robinhood Chain, id 4663 · RPC https://rpc.mainnet.chain.robinhood.com
    - API: https://api.epsilon.exchange/v1 (X-API-Key auth; free keys:
      https://developers.epsilon.exchange/dashboard)
    - OpenAPI: https://developers.epsilon.exchange/openapi.json
    - SDKs: `npm i @epsilon-exchange/sdk` (TS/viem) · `pip install epsilon-exchange`
    - Orders are EIP-712, signed LOCALLY via the SDK's buildAndSignOrder —
      domain { name: "EpsilonRouter", version: "7", chainId: 4663 }. Never
      hand-roll the struct (v7.1 includes triggerAmountOut); never send keys.
    - ERC-20s need a router allowance before placement (approveRouter).
    - Rate limits (free): 120 quote / 600 read / 30 order per min. Poll orders,
      not quotes.
    - Docs index for agents: https://developers.epsilon.exchange/llms.txt

## Safety model (for agents placing orders)

- Use a dedicated trading wallet with limited funds — never a main wallet.
- Keep EPSILON_MAX_ORDER_USD set and EPSILON_REQUIRE_CONFIRM on; show the
  confirmation preview to the human verbatim and only proceed after
  explicit approval. Never auto-confirm.
- Prices are token_out per 1 token_in — sanity-check direction with a quote
  before placing.
- The API key is attribution + rate limiting; it cannot move funds. The
  wallet key signs locally and is never transmitted.

## Links

- Docs: https://developers.epsilon.exchange/
- API reference: https://developers.epsilon.exchange/api/
- MCP + agent setup: https://developers.epsilon.exchange/mcp.html
- Compact index: https://developers.epsilon.exchange/llms.txt
- Dashboard (keys, usage, builder tier): https://developers.epsilon.exchange/dashboard
- App: https://app.epsilon.exchange · Landing: https://epsilon.exchange
- Product docs: https://docs.epsilon.exchange · X: https://x.com/TradeEpsilon