Market Maker Guide¶

from decimal import Decimal
import json, time, uuid
import requests
from pathlib import Path
from eth_account import Account
from eth_account.messages import encode_typed_data

API     = "https://api.testnet.sera.cx/api/v1"
DOMAIN  = {
    "name": "Sera",
    "version": "1",
    "chainId": 11155111,                                          # Sepolia
    "verifyingContract": "0x83475A1bD98a8DC2DCd507A747e4DC85da241D6e",
}

PRIVATE_KEY = "0x...your wallet key..."                            # signer
API_KEY     = "sera_..."                                           # see Authentication
API_SECRET  = "..."
OWNER       = Account.from_key(PRIVATE_KEY).address

AUTH = {"Authorization": f"Bearer {API_KEY}:{API_SECRET}"}

ORDER_TYPES = {
    "Order": [
        {"name": "user",                 "type": "address"},
        {"name": "expiration",           "type": "uint48"},
        {"name": "feeBps",               "type": "uint48"},
        {"name": "recipient",            "type": "address"},
        {"name": "fromToken",            "type": "address"},
        {"name": "toToken",              "type": "address"},
        {"name": "fromAmount",           "type": "uint256"},
        {"name": "toAmount",             "type": "uint256"},
        {"name": "initialDepositAmount", "type": "uint256"},
        {"name": "uuid",                 "type": "uint256"},
    ]
}

CANCEL_ORDER_TYPES = {
    "CancelOrder": [
        {"name": "owner",   "type": "address"},
        {"name": "orderId", "type": "uint256"},
    ]
}

health_response = requests.get(f"{API}/health", timeout=10)
health_response.raise_for_status()
EXECUTOR_ID = int(health_response.json()["executor_id"])

def compose_uuid(order_id: str, executor_id: int = EXECUTOR_ID,
                 leg_id: int = 0, group_uuid: str | None = None) -> int:
    """Pack a UUID4 string into the on-chain composite uint256."""
    oid    = int(uuid.UUID(order_id))
    gsrc   = int(uuid.UUID(group_uuid)) if group_uuid else oid
    gid    = gsrc >> 16                                            # top 112 of 128
    return (executor_id << 252) | (oid << 124) | (gid << 12) | leg_id

def new_order_id() -> str:
    return str(uuid.uuid4())

response = requests.get(f"{API}/markets", timeout=10)
response.raise_for_status()
MARKET = next(m for m in response.json()["markets"]
              if {m["base_symbol"], m["quote_symbol"]} == {"USDC", "EURC"})
BASE = {"address": MARKET["base_address"], "decimals": MARKET["base_decimals"]}
QUOTE = {"address": MARKET["quote_address"], "decimals": MARKET["quote_decimals"]}

def place_order(side: str, base: dict, quote: dict,
                amount: Decimal, price: Decimal,
                expiration: int) -> dict:
    order_id = new_order_id()
    uuid_int = compose_uuid(order_id)                              # deployment executor ID

    preview_request = {
        "owner_address": OWNER, "side": side,
        "amount": format(amount, "f"), "price": format(price, "f"),
        "order_type": "limit", "from_address": base["address"],
        "to_address": quote["address"], "order_id": order_id,
        "uuid_int": str(uuid_int), "expiration": expiration,
    }
    response = requests.post(f"{API}/orders/preview", json=preview_request, timeout=10)
    response.raise_for_status()
    preview = response.json()
    signable = encode_typed_data(DOMAIN, preview["eip712_types"], preview["eip712_order"])
    signature = Account.from_key(PRIVATE_KEY).sign_message(signable).signature.hex()

    wire = {
        "owner_address": OWNER,
        "side":          side,
        "amount":        preview["normalized_amount"],
        "price":         preview["normalized_price"],
        "order_type":    "limit",
        "from_address":  base["address"],                           # base, NOT spend
        "to_address":    quote["address"],                          # quote, NOT receive
        "order_id":      order_id,
        "uuid_int":      str(uuid_int),
        "signature":     "0x" + signature.removeprefix("0x"),
        "expiration":    expiration,
    }
    journal = Path("order-requests")
    journal.mkdir(mode=0o700, exist_ok=True)
    saved_path = journal / f"{order_id}.json"
    with saved_path.open("x", encoding="utf-8") as saved:
        json.dump(wire, saved)
    print(f"Saved order request: {saved_path}")
    r = requests.post(f"{API}/orders", headers={**AUTH, "Content-Type": "application/json"},
                      data=json.dumps(wire), timeout=10)
    if r.status_code != 201:
        detail = r.json().get("detail")
        raise RuntimeError(f"HTTP {r.status_code}, order {order_id}: {detail}")
    return {"order_id": order_id, "uuid_int": str(uuid_int)}

placed = place_order("bid", BASE, QUOTE, Decimal("1000"),
                     Decimal("1"), int(time.time()) + 3600)
print("placed:", placed)

def cancel_order(order_id: str, uuid_int: int) -> None:
    signable = encode_typed_data(
        DOMAIN, CANCEL_ORDER_TYPES,
        {"owner": OWNER, "orderId": uuid_int},
    )
    signature = Account.from_key(PRIVATE_KEY).sign_message(signable).signature.hex()
    r = requests.post(
        f"{API}/orders/cancel",
        headers={**AUTH, "Content-Type": "application/json"},
        data=json.dumps({
            "owner_address": OWNER,
            "order_id":      order_id,
            "uuid_int":      str(uuid_int),
            "signature":     "0x" + signature.removeprefix("0x"),
        }),
        timeout=10,
    )
    if r.status_code == 429:
        raise RuntimeError("cancel rejected (cooldown or rate limit) — inspect response and retry later")
    r.raise_for_status()

cancel_order(placed["order_id"], int(placed["uuid_int"]))

def get_mid(pair: str) -> Decimal:
    """Return the current mid price for `pair`.

    Implement against your own data feed — internal pricing service,
    Bloomberg, an aggregator REST API, etc. The output must be a
    Decimal price expressed as quote-per-base (e.g. EURC/USDC = 1.085).
    """
    raise NotImplementedError("Wire up your pricing feed here.")

SPREAD_BPS = Decimal("5")     # 5 bps either side
DRIFT_BPS  = Decimal("3")     # requote only when mid moves > 3 bps
POLL_S     = 2.0
QTY        = Decimal("1000")  # base units per side

open_bid = open_ask = None
last_mid = None

while True:
    try:
        mid = get_mid(MARKET["symbol"])
        if last_mid is not None and \
           abs(mid - last_mid) / last_mid * 10_000 <= DRIFT_BPS:
            time.sleep(POLL_S); continue

        # Cancel-first, then place — avoids self-match across the requote.
        if open_bid: cancel_order(**open_bid)
        if open_ask: cancel_order(**open_ask)
        open_bid = open_ask = None

        half   = SPREAD_BPS / Decimal(10_000)
        bid_px = (mid * (Decimal(1) - half)).quantize(Decimal("0.0001"))
        ask_px = (mid * (Decimal(1) + half)).quantize(Decimal("0.0001"))
        expiry = int(time.time()) + 3600

        placed_bid = place_order("bid", BASE, QUOTE, QTY, bid_px, expiry)
        open_bid = {"order_id": placed_bid["order_id"], "uuid_int": int(placed_bid["uuid_int"])}
        placed_ask = place_order("ask", BASE, QUOTE, QTY, ask_px, expiry)
        open_ask = {"order_id": placed_ask["order_id"], "uuid_int": int(placed_ask["uuid_int"])}
        last_mid   = mid
    except RuntimeError as e:
        # HTTP rejection, including typed business errors and string details.
        print("place/cancel error; reconcile saved orders before restarting:", e)
        break
    except requests.RequestException as e:
        print("network error; reconcile saved orders before restarting:", e)
        break
    time.sleep(POLL_S)

def place_vl_batch(legs: list[dict]) -> dict:
    """legs: list of {side, base, quote, amount, price, expiration}."""
    leg_0_uuid = new_order_id()                                    # source of group_id
    signed_legs = []
    for i, leg in enumerate(legs):
        order_id = leg_0_uuid if i == 0 else new_order_id()
        uuid_int = compose_uuid(order_id, executor_id=EXECUTOR_ID,
                                leg_id=i, group_uuid=leg_0_uuid)

        base, quote = leg["base"], leg["quote"]
        response = requests.post(f"{API}/orders/preview", json={
            "owner_address": OWNER, "side": leg["side"],
            "amount": format(leg["amount"], "f"), "price": format(leg["price"], "f"),
            "order_type": "limit", "from_address": base["address"],
            "to_address": quote["address"], "order_id": order_id,
            "uuid_int": str(compose_uuid(order_id)), "expiration": leg["expiration"],
        }, timeout=10)
        response.raise_for_status()
        preview = response.json()
        order_struct = {**preview["eip712_order"], "uuid": str(uuid_int)}
        signable = encode_typed_data(DOMAIN, preview["eip712_types"], order_struct)
        sig = Account.from_key(PRIVATE_KEY).sign_message(signable).signature.hex()
        signed_legs.append({
            "owner_address": OWNER,
            "side":          leg["side"],
            "amount":        preview["normalized_amount"],
            "price":         preview["normalized_price"],
            "order_type":    "limit",
            "from_address":  base["address"],
            "to_address":    quote["address"],
            "order_id":      order_id,
            "uuid_int":      str(uuid_int),
            "signature":     "0x" + sig.removeprefix("0x"),
            "expiration":    leg["expiration"],
        })

    wire = {"orders": signed_legs}
    journal = Path("vl-requests")
    journal.mkdir(mode=0o700, exist_ok=True)
    saved_path = journal / f"{leg_0_uuid}.json"
    with saved_path.open("x", encoding="utf-8") as saved:
        json.dump(wire, saved)
    print(f"Saved VL request: {saved_path}")
    r = requests.post(
        f"{API}/orders/vl/batch",
        headers={**AUTH, "Content-Type": "application/json"},
        data=json.dumps(wire),
        timeout=10,
    )
    r.raise_for_status()
    return r.json()