Market Maker API

Service & credentials

Hard limits & rate limiting

Batch place size

1–15Above the cap the whole batch returns 400.

Batch cancel ids

1–1000Duplicate ids are removed before counting.

Place bucket rate / burst

40/s · 60Per account, independent of IP rate limiting. A batch spends one token per order.

Cancel bucket rate / burst

80/s · 120Twice the place bucket.

Heartbeat cadence / timeout

5s / 10sOn timeout all open orders under the key are cancelled with cancelReason = HEARTBEAT_TIMEOUT.

Rate-limit headers

X-Fathom-RateLimit-*-Remaining, -Reset, -Tier. A 429 response also carries Retry-After.

These values and the limits the server enforces come from one shared constant (@fathom/exchange-sdk).

The market-making loop (runnable)

The Quickstart on the overview page walks the retail order loop. The market-making loop is a different one: get a key → confirm your tier → register the heartbeat → quote both sides in a batch → replace quotes → hit the kill switch before you stop. Below is the minimal runnable skeleton of that loop — set two environment variables and it runs.

#!/usr/bin/env python3
"""做市闭环最小骨架。运行前：export PX_BASE_URL=... PX_API_KEY=pxk_..."""
import os, time, requests

BASE = os.environ["PX_BASE_URL"]
H = {"X-PX-Key": os.environ["PX_API_KEY"], "Content-Type": "application/json"}
MARKET = "px-btc-120k"

def call(method, path, body=None):
    r = requests.request(method, BASE + path, headers=H, json=body, timeout=5)
    if r.status_code == 429:          # 桶内代币不足：整批被拒，退避后重发整批
        time.sleep(1.0)
        return None
    r.raise_for_status()
    return r.json()

# 1. 登记心跳。超过窗口未续期，服务端撤掉你名下全部挂单（cancel-on-disconnect）
call("POST", "/v1/px/heartbeats")

open_ids = []
try:
    while True:
        # 2. 撤掉上一轮的报价。单市场撤单比逐张撤便宜，也避免撤单频率打满
        if open_ids:
            call("DELETE", "/v1/px/orders/by-market", {"marketId": MARKET})
            open_ids = []

        # 3. 双边批量报价。逐张成败，results 按请求顺序返回
        res = call("POST", "/v1/px/orders/batch", {"orders": [
            {"marketId": MARKET, "outcome": "A", "side": "BUY",  "orderType": "LIMIT",
             "limitPriceE6": "520000", "quantityE6": "100000000", "tif": "GTC",
             "clientOrderId": f"bid-{int(time.time())}"},
            {"marketId": MARKET, "outcome": "A", "side": "SELL", "orderType": "LIMIT",
             "limitPriceE6": "540000", "quantityE6": "100000000", "tif": "GTC",
             "clientOrderId": f"ask-{int(time.time())}"},
        ]})
        if res:
            open_ids = [r["order"]["orderId"] for r in res["results"] if r["ok"]]
            for r in res["results"]:
                if not r["ok"]:
                    print("rejected:", r["code"], r["message"])

        # 4. 续心跳，频率取窗口的一半以内，给网络抖动留余量
        call("POST", "/v1/px/heartbeats")
        time.sleep(5)
finally:
    # 5. 收工：kill switch 撤掉全部挂单，再注销心跳登记（注销本身不触发全撤）
    call("DELETE", "/v1/px/orders/all")
    call("DELETE", "/v1/px/heartbeats")

Deliberately absent: reconnect backoff, book subscription and exposure checks. All three are coupled to your strategy, and shipping a generic implementation here would only mislead.

Endpoint index

Each endpoint has its own page with behaviour rules, authorization, and request and response examples.

Onboarding sequence

1. Log in and create a key under Settings → API keys with the read, place and cancel scopes. The secret is returned once, in the create response.
2. Read the market and its tick: GET /v1/px/markets/:marketId.
3. Start the heartbeat loop (every 5s). Heartbeats come before orders.
4. Subscribe to the real-time stream. After a reconnect, call GET /v1/px/orders first, then consume new events.
5. Rest the ladder with POST /v1/px/orders/batch, at most 15 orders per batch.
6. Re-price: cancel, then place again. Orders cannot be edited.
7. To stop: DELETE /v1/px/orders/all, then DELETE /v1/px/heartbeats.

Error codes

Inside a batch place, per-order rejections use the same codes in results[i].code; per-id cancel reasons appear in notCanceled.