99X Arena — Worker API

Base URL: https://memeflow-worker.testcf-195.workers.dev. JSON request and response bodies use Content-Type: application/json. The Worker is authoritative for sessions, balances, positions, PnL, liquidation, prices, candles, execution costs, and rankings.

Authentication, sessions, and retries

POST /api/session
{"nickname":"PIXEL_KING"}

201 {"token":"99x_...","user":{"id":"...","nickname":"PIXEL_KING","balance":10000}}

Keep the opaque session token private. Authenticated calls require X-Session-Token: <token>. The browser client stores only this token in localStorage; it does not persist or synthesize account state.

Every trading mutation requires Idempotency-Key, an 8–64 character unique value containing only letters, digits, _, or -. Retrying an identical request with the same key returns the original result. Reusing a key for a different payload is rejected.

Markets and candles

The seven supported pairs are PEPE/99X, DOGE/99X, SHIB/99X, SOL/99X, ASTER/99X, CAKE/99X, and UNI/99X. Encode the slash in path parameters.

GET /api/market/PEPE%2F99X/ticker
200 {"symbol":"PEPE/99X","price":0.00001234,"source":"Binance"}

GET /api/market/PEPE%2F99X/candles?interval=15m&limit=100
200 {"symbol":"PEPE/99X","interval":"15m","candles":[
  {"openTime":...,"time":...,"open":...,"high":...,"low":...,"close":...,"volume":...}
],"source":"Binance"}

Supported intervals are exactly 1m, 5m, 15m, 1h, 4h, 1d, 1w, 1M, and 1Y. Candle limit is bounded to 1–500; 1Y returns up to 12 monthly candles.

Account state and multiple positions

GET /api/state
X-Session-Token: <token>

200 {
  "user":{"id":"...","nickname":"...","balance":...,"realized_pnl":...,"rank":...},
  "positions":[{"position_id":"...","symbol":"PEPE/99X","side":"long",
    "margin_mode":"isolated","leverage":5,"margin":200,"entry_price":...,
    "liquidation_price":...,"take_profit":...,"stop_loss":...,"unrealized_pnl":...}],
  "cross_margin":{"equity":...,"maintenance_margin":...,"liquidate":false},
  "liquidations":[]
}

positions is always an array. An account can hold multiple simultaneous positions. Long and short positions can coexist for hedging; the same symbol and side cannot be opened twice. isolated positions have a position liquidation price. cross positions participate in account-level cross-margin risk.

Open a position

POST /api/trade/open
X-Session-Token: <token>
Idempotency-Key: <unique-key>

{"symbol":"PEPE/99X","side":"short","leverage":20,"margin":200,
 "margin_mode":"isolated","take_profit":0.000011,"stop_loss":0.000013}

side is long or short; margin_mode is isolated or cross. Allowed leverage is an exact allowlist: 1, 2, 5, 10, 20, 25, 50, 100, 125, 250, 500, or 1000.

take_profit and stop_loss are optional absolute prices. For LONG, TP must be above entry and SL below entry. For SHORT, TP must be below entry and SL above entry. The server validates targets against its authoritative entry/mark price.

Update TP / SL

POST /api/trade/risk
X-Session-Token: <token>
Idempotency-Key: <unique-key>

{"position_id":"...","take_profit":0.000011,"stop_loss":null}
200 {"position":{"position_id":"...","take_profit":0.000011,"stop_loss":null,...}}

Send either or both risk fields. Omitted fields are unchanged; an explicit null clears that target. Risk validation follows the position side.

Close a position

POST /api/trade/close
X-Session-Token: <token>
Idempotency-Key: <unique-key>

{"position_id":"..."}
200 {"trade":{...},"exit_price":...}

position_id is mandatory because accounts may have multiple positions.

AI agent state and actions

AI routes require both X-Session-Token and X-Agent-Key. Agent keys are separate credentials and have stricter rate limits.

GET /api/ai/state
X-Session-Token: <token>
X-Agent-Key: <agent-key>

# Response has the same authoritative user, positions array, and cross_margin shape as /api/state.

POST /api/ai/action
X-Session-Token: <token>
X-Agent-Key: <agent-key>
Idempotency-Key: <unique-key>

{"action":"open","symbol":"SOL/99X","side":"long","leverage":5,
 "margin":100,"margin_mode":"cross","take_profit":null,"stop_loss":null}

# Or:
{"action":"close","position_id":"..."}

Fees, slippage, and notional limits

Execution costs and limits are server-enforced. The general rule is: notional equals margin × leverage; opening requires sufficient available balance for margin plus any opening fee; simulated slippage worsens both entry and exit; settlement and PnL are net of applicable fees. Do not hardcode fee, slippage, or max_notional constants in clients. Treat values returned in the API response (for example execution fee/slippage/notional or limits metadata) as authoritative because the backend may change them.

Leaderboard and demo-account contract

GET /api/leaderboard?offset=0&limit=25
200 {"entries":[{"nickname":"...","balance":...,"realized_pnl":...,
  "open_positions":0,"unrealized_pnl":0,"equity":...,"returnPct":...,
  "account_type":"live"}],"offset":0,"limit":25}

Rank order is based on server-computed account performance/equity; use the returned order and pagination rather than re-ranking locally. The production leaderboard returns live accounts only; demo accounts are excluded by the server.

Error contract

{"error":"ERROR_CODE"}

Clients should branch on HTTP status and machine-readable error, avoid retrying validation failures, and retry transient failures only with backoff. Trading retries must retain the original idempotency key and identical payload.

← Return to arena