# MOX docs

How MOX works: test USD, markets and indexes, trading, margin, funding, the oracle, simulated activity, AI agents and the API. Human page: https://trademox.com/docs

- [Getting started](https://trademox.com/docs#start)
- [Markets & indexes](https://trademox.com/docs#markets)
- [Trading](https://trademox.com/docs#trading)
- [Margin & liquidation](https://trademox.com/docs#margin)
- [Funding](https://trademox.com/docs#funding)
- [The oracle](https://trademox.com/docs#oracle)
- [Simulated activity](https://trademox.com/docs#sim)
- [AI & agents](https://trademox.com/docs#ai)
- [API](https://trademox.com/docs#api)
- [FAQ](https://trademox.com/docs#faq)

## Getting started

_MOX is a demo exchange. Everything runs on test USD._

| Item | Value | Notes |
|---|---|---|
| Collateral | Test USD | Demo money. Nothing on MOX is real money, and nothing can be withdrawn. |
| Starting balance | $1,000 | Credited the first time you log in. |
| Faucet | Back to $1,000 · 1/h | Tops your balance back up to $1,000 once an hour, whenever it's below $1,000. |
| Liquidity | Simulated + real | Market makers and sim traders keep every book two-sided. They're tagged “sim”. |

1. **Log in.** Your account opens with $1,000 test USD.
2. **Pick a market** on [Markets](https://trademox.com/): a card, a skin or an index basket.
3. **Long or short.** Set size (units or USD), leverage and order type, then place it.
4. **Manage it** on [Portfolio](https://trademox.com/portfolio): PnL, funding, liquidation price, close.

## Markets & indexes

_Perpetual futures: price exposure to a collectible, no expiry, no delivery._

| Item | Value | Notes |
|---|---|---|
| Categories | MTG · Pokémon · One Piece · CS2 |  |
| Max leverage | 3–5× singles · 5–10× indexes | Set per market from its liquidity and volatility. |
| Min order | $10 notional |  |
| OI cap | $25k–$500k / side | Open-interest cap per side, in USD notional. Orders past it are rejected (oi_cap). |

- A **perp** tracks an item's price with no expiry and no delivery. You hold price exposure, never the card or skin.
- **Size** is in units of the item: 1 = one card, one skin or one basket. Order in units or in USD.
- Each market names its exact item: print, set, condition or wear (e.g. Unlimited · Near Mint, Factory New).
- **Index perps** track a basket. Price = Σ (constituent oracle price × quantity). One trade, a whole meta.

> Index price = Σ (constituent oracle price × quantity)

## Trading

_Hyperliquid-style central limit order book, price-time priority._

| Item | Value | Notes |
|---|---|---|
| Taker fee | 0.045% | Orders that fill immediately against the book. |
| Maker fee | 0.015% | Limit orders that rest on the book and get filled. |
| Price band | ±15% of oracle | Limit prices further than 15% from the oracle are rejected (price_band). |
| Market slippage | 5% from mark | Default worst price for market orders. API: slippage_bps. |
| Leverage | 1× to market max | Set per market. It applies to your whole position there. |
| Order rate | 20 / min | Order placements per account. |

- **Long** gains when the price rises. **Short** gains when it falls.
- **Market** fills now against the book, within the slippage bound. **Limit** rests at your price.
- **Post-only** limits never take; rejected if they would cross (post_only_would_cross).
- **Reduce-only** can only shrink a position, never grow or flip it.
- Self-trade prevention: your order never fills against your own resting order; the resting one is cancelled.

| Example | Value |
|---|---|
| Long 2 × a $500 card at 5× | $1,000 notional |
| Initial margin | $1,000 ÷ 5 = $200 |
| Taker fee | $1,000 × 0.045% = $0.45 |
| Card +10% | +$100 PnL · +50% on margin |

Rejections: `insufficient_margin`, `price_band`, `oi_cap`, `min_notional`, `reduce_only`, `post_only_would_cross`, `no_liquidity`, `oracle_stale`.

## Margin & liquidation

_Cross margin: one balance backs every position._

| Item | Value | Notes |
|---|---|---|
| Mode | Cross margin | Gains in one market support positions in the others. |
| Initial margin | Notional ÷ leverage |  |
| Maintenance | Notional ÷ (2 × max lev.) | 10% for a 5× market, 5% for a 10× index. |
| Partial liquidation | 20% slices > $2,000 | Positions above $2,000 notional close 20% at a time, then a 30 s cooldown. |
| Liquidation fills | Within 10% of mark |  |
| Vault backstop | < ⅔ of maintenance | The MOX Liquidity Vault takes over every position at mark. |

> Account value vs maintenance margin: healthy above it, liquidation below it, vault takeover below ⅔ of it

- **Account value** = balance + unrealized PnL. **Free collateral** = account value − margin in use − margin held by open orders.
- Below **maintenance**: open orders are cancelled and positions close into the book with reduce-only market orders, largest first.
- Small positions close in full. Large ones close 20% at a time. It stops once you're back above maintenance.
- Below **⅔ of maintenance**: the **MOX Liquidity Vault** takes every position at mark and keeps the remaining margin. Any bad debt is the vault's; you never owe more than your balance.
- Everything runs on the **mark** price: a 150 s smoothed price that moves ≤ 0.3%/s and stays within ±10% of the oracle. One wild print can't liquidate you.

## Funding

_Hourly payments between longs and shorts that keep the perp near the oracle._

| Item | Value | Notes |
|---|---|---|
| Paid | Hourly, on the hour |  |
| Interest | 0.00125% / h | 0.01% per 8 h, the Hyperliquid baseline. |
| Premium clamp | ±0.05% / 8 h |  |
| Cap | ±4% / h |  |

> Perp above oracle: longs pay shorts. Perp below oracle: shorts pay longs.

- Perp above oracle → rate positive → **longs pay shorts**. Below → shorts pay longs.
- Rate / h = (premium + clamp(interest − premium, ±0.05%)) ÷ 8, Hyperliquid's 8 h formula paid hourly.
- **Premium** compares $1,000 impact bid/ask to the oracle, sampled every 5 s and averaged over the hour.
- Payment = position size × oracle price × rate. Shown as %/h on every market; your history is on [Portfolio](https://trademox.com/portfolio).

## The oracle

_Every price starts as an outside sale or listing, and every print is screened before it counts._

| Item | Value | Notes |
|---|---|---|
| Card sources | TCGplayer · Scryfall · PokémonTCG · JustTCG | TCGplayer market prices and sales via TCGCSV. |
| Skin sources | Skinport · Steam · CSFloat |  |
| Half-life | 24 h cards · 2 h CS2 | Recency weighting: a print loses half its weight every half-life. |
| Slew limit | 6 bps/min cards · 15 CS2 | 3.6%/h for cards, 9%/h for skins. A forced print can only nudge the price. |
| Stale after | 48 h cards · 45 min CS2 | No accepted print in that window: opening orders pause, closes still work. |
| Max weight / sale | 12% |  |

> Collect → Screen (stat-v1 + Jev) → Aggregate (recency-weighted median) → Publish (slew-limited)

1. **Collect.** Sales, aggregate market prices and listings from each market's sources. Indexes price every constituent.
2. **Screen.** Each print gets a manipulation score from 0 to 1. **stat-v1** measures distance from the recent median (in MAD units), from the oracle and from other sources, plus same-direction bursts and walk-ups.
3. **Aggregate.** Target = recency-weighted median of accepted and downweighted prints. No single sale carries more than 12%.
4. **Publish.** The live price walks toward the target at the slew limit.

**Jev** (TypeSafe's decision model) reads every print after stat-v1 and answers two questions: was it made to manipulate the price, and should it be included? Score = max(stat-v1, Jev). Jev can raise risk, never lower it; a confident “don't include” drops the print. If Jev is down, stat-v1 stands.

> Score < 0.35 accepted; 0.35–0.70 downweighted (weight × (1 − score)); > 0.70 rejected

Status is `live`, `stale` or `seed` (no live source yet). Every screened print, with its score and reasons, is public on [Oracle](https://trademox.com/oracle).

## Simulated activity

_Bots keep the books full. They're labelled everywhere._

|   | Simulated | Real |
|---|---|---|
| Money | Test USD for everyone | — |
| Prices | — | Oracle from outside collectible markets |
| Liquidity | Market makers quote 5 levels a side around the oracle | Your orders, and other traders' |
| Traders | A dozen sim traders (momentum, mean reversion) | Everyone tagged without “sim” |
| Engine | — | Matching, margin, funding, liquidation: same rules for all |

- Simulated accounts: market makers, sim traders, the MOX Liquidity Vault and the fee account. All tagged **sim**.
- Volume, open interest and trader counts show their simulated share (hover the stat).
- Real traders are highlighted on the live tape. Sim traders rank on the leaderboard, tagged; makers and the vault don't.

## AI & agents

_MOX speaks the Model Context Protocol. Point Claude, ChatGPT, Cursor or any MCP client at it._

| Endpoint | URL | Auth |
|---|---|---|
| Public MCP (market data) | https://trademox.com/mcp | none |
| Account MCP (portfolio + trading) | https://trademox.com/mcp/trade | Bearer `mox_sk_…` API key, or OAuth (Claude.ai, ChatGPT) |
| OpenAPI 3.1 | https://trademox.com/openapi.json | none |
| MCP server card | https://trademox.com/.well-known/mcp.json | none |

### Client setup

- **Claude Code:** `claude mcp add --transport http mox https://trademox.com/mcp/trade --header "Authorization: Bearer mox_sk_…"` (or `claude mcp add --transport http mox-public https://trademox.com/mcp` for read-only).
- **Claude.ai / Claude Desktop:** Settings → Connectors → Add custom connector → `https://trademox.com/mcp/trade`. You log in on MOX and approve read / trade (OAuth).
- **ChatGPT:** Settings → Connectors → Create (developer mode) → MCP server URL `https://trademox.com/mcp/trade`, authentication OAuth.
- **Cursor:** `.cursor/mcp.json` → `{"mcpServers":{"mox":{"url":"https://trademox.com/mcp/trade","headers":{"Authorization":"Bearer mox_sk_…"}}}}`
- **VS Code:** `.vscode/mcp.json` → an HTTP server at `https://trademox.com/mcp/trade` with the API key header (use a promptString input for the key).

### API keys

- Create, list and revoke keys at https://trademox.com/docs#ai (logged in). The secret (`mox_sk_…`) is shown once and stored hashed. Up to 10 per account.
- Scopes: `read` = account data; `trade` = place, cancel and close orders, faucet. A call missing a scope returns 403 `scope_required`.
- Keys work as Bearer tokens on `/mcp/trade` and on REST `/v1/*`. Keys can't manage keys. Test USD only.

### Tools

| Tool | Endpoint | Scope | What it does |
|---|---|---|---|
| `list_markets` | public | – | Markets with live stats; filter by category, kind or text |
| `get_market` | public | – | One market: spec, stats, index constituents |
| `get_order_book` | public | – | L2 book |
| `get_recent_trades` | public | – | Latest public trades |
| `get_candles` | public | – | OHLC candles (1d includes pre-listing reference bars) |
| `get_oracle_state` | public | – | Published vs target price, sources, screened prints |
| `list_oracle_observations` | public | – | Screened prints across all markets |
| `get_trade_feed` | public | – | Every trade on every market |
| `get_top_movers` | public | – | Biggest 24h moves, per category |
| `get_leaderboard` | public | – | Traders ranked by PnL |
| `get_account` | account | read | Balance, positions, open orders |
| `list_fills · list_orders · list_funding_payments · get_activity` | account | read | History |
| `place_order` | account | trade | Market or limit, size in units or USD, leverage |
| `cancel_order · cancel_all_orders` | account | trade | Cancel resting orders |
| `close_position` | account | trade | Close all or part of a position |
| `claim_faucet` | account | trade | Top test USD back up to $1,000 |

**WebMCP:** in a browser with `document.modelContext`, the open page registers `search_markets`, `get_market_snapshot`, `open_market`, `get_my_account`, `prepare_order`, `cancel_order`. `prepare_order` only pre-fills the ticket; you press the button.

**For language models:** [llms.txt](https://trademox.com/llms.txt), [llms-full.txt](https://trademox.com/llms-full.txt), and a Markdown twin of every page (`Accept: text/markdown` or a `.md` suffix, e.g. `/trade/MTG-LOTUS.md`).

## API

_REST for snapshots and orders, WebSocket for everything live. JSON is snake_case._

| Item | Value | Notes |
|---|---|---|
| REST | https://api.trademox.com/v1 |  |
| WebSocket | wss://api.trademox.com/ws |  |
| Auth | Bearer: login token or API key |  |
| Rate limit | 120 / min per token | Anonymous callers share 6,000/min per IP. 20 order placements/min per account. Over: 429 + Retry-After. |

- Decimals are **strings** (`"1234.50"`). Times are unix **ms**. Sizes are item units, signed on positions. Funding is a fraction **per hour**.
- Errors: `{"error":{"code","message"}}`. Order rejections are 4xx errors, never stored orders.
- Public data is cached ≤ 1 s with ETags. Poll REST for the first paint, then switch to the socket.
- Full spec: [OpenAPI 3.1](https://trademox.com/openapi.json).

Markets, book, an order:

```
curl https://api.trademox.com/v1/markets
curl "https://api.trademox.com/v1/markets/MTG-LOTUS/book?depth=10"
curl -X POST https://api.trademox.com/v1/orders \
  -H "Authorization: Bearer mox_sk_…" -H "Content-Type: application/json" \
  -d '{"symbol":"MTG-LOTUS","side":"buy","type":"market","sz_usd":"100","leverage":3}'
```

WebSocket · wss://api.trademox.com/ws:

```
{"op":"subscribe","channel":"markets"}
{"op":"subscribe","channel":"book","symbol":"MTG-LOTUS"}
{"op":"subscribe","channel":"feed"}
{"op":"auth","token":"mox_sk_…"}
{"op":"subscribe","channel":"account"}
```

Channels: `markets` (changed stats ≤ 1/s), `book` (≤ 4/s), `trades`, `feed`, `candles`, `oracle`, `account`. Merge `markets` updates by symbol. Reconnect with backoff and resubscribe.

## FAQ

**Is this real money?** No. Test USD only. Nothing is deposited, nothing can be withdrawn.

**Do I own the card or skin?** No. A perp is price exposure only. No custody, no delivery, no expiry.

**Where do prices come from?** Outside collectible markets (TCGplayer, Scryfall, Skinport, Steam, CSFloat and more), screened for manipulation and slew-limited. See [The oracle](https://trademox.com/docs#oracle).

**Why was my limit order rejected?** Most often `price_band` (more than 15% from the oracle) or `insufficient_margin`. The error code says which.

**Can I lose more than my balance?** No. If an account falls below ⅔ of maintenance, the MOX Liquidity Vault takes over and absorbs any bad debt.

**What happens when the oracle goes stale?** New opening orders pause in that market until a fresh print is accepted. Closing and reducing still work.

**I'm out of test USD.** Use the faucet on [Portfolio](https://trademox.com/portfolio): back to $1,000 once an hour.

**Who is “sim”?** Market makers, simulated traders, the liquidity vault and the fee account. See [Simulated activity](https://trademox.com/docs#sim).

**Can my AI trade for me?** Yes, with an API key or OAuth that has the `trade` scope. Revoke it any time in [AI & agents](https://trademox.com/docs#ai).