Market Maker API

Complete guide for automated market makers integrating with the sim-trading platform.

Overview

The Market Maker API lets automated trading systems place and dynamically reprice two-sided liquidity orders (bid + ask) as a single atomic pair. The core workflow is:

Authentication

All API calls require a Bearer token in the Authorization header.

copyAuthorization: Bearer <token>

Tokens do not expire by session but may be revoked. Re-authenticate if you receive 401.

Base URL

copyhttp://<host>:3001

All paths in this document are relative to the base URL.

Step 1 — Authenticate

Request

copy{
  "username": "your_username",
  "password": "your_password"
}

Response

copy{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": { "id": "...", "username": "...", "role": "..." }
}

Step 2 — Place a Liquidity Pair

Place two orders with the same pairId in meta. The pairId is a string you generate (e.g. a UUID). Use it to reprice or cancel the pair later.

Request Body

Pricing Modes

Example — place a ±0.5% pair

copy# 1. Generate a pair ID
PAIR_ID="pair_$(date +%s)_$(head /dev/urandom | tr -dc a-z0-9 | head -c6)"

# 2. Place buy side
curl -s -X POST http://HOST:3001/api/trading/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"symbol\": \"BTCUSDT\",
    \"side\": \"buy\",
    \"type\": \"liquidity\",
    \"quantity\": 0.01,
    \"leverage\": 1,
    \"liquidityConfig\": { \"levelOffset\": 1, \"ttlSeconds\": 300 },
    \"priceMode\": \"percentage\",
    \"pricePercent\": 0.5,
    \"meta\": \"{\\\"pairId\\\": \\\"$PAIR_ID\\\"}\"
  }"

# 3. Place sell side (same pairId)
curl -s -X POST http://HOST:3001/api/trading/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"symbol\": \"BTCUSDT\",
    \"side\": \"sell\",
    \"type\": \"liquidity\",
    \"quantity\": 0.01,
    \"leverage\": 1,
    \"liquidityConfig\": { \"levelOffset\": 1, \"ttlSeconds\": 300 },
    \"priceMode\": \"percentage\",
    \"pricePercent\": 0.5,
    \"meta\": \"{\\\"pairId\\\": \\\"$PAIR_ID\\\"}\"
  }"

copyconst BASE = 'http://HOST:3001';
const headers = {
  'Content-Type': 'application/json',
  'Authorization': `Bearer ${token}`,
};

const pairId = `pair_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;

async function placeLiquidityPair({ symbol, quantity, pricePercent, ttlSeconds = 300 }) {
  const base = { symbol, type: 'liquidity', quantity, leverage: 1,
    liquidityConfig: { levelOffset: 1, ttlSeconds },
    priceMode: 'percentage', pricePercent,
    meta: JSON.stringify({ pairId }),
  };

  const [buyRes, sellRes] = await Promise.all([
    fetch(`${BASE}/api/trading/orders`, { method: 'POST', headers, body: JSON.stringify({ ...base, side: 'buy' }) }),
    fetch(`${BASE}/api/trading/orders`, { method: 'POST', headers, body: JSON.stringify({ ...base, side: 'sell' }) }),
  ]);

  const [buy, sell] = await Promise.all([buyRes.json(), sellRes.json()]);
  return { pairId, buyOrderId: buy.order.id, sellOrderId: sell.order.id };
}

const pair = await placeLiquidityPair({
  symbol: 'BTCUSDT',
  quantity: 0.01,
  pricePercent: 0.5,
});

Step 3 — Reprice

Call this to atomically cancel the existing pair and re-place at new absolute prices. Margin is released and re-frozen automatically.

Request Body

Response

copy{
  "success": true,
  "buyOrderId": "new-buy-order-uuid",
  "sellOrderId": "new-sell-order-uuid",
  "newBidPrice": 68000,
  "newAskPrice": 72000
}

Example

copycurl -s -X POST http://HOST:3001/api/liquidity/reprice \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pairId": "pair_1742123456_abc123",
    "newBidPrice": 68000,
    "newAskPrice": 72000
  }'

copyasync function reprice(pairId, newBidPrice, newAskPrice) {
  const res = await fetch(`${BASE}/api/liquidity/reprice`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ pairId, newBidPrice, newAskPrice }),
  });
  if (!res.ok) {
    const err = await res.json();
    throw new Error(err.error);
  }
  return res.json();
}

// Reprice every 10 seconds based on mid price
setInterval(async () => {
  const mid = await getMidPrice('BTCUSDT');  // your price feed
  const spread = mid * 0.005;               // 0.5% spread
  await reprice(currentPairId, mid - spread, mid + spread);
}, 10_000);

Cancel a Pair

Cancel either order by ID. The other side is automatically cancelled too.

copycurl -s -X DELETE http://HOST:3001/api/trading/orders/$BUY_ORDER_ID \
  -H "Authorization: Bearer $TOKEN"

Pair Lifecycle

Best Practices

Reprice frequency

• Recommended minimum interval: 1 second between reprice calls for the same pair.
• Rapid repricing (<500ms) is not blocked but increases margin churn and server load.
• For volatile markets, consider wider spreads instead of faster repricing.

pairId management

• Generate a new pairId for each pair placement (UUID or timestamp + random).
• After a reprice, the server generates a new internal pairId for the new orders. Your original pairId is consumed.
• Store the new buyOrderId / sellOrderId from the reprice response to track the live pair.

Margin management

• Both sides of a pair require margin. A pair of 0.01 BTC at 70,000 USDT with leverage=1 freezes ~1,400 USDT total.
• Reprice releases old margin and freezes new margin atomically — net change is typically <1 USDT (market price drift).
• Monitor availableBalance via GET /api/accounts/me to avoid margin failures.

Error handling

• Always handle 400 on reprice (pair already filled or cancelled).
• Re-authenticate on 401.
• Back off on 500 — do not retry in a tight loop.

Error Reference

Market Maker API v1.0  ·  sim-trading-pro  ·  Questions? Contact the platform operator.

External Symbol Price Feed

Push a reference price (last trade price) for a custom symbol. The price is broadcast to all connected clients and used for chart display and order matching. bid/ask spreads are formed by your liquidity orders, not this endpoint.

Request Body

Legacy format: { bid, ask } is also accepted — mid price is used automatically.

copy# Single push
curl -X POST http://HOST:3001/api/broker/price-feed \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"symbol":"XAUUSD","price":3275.50}'

# Continuous push script (bash)
TOKEN="YOUR_TOKEN"
while true; do
  PRICE=3275.50  # replace with your data source
  curl -s -X POST http://HOST:3001/api/broker/price-feed \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"symbol\":\"XAUUSD\",\"price\":$PRICE}" > /dev/null
  sleep 1
done

copyimport requests, time

BASE = "http://HOST:3001"
TOKEN = "YOUR_TOKEN"
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}

def push_price(symbol: str, price: float):
    requests.post(f"{BASE}/api/broker/price-feed",
                  headers=HEADERS,
                  json={"symbol": symbol, "price": price})

# Example: push every tick from your data source
while True:
    price = get_price_from_your_source()  # replace with your API
    push_price("XAUUSD", price)
    time.sleep(0.1)  # push every 100ms - backend throttles WS broadcast to 1/sec

copyconst BASE = "http://HOST:3001";
const TOKEN = "YOUR_TOKEN";

async function pushPrice(symbol, price) {
  await fetch(`${BASE}/api/broker/price-feed`, {
    method: "POST",
    headers: { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json" },
    body: JSON.stringify({ symbol, price }),
  });
}

// Push every tick - platform throttles broadcast automatically
setInterval(async () => {
  const price = await getFromYourSource(); // replace with your feed
  await pushPrice("XAUUSD", price);
}, 100);

Create Custom Symbol

Register a new tradeable symbol on the platform. After creation, the symbol appears in the market list immediately (page refresh required on client).

Request Body

copycurl -X POST http://HOST:3001/api/broker/symbols \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "XAUUSD",
    "displayName": "黃金/美元",
    "pricePrecision": 2,
    "qtyPrecision": 2,
    "minOrderSize": 0.01
  }'