交易对（Markets）

交易对元数据：tick size、lot size、最小名义金额、手续费、上市状态。

列出所有交易对

公开接口，返回每个交易对的完整配置。

GET /spot/markets

响应 — 200 OK

[
  {
    "id":            "DFUSDT",
    "base_token":    "DF",
    "quote_token":   "USDT",
    "tick_size":     "0.0001",
    "lot_size":      "0.01",
    "min_notional":  "1",
    "maker_fee_bps": 0,
    "taker_fee_bps": 0,
    "status":        "listed"
  }
]

字段

字段	类型	说明
id	string	全套 API 使用的 symbol（如 DFUSDT）
base_token / quote_token	string	代币符号。notional = price × quantity（以 quote 计）
tick_size	string	价格的最小步进。price % tick_size != 0 → INVALID_TICK
lot_size	string	数量的最小步进。quantity % lot_size != 0 → INVALID_LOT
min_notional	string	price × quantity 的最小值。低于 → BELOW_MIN_NOTIONAL
maker_fee_bps / taker_fee_bps	number	基点（1 bps = 0.01%）。MVP testnet 默认都为 0
status	string	listed（开放交易）/ halted（可撤单，不收新单）/ delisted（终态 —— 切换时自动撤所有挂单）

---

Admin：创建交易对

新建一个交易对。id 冲突幂等 —— 返回 409 MARKET_EXISTS。

仅 Admin

需要 X-API-Key 头部，值匹配服务端 ADMIN_API_KEY env。

POST /admin/spot/markets

请求体

{
  "id":            "DFUSDT",
  "base_token":    "DF",
  "quote_token":   "USDT",
  "tick_size":     "0.0001",
  "lot_size":      "0.01",
  "min_notional":  "1",
  "maker_fee_bps": 0,
  "taker_fee_bps": 0
}

字段	类型	必填	备注
id	string	是	唯一。约定：BASE + QUOTE
tick_size / lot_size / min_notional	string / number	是	必须 > 0
maker_fee_bps / taker_fee_bps	number	是	必须 >= 0

新建时 status 总是 listed。要 halt 或 delist 用下面的 status 接口。

响应 — 200 OK

{ "ok": true, "id": "DFUSDT" }

写库后 engine 会收到 ReloadMarket 信号，无需重启就能刷新内存里的 MarketCache。

---

Admin：更新交易对配置

可以补丁 tick_size / lot_size / min_notional / maker_fee_bps / taker_fee_bps 的任意子集。省略的字段保持不变。

PATCH /admin/spot/markets/:id

请求体（字段都是可选的）

{
  "tick_size":     "0.001",
  "maker_fee_bps": 5,
  "taker_fee_bps": 10
}

响应 — 200 OK

{ "ok": true, "id": "DFUSDT" }

已挂的订单不会按新的 tick/lot/min_notional 追溯校验。只有新订单才走新规则。

---

Admin：改状态

允许的转换：listed → halted、halted → listed、listed | halted → delisted。delisted 是终态。

PATCH /admin/spot/markets/:id/status

请求体

{ "status": "halted" }

状态语义

status	下新单	撤现有单	现有挂单
listed	接受	接受	不变
halted	拒绝 MARKET_HALTED	接受	保留
delisted	拒绝 MARKET_DELISTED	不适用	被清空 —— 状态翻转之前自动撤销所有挂单并解冻资金

响应 — 200 OK

{ "ok": true, "id": "DFUSDT", "status": "halted" }

---

Admin：直接 Credit 余额（仅 testnet）

直接给用户的 spot 钱包加余额，绕开链上充值流程 —— 用于 testnet 给测试账号铺资金。

仅 Testnet

当服务端 env 没有 TESTNET_ONLY=true 时返回 404 DISABLED。主网环境就算 auth 正确也答 404。

POST /admin/spot/balances/credit

请求体

{
  "user_address": "0xab12...",
  "token":        "DF",
  "amount":       "10000",
  "reason":       "seed mm bot inventory"
}

字段	类型	必填	备注
user_address	string	是	服务端会转小写
token	string	是	DF 或 USDT
amount	string / number	是	十进制，必须 > 0。加到 available，frozen 不变
reason	string	否	自由文本审计备注

余额更新和 spot_admin_credits 审计行的写入在同一个 DB 事务里完成。

响应 — 200 OK

{ "ok": true }

代码示例

import requests

BASE     = "https://api-sepolia.p99.world/api/v1"
ADMIN_K  = "your_admin_api_key"

# 1. 创建唯一的交易对
requests.post(f"{BASE}/admin/spot/markets",
    headers={"X-API-Key": ADMIN_K, "Content-Type": "application/json"},
    json={"id": "DFUSDT", "base_token": "DF", "quote_token": "USDT",
          "tick_size": "0.0001", "lot_size": "0.01", "min_notional": "1",
          "maker_fee_bps": 0, "taker_fee_bps": 0})

# 2. 给测试账号铺资金（仅 testnet）
for token, amt in [("DF", "10000"), ("USDT", "10000")]:
    requests.post(f"{BASE}/admin/spot/balances/credit",
        headers={"X-API-Key": ADMIN_K, "Content-Type": "application/json"},
        json={"user_address": "0xab12...", "token": token,
              "amount": amt, "reason": "manual test"})

# 3. 看一下当前生效的市场
print(requests.get(f"{BASE}/spot/markets").json())