Documentation Index Fetch the complete documentation index at: https://mintlify.com/jamxu88/exchange/llms.txt
Use this file to discover all available pages before exploring further.
All requests go to the base URL: https://exchange.jamesxu.dev
A machine-readable OpenAPI schema and Swagger UI are also available:
https://exchange.jamesxu.dev/api-doc/openapi.json https://exchange.jamesxu.dev/docs
Public endpoints No authentication required.
Method Path Purpose GET/healthService and persistence health GET/api/v1/marketsList configured markets
Returns the service status and current persistence state. No authentication required. Response fields ok when persistence is disabled or ok. degraded when persistence is retrying, backpressured, or stopped.
Current server time in RFC 3339 format.
Current persistence status including mode.
curl https://exchange.jamesxu.dev/health
{ "status" : "ok" , "service" : "exchange" , "now" : "2026-03-18T15:27:00.000000Z" , "persistence" : { "backend" : "in_memory" , "mode" : "disabled" , "queue_depth" : 0 , "last_error" : null } }
Returns the list of all configured markets. No authentication required. curl https://exchange.jamesxu.dev/api/v1/markets
[ { "market_id" : "BTC-USD" , "display_name" : "Bitcoin" , "base_asset" : "BTC" , "quote_asset" : "USD" , "tick_size" : 1 , "min_order_quantity" : 1 , "reference_price" : 100 , "settlement_price" : null , "status" : "enabled" , "created_at" : "2026-03-18T15:00:00.000000Z" , "updated_at" : "2026-03-18T15:00:00.000000Z" } ]
Trader endpoints
Admin endpoints
Trader routes require the x-api-key header. API keys are provisioned by an admin and are prefixed with exch_. x-api-key: exch_1d4208be6fa84b8cb0a2e5cfa9508d5f
Method Path Purpose GET/api/v1/userAuthenticated user profile GET/api/v1/positionsUser positions across markets GET/api/v1/portfolioPortfolio snapshot with PnL GET/api/v1/leaderboardLeaderboard ranked by marked net PnL GET/api/v1/open-ordersOpen orders, optional ?market= filter GET/api/v1/fillsFills, optional ?market= filter POST/api/v1/ordersSubmit a limit order PATCH/api/v1/orders/{order_id}Amend remaining quantity DELETE/api/v1/orders/{order_id}Cancel an order
Returns the authenticated trader’s profile. curl \ -H "x-api-key: YOUR_API_KEY" \ https://exchange.jamesxu.dev/api/v1/user
{ "trader_id" : "9d64e278-8b56-46e9-9cab-18c5b22f2fb9" , "username" : "team-alpha" , "api_key" : "exch_1d4208be6fa84b8cb0a2e5cfa9508d5f" , "created_at" : "2026-03-18T15:27:42.159901Z" }
Returns all open positions for the authenticated trader. curl \ -H "x-api-key: YOUR_API_KEY" \ https://exchange.jamesxu.dev/api/v1/positions
[ { "market" : "BTC-USD" , "net_quantity" : 5 , "average_entry_price" : 98 , "realized_pnl" : 50 , "updated_at" : "2026-03-18T15:30:00.000000Z" } ]
net_quantity is a signed integer. Positive values are long, negative values are short.realized_pnl accumulates as fills close or reduce the position.
Returns a portfolio snapshot including position limit and all current positions. curl \ -H "x-api-key: YOUR_API_KEY" \ https://exchange.jamesxu.dev/api/v1/portfolio
{ "trader_id" : "9d64e278-8b56-46e9-9cab-18c5b22f2fb9" , "position_limit" : 1000 , "positions" : [ { "market" : "BTC-USD" , "net_quantity" : 5 , "average_entry_price" : 98 , "realized_pnl" : 50 , "updated_at" : "2026-03-18T15:30:00.000000Z" } ] }
position_limit reflects the exchange-wide per-market net position limit of +/-1000 .
Returns traders ranked by their current marked net PnL. Marking uses settled prices, orderbook mid prices, or market reference prices. Query parameters Optional. Maximum number of rows to return. Omit to return all traders.
curl \ -H "x-api-key: YOUR_API_KEY" \ "https://exchange.jamesxu.dev/api/v1/leaderboard?limit=10"
[ { "rank" : 1 , "trader_id" : "9d64e278-8b56-46e9-9cab-18c5b22f2fb9" , "username" : "team-alpha" , "net_pnl" : 420 , "realized_pnl" : 300 , "unrealized_pnl" : 120 , "gross_exposure" : 1000 } ]
Returns all resting open orders for the authenticated trader. Filter by market using the optional market query parameter. Query parameters Optional. Filter results to a single market, e.g. BTC-USD.
curl \ -H "x-api-key: YOUR_API_KEY" \ "https://exchange.jamesxu.dev/api/v1/open-orders?market=BTC-USD"
[ { "id" : "66377526-7b98-485a-8c40-7024e68fa3c5" , "trader_id" : "9d64e278-8b56-46e9-9cab-18c5b22f2fb9" , "market" : "BTC-USD" , "side" : "BUY" , "price" : 100 , "quantity" : 2 , "remaining" : 2 , "created_at" : "2026-03-18T15:28:01.342510Z" } ]
Returns all fills for the authenticated trader. Filter by market using the optional market query parameter. Query parameters Optional. Filter results to a single market, e.g. BTC-USD.
curl \ -H "x-api-key: YOUR_API_KEY" \ "https://exchange.jamesxu.dev/api/v1/fills?market=BTC-USD"
[ { "fill_id" : "a1b2c3d4-0000-0000-0000-000000000001" , "market" : "BTC-USD" , "maker_order_id" : "aaa00000-0000-0000-0000-000000000001" , "taker_order_id" : "66377526-7b98-485a-8c40-7024e68fa3c5" , "price" : 100 , "quantity" : 2 , "occurred_at" : "2026-03-18T15:29:10.000000Z" } ]
Submits a limit order. Returns the order, any fills that occurred, and whether the order is resting in the book. Request body Market symbol, e.g. BTC-USD. Must follow the BASE-QUOTE format.
Limit price. Must be greater than zero and align to the market’s tick_size.
Order quantity. Must be at least the market’s min_order_quantity.
Response fields The submitted order with its assigned id and current remaining quantity.
List of fills that occurred immediately on submission. Empty if the order rested.
true if the order has remaining quantity in the book after matching.
curl \ -X POST \ -H "x-api-key: YOUR_API_KEY" \ -H "content-type: application/json" \ https://exchange.jamesxu.dev/api/v1/orders \ -d '{"market":"BTC-USD","side":"BUY","price":100,"quantity":2}'
{ "order" : { "id" : "66377526-7b98-485a-8c40-7024e68fa3c5" , "trader_id" : "9d64e278-8b56-46e9-9cab-18c5b22f2fb9" , "market" : "BTC-USD" , "side" : "BUY" , "price" : 100 , "quantity" : 2 , "remaining" : 2 , "created_at" : "2026-03-18T15:28:01.342510Z" }, "fills" : [], "resting" : true }
Order admission checks worst-case net exposure from all resting open orders. A position limit of +/-1000 applies per market. Exceeding this returns 409 Conflict.
PATCH /api/v1/orders/{order_id}
Amends the remaining quantity of a resting order. You can only reduce remaining — increasing it is not allowed. Path parameters UUID of the resting order to amend.
Request body New remaining quantity. Must be greater than zero and less than or equal to the current remaining.
curl \ -X PATCH \ -H "x-api-key: YOUR_API_KEY" \ -H "content-type: application/json" \ https://exchange.jamesxu.dev/api/v1/orders/ORDER_ID \ -d '{"remaining":1}'
{ "order" : { "id" : "66377526-7b98-485a-8c40-7024e68fa3c5" , "trader_id" : "9d64e278-8b56-46e9-9cab-18c5b22f2fb9" , "market" : "BTC-USD" , "side" : "BUY" , "price" : 100 , "quantity" : 2 , "remaining" : 1 , "created_at" : "2026-03-18T15:28:01.342510Z" } }
DELETE /api/v1/orders/{order_id}
Cancels a resting order. Returns the canceled order. Path parameters UUID of the order to cancel.
curl \ -X DELETE \ -H "x-api-key: YOUR_API_KEY" \ https://exchange.jamesxu.dev/api/v1/orders/ORDER_ID
{ "order" : { "id" : "66377526-7b98-485a-8c40-7024e68fa3c5" , "trader_id" : "9d64e278-8b56-46e9-9cab-18c5b22f2fb9" , "market" : "BTC-USD" , "side" : "BUY" , "price" : 100 , "quantity" : 2 , "remaining" : 2 , "created_at" : "2026-03-18T15:28:01.342510Z" } }
Admin routes require a Bearer token in the Authorization header. Authorization: Bearer ADMIN_API_TOKEN
Method Path Purpose POST/api/v1/admin/usersProvision a competition user GET/api/v1/admin/stateCurrent controls, markets, messages, and persistence POST/api/v1/admin/trading/startEnable trading submissions POST/api/v1/admin/trading/stopDisable trading submissions GET/api/v1/admin/marketsList markets POST/api/v1/admin/marketsCreate or replace a market PATCH/api/v1/admin/markets/{market_id}Update market status or limits DELETE/api/v1/admin/markets/{market_id}Delete a market with no open orders POST/api/v1/admin/markets/{market_id}/settleSettle a market at a given price POST/api/v1/admin/config/loadBulk-load exchange config and market definitions GET/api/v1/admin/messagesRecent admin messages POST/api/v1/admin/messagesSend a broadcast or user-targeted admin message POST/api/v1/admin/users/resetClear all user positions, orders, and fills GET/api/v1/admin/leaderboardLeaderboard snapshot
Provisions a new competition user and returns their profile including the assigned API key. Request body Unique username for the new trader. Must not be empty.
Response fields UUID assigned to the trader.
The provisioned username.
API key prefixed with exch_. Share this with the trader.
ISO 8601 creation timestamp.
curl \ -X POST \ -H "Authorization: Bearer ADMIN_API_TOKEN" \ -H "content-type: application/json" \ https://exchange.jamesxu.dev/api/v1/admin/users \ -d '{"username":"team-alpha"}'
{ "profile" : { "trader_id" : "9d64e278-8b56-46e9-9cab-18c5b22f2fb9" , "username" : "team-alpha" , "api_key" : "exch_1d4208be6fa84b8cb0a2e5cfa9508d5f" , "created_at" : "2026-03-18T15:27:42.159901Z" } }
Returns the current exchange state including trading controls, configured markets, recent admin messages (up to 50), and persistence status. curl \ -H "Authorization: Bearer ADMIN_API_TOKEN" \ https://exchange.jamesxu.dev/api/v1/admin/state
Response fields: controls (ExchangeControls), markets (array of MarketDefinition), recent_messages (up to 50 AdminMessageEntry), persistence (PersistenceStatus).
POST /api/v1/admin/trading/start
Enables order submissions exchange-wide. Traders can submit orders once this is set. curl \ -X POST \ -H "Authorization: Bearer ADMIN_API_TOKEN" \ https://exchange.jamesxu.dev/api/v1/admin/trading/start
POST /api/v1/admin/trading/stop
Disables order submissions exchange-wide. All new order, amend, and cancel requests will be rejected until trading is re-enabled. curl \ -X POST \ -H "Authorization: Bearer ADMIN_API_TOKEN" \ https://exchange.jamesxu.dev/api/v1/admin/trading/stop
GET /api/v1/admin/markets
Returns all configured markets including full metadata and status. curl \ -H "Authorization: Bearer ADMIN_API_TOKEN" \ https://exchange.jamesxu.dev/api/v1/admin/markets
POST /api/v1/admin/markets
Creates or replaces a market definition. If a market with the same market_id already exists, it is replaced. Request body Market symbol in BASE-QUOTE format, e.g. BTC-USD.
Optional. Human-readable market name. Falls back to market_id if omitted.
Minimum price increment. All order prices must be a multiple of this value.
Minimum order quantity. Orders below this are rejected.
Optional reference price used for marking when no trades have occurred.
Whether the market is open for trading on creation. true creates an enabled market, false creates a disabled one.
curl \ -X POST \ -H "Authorization: Bearer ADMIN_API_TOKEN" \ -H "content-type: application/json" \ https://exchange.jamesxu.dev/api/v1/admin/markets \ -d '{ "market_id":"BTC-USD", "display_name":"Bitcoin", "base_asset":"BTC", "quote_asset":"USD", "tick_size":1, "min_order_quantity":1, "reference_price":100, "enabled":true }'
PATCH /api/v1/admin/markets/{market_id}
Updates a market’s status or limits. Only fields provided in the request body are changed. Path parameters Market symbol, e.g. BTC-USD.
curl \ -X PATCH \ -H "Authorization: Bearer ADMIN_API_TOKEN" \ -H "content-type: application/json" \ https://exchange.jamesxu.dev/api/v1/admin/markets/BTC-USD \ -d '{"enabled":false}'
DELETE /api/v1/admin/markets/{market_id}
Deletes a market. The market must have no open orders. Path parameters curl \ -X DELETE \ -H "Authorization: Bearer ADMIN_API_TOKEN" \ https://exchange.jamesxu.dev/api/v1/admin/markets/BTC-USD
POST /api/v1/admin/markets/{market_id}/settle
Settles a market. Cancels all resting orders, then closes every trader’s net position at the supplied settlement price, realizing PnL. Positions are flattened to zero after settlement. Path parameters Request body The admin-determined true value per share. PnL is realized against each trader’s signed net position at this price. Must be greater than zero.
Optional. Custom announcement text broadcast to all WebSocket clients after settlement. Defaults to a generated message if omitted.
curl \ -X POST \ -H "Authorization: Bearer ADMIN_API_TOKEN" \ -H "content-type: application/json" \ https://exchange.jamesxu.dev/api/v1/admin/markets/BTC-USD/settle \ -d '{"settlement_price":150}'
{ "market" : { "market_id" : "BTC-USD" , "status" : "settled" , "settlement_price" : 150 }, "canceled_orders" : 5 , "affected_traders" : 3 , "settled_quantity" : 200 , "settlement_price" : 150 }
POST /api/v1/admin/config/load
Bulk-loads exchange configuration and market definitions. Use this to initialize or replace the full exchange state in one call. Request body Optional. Set to true or false to control trading. Omit to leave the current value unchanged.
Array of market definitions. Each entry uses the same shape as POST /api/v1/admin/markets.
curl \ -X POST \ -H "Authorization: Bearer ADMIN_API_TOKEN" \ -H "content-type: application/json" \ https://exchange.jamesxu.dev/api/v1/admin/config/load \ -d '{"markets":[{"market_id":"BTC-USD","display_name":"Bitcoin","base_asset":"BTC","quote_asset":"USD","tick_size":1,"min_order_quantity":1,"reference_price":100,"enabled":true}]}'
GET /api/v1/admin/messages
Returns recent admin messages sent to traders. Query parameters Optional. Maximum number of messages to return. Defaults to 50.
curl \ -H "Authorization: Bearer ADMIN_API_TOKEN" \ "https://exchange.jamesxu.dev/api/v1/admin/messages?limit=20"
POST /api/v1/admin/messages
Sends a broadcast or user-targeted admin message. Messages can be scoped to all traders or a specific username. Request body Optional. Username to send the message to. null broadcasts to all traders.
Optional. Market context for the message.
Severity level: info, warning, or critical.
Optional. Short message title.
curl \ -X POST \ -H "Authorization: Bearer ADMIN_API_TOKEN" \ -H "content-type: application/json" \ https://exchange.jamesxu.dev/api/v1/admin/messages \ -d '{ "target_username": null, "market": "BTC-USD", "level": "info", "title": "Desk notice", "body": "Trading will stop in five minutes." }'
POST /api/v1/admin/users/reset
Clears all user positions, open orders, and fills exchange-wide. This is a destructive operation intended for resetting between competition rounds. This operation is irreversible. All trader positions, open orders, and fills are permanently deleted.
curl \ -X POST \ -H "Authorization: Bearer ADMIN_API_TOKEN" \ https://exchange.jamesxu.dev/api/v1/admin/users/reset
{ "cleared_orders" : 12 , "cleared_positions" : 8 , "cleared_fills" : 34 }
GET /api/v1/admin/leaderboard
Returns a leaderboard snapshot with all traders ranked by marked net PnL. Useful for competition scoring and monitoring. Query parameters Optional. Maximum number of rows to return. Omit to return all traders.
curl \ -H "Authorization: Bearer ADMIN_API_TOKEN" \ "https://exchange.jamesxu.dev/api/v1/admin/leaderboard?limit=20"
Data model notes
side is BUY or SELLprice, quantity, and remaining are unsigned 64-bit integers (u64)The per-market net position limit is +/-1000
Traders can sell from flat and go short; order admission is based on worst-case net exposure if all resting open orders were to execute
Realized PnL is tracked on positions; no pre-seeded inventory or cash balance is required to open a long or short position
Leaderboard ranking uses settled prices, orderbook marks, or market reference prices
Pagination is not yet implemented