SORDEX API 参考API Reference
返回应用Back to app

SORDEX API 参考API Reference

概览

SORDEX 是 BSC 主网(chainId 56)上的非托管现货订单簿 DEX。对接分三层:

  • 公开数据 REST / WebSocket:交易对、盘口、成交、K 线、聚合商标准数据。只读,无需鉴权。
  • 链上合约:挂单、撤单、改价、吃单、建对、做市金库充提,直接调合约,由钱包私钥签交易。资金安全只由链上保证。
  • 签名报价(做市):做市商用 EIP-712 离线签名报价提交到撮合层,改价零 gas;资金锁在做市金库,成交时原子交割。
读接口返回的是缓存视图,用于展示与路由,不作为资金真相;资金状态以链上为准。

Overview

SORDEX is a non-custodial spot order-book DEX on BSC mainnet (chainId 56). Integration spans three layers:

  • Public REST / WebSocket: pairs, order book, trades, candles, aggregator feeds. Read-only, no auth.
  • On-chain contracts: placing, cancelling, amending, taking, listing and vault deposits/withdrawals call contracts directly, signed by your wallet key. Fund safety is guaranteed only on-chain.
  • Signed quotes (market making): makers post EIP-712 off-chain quotes to the matching layer; repricing is gasless. Funds stay in the vault and settle atomically on fill.
Read endpoints return cached views for display and routing, not the source of truth for funds; fund state is authoritative on-chain.

基址 · 鉴权 · 限流

基址:https://sordexpro.com/api,所有路径拼在其后,返回 JSON。

鉴权:只读接口无需鉴权。做市报价按 报价准入规则,带 x-mm-key 请求头或满足金库余额条件。做市管理接口(申领 Key、托管订阅等)用钱包 EIP-712 签名鉴权,无账户密码体系。

限流(按 IP):

接口限额
/quote · /quote/batch120 / 分钟
/mm/issue · /mm/update-ips10 / 分钟
/mm/subscribe · /mm/unsubscribe60 / 分钟
/mm/contact5 / 分钟
/scan-token · /listing-meta10 / 分钟
/token-meta20 / 分钟

行情类只读接口为轻量缓存,实时数据请用 WebSocket 订阅,不要轮询。出错返回对应 HTTP 状态码与 {"error":"…"},详见 错误码。

Base · Auth · Limits

Base URL: https://sordexpro.com/api. Append each path; responses are JSON.

Auth: read endpoints need none. Quoting follows the quote admission rules — send an x-mm-key header or meet the vault-balance condition. Market-making management endpoints (key issuance, hosted subscription) authenticate by wallet EIP-712 signature; there are no account passwords.

Rate limits (per IP):

endpointlimit
/quote · /quote/batch120 / min
/mm/issue · /mm/update-ips10 / min
/mm/subscribe · /mm/unsubscribe60 / min
/mm/contact5 / min
/scan-token · /listing-meta10 / min
/token-meta20 / min

Market-data reads are lightly cached; subscribe to the WebSocket for live data instead of polling. Errors return the matching HTTP status and {"error":"…"}; see error codes.

交易对

GET/pairs无鉴权
列出全部交易对及参数,按活跃挂单数降序。
字段说明
pairId交易对编号
base / quote基础币 / 计价币合约地址(计价币固定 USDT)
baseSymbol / quoteSymbol符号
baseDecimals / quoteDecimals精度
tick / tickNum / tickDen价格最小变动;价格须为 tickNum/tickDen 的整数倍
minBaseQty / minNotional最小下单量 / 最小名义额(最小单位)
takerFeeBps / makerFeeBps吃单 / 挂单费率(基点,10 = 0.10%)
buyTaxBps / sellTaxBps项目方交易税率(基点)
openTime / isOpen / paused开放交易时间戳(秒,0=立即)/ 当前是否开放 / 是否暂停
logo / displayName链下展示信息(可能为 null)
listingComplete上币是否全部步骤完成
openOrders当前有效挂单数
GET /api/pairs

[{
  "pairId":"1", "base":"0x…", "quote":"0x55d3…7955",
  "baseSymbol":"DEMO", "quoteSymbol":"USDT", "baseDecimals":18, "quoteDecimals":18,
  "tick":0.01, "tickNum":"1", "tickDen":"100",
  "minBaseQty":"0", "minNotional":"0",
  "takerFeeBps":10, "makerFeeBps":0, "buyTaxBps":0, "sellTaxBps":0,
  "openTime":1793988678, "isOpen":false, "paused":false,
  "logo":null, "displayName":"Demo Coin", "listingComplete":true, "openOrders":0
}]

Pairs

GET/pairsno auth
List all pairs and their parameters, sorted by live open-order count.
fieldmeaning
pairIdpair id
base / quotebase / quote token address (quote is always USDT)
baseSymbol / quoteSymbolsymbols
baseDecimals / quoteDecimalsdecimals
tick / tickNum / tickDenprice step; price must be a multiple of tickNum/tickDen
minBaseQty / minNotionalmin order size / min notional (smallest units)
takerFeeBps / makerFeeBpstaker / maker fee in bps (10 = 0.10%)
buyTaxBps / sellTaxBpsproject transfer-tax rates (bps)
openTime / isOpen / pausedopening timestamp (sec, 0=immediate) / open now / paused
logo / displayNameoff-chain display info (may be null)
listingCompleteall listing steps done
openOrderslive open-order count
GET /api/pairs

[{
  "pairId":"1", "base":"0x…", "quote":"0x55d3…7955",
  "baseSymbol":"DEMO", "quoteSymbol":"USDT", "baseDecimals":18, "quoteDecimals":18,
  "tick":0.01, "tickNum":"1", "tickDen":"100",
  "minBaseQty":"0", "minNotional":"0",
  "takerFeeBps":10, "makerFeeBps":0, "buyTaxBps":0, "sellTaxBps":0,
  "openTime":1793988678, "isOpen":false, "paused":false,
  "logo":null, "displayName":"Demo Coin", "listingComplete":true, "openOrders":0
}]

盘口

GET/book?pairId=1无鉴权
仅链上锁仓单(A 单)聚合盘口。返回 {pairId, bids:[{price,qty}], asks:[{price,qty}], updatedAt}。
GET/mixed-book?pairId=1无鉴权
合并盘口:链上锁仓单(A 单)+ 做市商签名单(B 单),每档带来源标记。交易页用此接口。
字段说明
bids / asks每档 {price, qty, src};src 为 onchain / signed / onchain+signed
signedQuotes当前签名池内报价条数
updatedAt生成时间戳(毫秒)
GET /api/mixed-book?pairId=1

{
  "pairId":"1",
  "bids":[{"price":0.24, "qty":1200, "src":"signed"}],
  "asks":[{"price":0.26, "qty":900, "src":"onchain+signed"}],
  "signedQuotes":42, "updatedAt":1730990000000
}
GET/open-orders?pairId=1无鉴权
带订单 id 的全部有效挂单,供撮合 / 做市对账。返回 {pairId, orders:[{id, side, price, remainingBaseQty, seq}]}。

Order book

GET/book?pairId=1no auth
On-chain escrowed orders (A-orders) only. Returns {pairId, bids:[{price,qty}], asks:[{price,qty}], updatedAt}.
GET/mixed-book?pairId=1no auth
Merged book: on-chain A-orders + maker signed B-orders, each level tagged by source. Used by the trade UI.
fieldmeaning
bids / asksper level {price, qty, src}; src is onchain / signed / onchain+signed
signedQuotesquotes currently in the signed pool
updatedAtgeneration timestamp (ms)
GET /api/mixed-book?pairId=1

{
  "pairId":"1",
  "bids":[{"price":0.24, "qty":1200, "src":"signed"}],
  "asks":[{"price":0.26, "qty":900, "src":"onchain+signed"}],
  "signedQuotes":42, "updatedAt":1730990000000
}
GET/open-orders?pairId=1no auth
All live open orders with ids, for matching / MM reconciliation. Returns {pairId, orders:[{id, side, price, remainingBaseQty, seq}]}.

成交 · K 线 · 订单

GET/trades?pairId=1&limit=50无鉴权
最近成交。返回 {trades:[{price, qty, cost, fee, taker, txHash, block}]}(qty/cost/fee 为最小单位字符串)。
GET/candles?pairId=1&limit=200&bucketBlocks=50无鉴权
K 线,由链上成交按区块桶聚合,非外部行情源。返回 {candles:[{t,o,h,l,c,v}], source:"fills", bucketBlocks},t 为桶首区块号。
GET/orders?owner=0x…无鉴权
某地址的全部订单(跨交易对)。owner 必填。返回 {orders:[{id, pairId, side, price, originalBaseQty, remainingBaseQty, status}]}。

Trades · Candles · Orders

GET/trades?pairId=1&limit=50no auth
Recent trades. Returns {trades:[{price, qty, cost, fee, taker, txHash, block}]} (qty/cost/fee are smallest-unit strings).
GET/candles?pairId=1&limit=200&bucketBlocks=50no auth
Candles aggregated from on-chain fills by block bucket, not an external feed. Returns {candles:[{t,o,h,l,c,v}], source:"fills", bucketBlocks}; t is the bucket's first block number.
GET/orders?owner=0x…no auth
All orders for an address (across pairs). owner is required. Returns {orders:[{id, pairId, side, price, originalBaseQty, remainingBaseQty, status}]}.

聚合商标准数据

供 DexScreener / GeckoTerminal / DefiLlama / CoinGecko / CMC 收录的订单簿型交易所标准接口。ticker_id 规则为 BASE_USDT(符号大写)。只读、轻量缓存。

GET/public/pairs
[{ticker_id, base, target, pool_id}]
GET/public/tickers
[{ticker_id, base_currency, target_currency, pool_id, last_price, base_volume, target_volume, bid, ask, high, low, price_change_percent}],量为近 24h。
GET/public/stats
平台概览:{tvl, volume24h, pairs, updatedAt}。仅统计已完成上币的对,tvl 以 USDT 计。
GET/public/orderbook?ticker_id=BASE_USDT&depth=100
{ticker_id, timestamp, bids:[["price","qty"]], asks:[["price","qty"]]},depth 上限 500。
GET/public/historical_trades?ticker_id=BASE_USDT&type=buy&limit=200
[{trade_id, price, base_volume, target_volume, trade_timestamp, type}],type 可选 buy/sell,limit 上限 1000。
GET /api/public/tickers

[{
  "ticker_id":"DEMO_USDT", "base_currency":"DEMO", "target_currency":"USDT", "pool_id":"1",
  "last_price":0.25, "base_volume":1200, "target_volume":300,
  "bid":0.24, "ask":0.26, "high":0.27, "low":0.23, "price_change_percent":4.1
}]

Aggregator feed

Standard order-book exchange feeds for DexScreener / GeckoTerminal / DefiLlama / CoinGecko / CMC. ticker_id is BASE_USDT (upper-cased symbols). Read-only, lightly cached.

GET/public/pairs
[{ticker_id, base, target, pool_id}]
GET/public/tickers
[{ticker_id, base_currency, target_currency, pool_id, last_price, base_volume, target_volume, bid, ask, high, low, price_change_percent}]; 24h volumes.
GET/public/stats
Platform overview: {tvl, volume24h, pairs, updatedAt}. Counts completed listings only; tvl in USDT.
GET/public/orderbook?ticker_id=BASE_USDT&depth=100
{ticker_id, timestamp, bids:[["price","qty"]], asks:[["price","qty"]]}; depth capped at 500.
GET/public/historical_trades?ticker_id=BASE_USDT&type=buy&limit=200
[{trade_id, price, base_volume, target_volume, trade_timestamp, type}]; type is buy/sell, limit capped at 1000.
GET /api/public/tickers

[{
  "ticker_id":"DEMO_USDT", "base_currency":"DEMO", "target_currency":"USDT", "pool_id":"1",
  "last_price":0.25, "base_volume":1200, "target_volume":300,
  "bid":0.24, "ask":0.26, "high":0.27, "low":0.23, "price_change_percent":4.1
}]

代币检测

GET/token-meta?token=0x…无鉴权
链上名称 / 符号 / 精度 / 总量 + logo 候选链接 + 安全检测结论。返回 {token, name, symbol, decimals, totalSupply, logoCandidates, verdict, risks, summary}。
GET/scan-token?token=0x…无鉴权
完整安全检测报告:抽税 / 蜜罐、黑名单、可增发、可暂停、可升级、持仓集中度等风险项与结论(verdict: pass / review / block)。只读,不花 gas。
GET /api/token-meta?token=0x0E09…cE82

{
  "token":"0x0E09…cE82", "name":"PancakeSwap Token", "symbol":"Cake",
  "decimals":18, "totalSupply":"…", "logoCandidates":["https://…/logo.png"],
  "verdict":"pass", "risks":[]
}
检测为只读启发式,不覆盖全部攻击面(如成交后才开启的黑名单),请自行复核。

Token checks

GET/token-meta?token=0x…no auth
On-chain name / symbol / decimals / supply + candidate logo URLs + safety verdict. Returns {token, name, symbol, decimals, totalSupply, logoCandidates, verdict, risks, summary}.
GET/scan-token?token=0x…no auth
Full safety report: transfer tax / honeypot, blacklist, mintable, pausable, upgradeable, holder concentration, with a verdict (pass / review / block). Read-only, no gas.
GET /api/token-meta?token=0x0E09…cE82

{
  "token":"0x0E09…cE82", "name":"PancakeSwap Token", "symbol":"Cake",
  "decimals":18, "totalSupply":"…", "logoCandidates":["https://…/logo.png"],
  "verdict":"pass", "risks":[]
}
The scan is a read-only heuristic and does not cover every attack (e.g. a blacklist switched on only after trading). Verify independently.

WebSocket

WS/ws无鉴权
实时推送,无需轮询。消息有三种:{type:"hello", …统计}(连接成功即收,重连后也会收到);{type:"update", block, pairs}(盘口、成交或做市报价有变化;pairs 是受影响的交易对 id 数组,null 表示全部),收到后再用 REST 拉取你关心的数据;{type:"hb"}(每 25 秒一次心跳,超过 70 秒没收到任何消息请主动重连)。同一 IP 最多 20 条连接;断线请指数退避重连,重连成功后先拉一次最新数据以补上断线期间的变化。
const ws = new WebSocket("wss://sordexpro.com/api/ws");
ws.onmessage = (e) => {
  const ev = JSON.parse(e.data);
  // { type:"hello" } | { type:"update", block, pairs:["1"]|null } | { type:"hb" }
  if (ev.type === "update") { /* 再用 REST 拉取变化的数据 */ }
};

WebSocket

WS/wsno auth
Live push, so you do not need to poll. Three message types: {type:"hello", …stats} (sent on connect, and again after a reconnect); {type:"update", block, pairs} (the book, trades or maker quotes changed; pairs is an array of affected pair ids, null means all) – fetch what you need over REST when it arrives; and {type:"hb"} (a heartbeat every 25 seconds; if you receive nothing for 70 seconds, reconnect). At most 20 connections per IP. Reconnect with exponential backoff, and refetch the latest data once after reconnecting to cover the gap.
const ws = new WebSocket("wss://sordexpro.com/api/ws");
ws.onmessage = (e) => {
  const ev = JSON.parse(e.data);
  // { type:"hello" } | { type:"update", block, pairs:["1"]|null } | { type:"hb" }
  if (ev.type === "update") { /* then fetch the changed data over REST */ }
};

做市商接入模型

做市商有两种资金托管模式,报价准入规则不同:

  • 金库做市(VAULT):把流动性充入 MMCollateralVault。该 maker 在对应交易对金库有可用余额时,报价无需 API Key。
  • 授权额度做市(ALLOWANCE):资金留在钱包、只对合约 approve。此模式报价必须带 API Key。

API Key 为自助申领:用资金地址 EIP-712 签名即时领取,绑定 maker 地址 + IP 白名单。Key 只是报价准入凭证,不托管资金、不能提现、不能替别的地址报价。详见 报价准入。

Market-making access model

Makers run under one of two custody modes, with different quote-admission rules:

  • Vault custody (VAULT): deposit liquidity into MMCollateralVault. When the maker has available balance in the pair's vault, quoting needs no API key.
  • Allowance custody (ALLOWANCE): funds stay in the wallet with an on-chain approval. Quoting in this mode requires an API key.

Keys are self-issued: sign once with EIP-712 from the funding address to receive one, bound to the maker address + an IP allowlist. A key is a quote-admission credential only — it custodies no funds, cannot withdraw, and cannot quote for another address. See quote admission.

申领与轮换 Key

POST/mm/issueEIP-712 签名
自助申领 API Key。同一 maker 再次申领即轮换,旧 Key 立即失效、其在池旧报价一并清除。明文 Key 仅此一次返回。
字段说明
maker资金地址
ipsIP 白名单数组(精确 IPv4、IPv4 CIDR(如 1.2.3.0/24)或精确 IPv6 地址,暂不支持 IPv6 CIDR;1~20 条)
signature对 MMAccess(action="issue")的 EIP-712 签名,见 EIP-712
deadline / nonce签名有效期(秒)/ 防重放随机数
label / contactEmail可选,备注与联系邮箱
POST /api/mm/issue
{
  "maker":"0x…", "ips":["203.0.113.7","198.51.100.0/24"],
  "signature":"0x…", "deadline":1731000000, "nonce":"1"
}

200  → { "ok":true, "apiKey":"sdx_mk_…", "status":"active", "allowedIps":[…] }
合约金库(资金地址为合约)可由其已 setAgent 授权的代理地址代签申领;后端对 maker 做 isAuthorizedAgent 校验。

Issue & rotate key

POST/mm/issueEIP-712 sig
Self-issue an API key. Issuing again for the same maker rotates it — the old key dies instantly and its pooled quotes are cleared. The plaintext key is returned once.
fieldmeaning
makerfunding address
ipsIP allowlist array (exact IPv4, IPv4 CIDR such as 1.2.3.0/24, or an exact IPv6 address; IPv6 CIDR is not supported yet; 1–20 entries)
signatureEIP-712 signature over MMAccess (action="issue"); see EIP-712
deadline / noncesignature expiry (sec) / anti-replay nonce
label / contactEmailoptional label and contact email
POST /api/mm/issue
{
  "maker":"0x…", "ips":["203.0.113.7","198.51.100.0/24"],
  "signature":"0x…", "deadline":1731000000, "nonce":"1"
}

200  → { "ok":true, "apiKey":"sdx_mk_…", "status":"active", "allowedIps":[…] }
A contract vault (funding address is a contract) may have the key issued by an agent it has authorized via setAgent; the backend verifies isAuthorizedAgent against the maker.

IP 白名单

POST/mm/update-ipsEIP-712 签名
更新 IP 白名单而不轮换 Key。需对 MMAccess(action="update-ip")重新签名。
POST /api/mm/update-ips
{ "maker":"0x…", "ips":["203.0.113.7"], "signature":"0x…", "deadline":1731000000, "nonce":"2" }

200  → { "ok":true, "allowedIps":["203.0.113.7"] }

IP allowlist

POST/mm/update-ipsEIP-712 sig
Update the IP allowlist without rotating the key. Requires a fresh signature over MMAccess (action="update-ip").
POST /api/mm/update-ips
{ "maker":"0x…", "ips":["203.0.113.7"], "signature":"0x…", "deadline":1731000000, "nonce":"2" }

200  → { "ok":true, "allowedIps":["203.0.113.7"] }

Key 状态

GET/mm/key-status?maker=0x…公开 / x-mm-key
查询某地址是否已有可用的 API Key,不返回明文 Key。IP 白名单 allowedIps 只在请求头带上该地址自己的 x-mm-key 时返回。
200  → { "status":"active"|"banned"|"none", "hasKey":true, "allowedIps":[…], "required":true }

required 表示当前平台是否强制报价带 Key。

Key status

GET/mm/key-status?maker=0x…public / x-mm-key
Check whether an address has an active API key; never returns the plaintext key. The IP allowlist (allowedIps) is only returned when the request carries that address's own x-mm-key.
200  → { "status":"active"|"banned"|"none", "hasKey":true, "allowedIps":[…], "required":true }

required indicates whether the platform currently enforces a key for quoting.

做市预算与指标

GET/mm/exposure?maker=0x…&pairId=1x-mm-key(仅本人)
某 maker 在某对的托管模式与可用做市预算。baseBudget=卖单可挂上限(base wei),quoteBudget=买单可挂上限(quote wei)。
200  → {
  "maker":"0x…", "pairId":"1", "custody":"vault"|"allowance",
  "base":"0x…", "quote":"0x…", "baseBudget":"…", "quoteBudget":"…"
}
GET/mm-metrics?pairId=1&owner=0x…&bandBps=200无鉴权
做市考核指标:中间价、价差、价带内双边深度、是否双边,以及该地址自己的报价覆盖。
200  → {
  "pairId":"1", "mid":0.25, "spreadBps":80, "bestBid":0.24, "bestAsk":0.26,
  "bidDepth":1200, "askDepth":900, "twoSided":true, "bandBps":200,
  "owner":"0x…", "ownerBidOrders":5, "ownerAskOrders":5, "ownerOpenOrders":10, "ownerTwoSided":true
}

Budget & metrics

GET/mm/exposure?maker=0x…&pairId=1x-mm-key (own address only)
A maker's custody mode and available quoting budget for a pair. baseBudget = max sell size (base wei), quoteBudget = max buy size (quote wei).
200  → {
  "maker":"0x…", "pairId":"1", "custody":"vault"|"allowance",
  "base":"0x…", "quote":"0x…", "baseBudget":"…", "quoteBudget":"…"
}
GET/mm-metrics?pairId=1&owner=0x…&bandBps=200no auth
MM metrics: mid, spread, in-band two-sided depth, whether two-sided, and the address's own quote coverage.
200  → {
  "pairId":"1", "mid":0.25, "spreadBps":80, "bestBid":0.24, "bestAsk":0.26,
  "bidDepth":1200, "askDepth":900, "twoSided":true, "bandBps":200,
  "owner":"0x…", "ownerBidOrders":5, "ownerAskOrders":5, "ownerOpenOrders":10, "ownerTwoSided":true
}

托管做市

做市商把流动性充入金库并对平台代理授权后,由平台常驻机器人替其增量布单。订阅 / 退订均需 maker 本人 EIP-712 签名。

GET/mm/agent无鉴权
平台托管机器人的代理地址,供前端 setAgent 授权用。返回 {agent, enabled}。
POST/mm/subscribeEIP-712 签名
订阅托管做市。前置:① 已对 /mm/agent 返回的代理地址 setAgent 授权(后端链上校验);② VAULT 模式需该交易对金库里已有做市资金,USDT 可用额或按固定价折算的 base 至少 1 USDT,否则返回 400;③ 被平台停用的地址返回 403。
字段说明
maker / pairId资金地址 / 交易对
params.priceSource锚价来源:fixed / binance(book 已停用:以自家盘口为锚容易被尘埃单拖偏)
params.fixedPrice固定锚价(priceSource=fixed 时)
params.binanceSymbol外部行情符号(priceSource=binance 时)
params.levels单边挂单档数(1~20)
params.halfSpreadBps半价差(基点,1~2000)
params.rangeWidthBps布单价格带宽(基点,10~5000)
signature / deadline / nonce对 MMSubscribe 的 EIP-712 签名,见 EIP-712
POST /api/mm/subscribe
{
  "maker":"0x…", "pairId":"1",
  "params":{ "priceSource":"binance", "binanceSymbol":"CAKEUSDT", "levels":10, "halfSpreadBps":30, "rangeWidthBps":300 },
  "signature":"0x…", "deadline":1731000000, "nonce":"1"
}

200  → { "ok":true, "subscription":{…} }
POST/mm/unsubscribeEIP-712 签名
取消托管做市。需对 MMUnsubscribe 签名。返回 {ok, removed};该交易对没有订阅时返回 404。
GET/mm/subscriptions?maker=0x…x-mm-key(仅本人)
查询某做市商的托管订阅。返回 {subscriptions:[…]}。

Hosted market making

Once a maker funds the vault and authorizes the platform agent, the platform's resident bot quotes incrementally on its behalf. Subscribe and unsubscribe both require the maker's own EIP-712 signature.

GET/mm/agentno auth
The platform bot's agent address for the frontend setAgent call. Returns {agent, enabled}.
POST/mm/subscribeEIP-712 sig
Subscribe to hosted MM. Preconditions: (1) the agent from /mm/agent must already be authorized via setAgent (checked on-chain); (2) in VAULT mode the pair's vault must already hold market-making funds worth at least 1 USDT (available USDT, or base valued at the fixed price), otherwise 400; (3) addresses suspended by the platform get 403.
fieldmeaning
maker / pairIdfunding address / pair
params.priceSourceanchor price source: fixed / binance ("book" is no longer accepted: anchoring on our own book can be pushed by tiny orders)
params.fixedPricefixed anchor price (when priceSource=fixed)
params.binanceSymbolexternal feed symbol (when priceSource=binance)
params.levelslevels per side (1–20)
params.halfSpreadBpshalf spread in bps (1–2000)
params.rangeWidthBpsladder price-band width in bps (10–5000)
signature / deadline / nonceEIP-712 signature over MMSubscribe; see EIP-712
POST /api/mm/subscribe
{
  "maker":"0x…", "pairId":"1",
  "params":{ "priceSource":"binance", "binanceSymbol":"CAKEUSDT", "levels":10, "halfSpreadBps":30, "rangeWidthBps":300 },
  "signature":"0x…", "deadline":1731000000, "nonce":"1"
}

200  → { "ok":true, "subscription":{…} }
POST/mm/unsubscribeEIP-712 sig
Cancel hosted MM. Requires a signature over MMUnsubscribe. Returns {ok, removed}, or 404 if there is no subscription for that pair.
GET/mm/subscriptions?maker=0x…x-mm-key (own address only)
Query a maker's hosted subscriptions. Returns {subscriptions:[…]}.

高级做市联系

POST/mm/contact无鉴权
高级做市商联系表单,仅落库邮箱与需求,平台人工跟进,不涉及资金 / 签名 / 准入。
POST /api/mm/contact
{ "email":"you@example.com", "note":"…", "token":"0x…" }

200  → { "ok":true }

Advanced MM contact

POST/mm/contactno auth
Advanced-maker contact form; stores an email and request for manual follow-up. No funds, signing or admission involved.
POST /api/mm/contact
{ "email":"you@example.com", "note":"…", "token":"0x…" }

200  → { "ok":true }

交易 API 概览

交易 API 和做市报价共用同一把 API Key,Key 代表它绑定的那个钱包。下单、撤单、查询都用这一把 Key,不需要另外申请。

平台不托管资金,也不替你付 gas。下单类接口返回一笔算好的交易(to / data / value),由你的程序用 Key 绑定的钱包签名并广播,gas 由你自己付。资金始终在你自己的钱包里,成交与保护由合约强制执行。

类型怎么成交
市价单服务端按当前盘口(链上挂单 + 做市签名报价)规划路由,组装一笔聚合吃单交易,带"最少到手量"。盘口在你发交易时变差、到手会低于最少到手量的,整笔回滚,不会以意外的价格成交。
限价单 GTC挂到链上订单簿,挂单时锁仓(买单锁 USDT,卖单锁代币)。和对面的单价格交叉后由撮合程序自动成交,撤单时退回锁仓。只能挂不会立即成交的价格:限价已经够得着对面最优价时,接口返回 WOULD_CROSS,请先用 IOC 吃单,剩下的再挂。这是为了防止挂上去的单被人按你的限价、而不是盘口更好的价格成交。
限价单 IOC只按你的限价吃盘口上现有的单,吃不到的部分不留单。
请求头x-api-key
每个请求都要带 x-api-key: sdx_mk_…(也兼容 x-mm-key),而且请求 IP 必须在这把 Key 的白名单里。每把 Key 每分钟最多 600 次请求。

数量一律用代币最小单位的整数字符串(18 位精度的币,1 枚 = 1000000000000000000);价格用十进制字符串,表示 1 个基础币值多少 USDT。

出错时返回 { error, message, messageZh }:error 是给程序判断用的固定代码,另外两个分别是英文和中文说明。

Trading API overview

The trading API uses the same API key as market-maker quoting. The key represents the wallet it is bound to, and covers placing orders, cancelling and queries. There is nothing extra to apply for.

The platform never holds your funds and never pays gas for you. Order endpoints return a ready-made transaction (to / data / value). Your program signs and broadcasts it from the wallet bound to the key and pays the gas. Funds stay in your own wallet, and the contracts enforce settlement and protections.

typehow it fills
MarketThe server plans a route across the current book (on-chain orders plus market-maker signed quotes) and builds one aggregated take transaction with a minimum amount out. If the book moves and you would receive less than that minimum, the whole transaction reverts, so you never fill at an unexpected price.
Limit GTCRests on the on-chain order book with funds locked (USDT for buys, tokens for sells). It fills automatically when it crosses the other side, and cancelling returns the locked funds. GTC only accepts prices that would not trade immediately: if your limit already reaches the best price on the other side, you get WOULD_CROSS. Send IOC first and rest the remainder. This stops a resting order from being filled at your own limit instead of the better book price.
Limit IOCTakes only what is on the book at or better than your limit price. Nothing rests.
Headerx-api-key
Every request needs x-api-key: sdx_mk_… (x-mm-key also works), and must come from an IP on that key's allowlist. Each key can make up to 600 requests per minute.

Quantities are integer strings in the token's smallest unit (for an 18-decimal token, 1 token = 1000000000000000000). Prices are decimal strings: how many USDT one base token is worth.

Errors return { error, message, messageZh }: error is a stable code for your program, the other two are explanations in English and Chinese.

下单

POST/v1/trade/orderx-api-key
返回待签名的交易。余额不够或授权不足时如实告诉你,并附上需要先发的授权交易。
字段说明
pairId交易对编号,见 GET /pairs
sidebuy 或 sell
typemarket(默认)或 limit
qty基础币数量,最小单位整数字符串
price限价单必填,必须落在交易对的最小价格变动上;不在的话会返回 PRICE_NOT_ON_TICK 和建议价
timeInForce限价单用:GTC(默认,挂单)或 IOC(只吃不挂)
slippageBps市价单允许的滑点,默认 100(1%),最多 1000
allowPartial市价单深度不够时是否按现有深度成交,默认 true;传 false 则深度不够直接报错
expiryGTC 挂单的到期时间(Unix 秒),0 表示不过期
deadlineSec吃单交易的有效期,30 到 600 秒,默认 120;超时上链会回滚
POST /api/v1/trade/order
x-api-key: sdx_mk_…
{ "pairId":"2", "side":"sell", "type":"market", "qty":"100000000", "slippageBps":100 }

200 → {
  "plan": { "fillQty":"100000000", "avgPrice":0.059566, "expectedOut":"59387302000000000", "minOut":"58793428980000000", "legs":[…] },
  "pay": { "token":"0x…", "max":"100000000" },
  "balanceEnough": true,
  "approvals": [ { "spender":"0x…", "amount":"…", "tx":{ "to":"0x…", "data":"0x095ea7b3…" } } ],
  "tx": { "to":"0x…", "data":"0x…", "value":"0", "chainId":56, "gas":"360485" },
  "deadline": "1763340000", "simulated": true
}
使用步骤:① approvals 不为空时,先逐笔发出这些授权交易;② 授权上链后重新请求一次,拿到最新的计划;③ 在 deadline 之前签名广播 tx。simulated=true 表示服务端已经用你的地址模拟过这笔交易,能成交。

Place an order

POST/v1/trade/orderx-api-key
Returns a transaction for you to sign. If your balance or allowance is short, the response says so and includes the approval transactions to send first.
fieldmeaning
pairIdpair id, see GET /pairs
sidebuy or sell
typemarket (default) or limit
qtybase amount, integer string in the smallest unit
pricerequired for limit orders and must sit on the pair's tick; otherwise you get PRICE_NOT_ON_TICK with a suggested price
timeInForcefor limit orders: GTC (default, rests on the book) or IOC (take only)
slippageBpsmarket order slippage tolerance, default 100 (1%), max 1000
allowPartialfor market orders, whether to trade what is available when the book is thin; default true, send false to get an error instead
expiryGTC order expiry as a unix timestamp in seconds; 0 means never
deadlineSecvalidity of a take transaction, 30 to 600 seconds, default 120; it reverts if mined later
POST /api/v1/trade/order
x-api-key: sdx_mk_…
{ "pairId":"2", "side":"sell", "type":"market", "qty":"100000000", "slippageBps":100 }

200 → {
  "plan": { "fillQty":"100000000", "avgPrice":0.059566, "expectedOut":"59387302000000000", "minOut":"58793428980000000", "legs":[…] },
  "pay": { "token":"0x…", "max":"100000000" },
  "balanceEnough": true,
  "approvals": [ { "spender":"0x…", "amount":"…", "tx":{ "to":"0x…", "data":"0x095ea7b3…" } } ],
  "tx": { "to":"0x…", "data":"0x…", "value":"0", "chainId":56, "gas":"360485" },
  "deadline": "1763340000", "simulated": true
}
How to use it: (1) if approvals is not empty, send those approval transactions first; (2) once they are mined, request the order again to get a fresh plan; (3) sign and broadcast tx before deadline. simulated=true means the server has already simulated the transaction from your address and it fills.

撤单

POST/v1/trade/cancelx-api-key
传 orderId,或者 orderIds(1 到 50 个)。每张单返回一笔撤单交易,由你的钱包签名发送,锁仓退回钱包。只能撤自己的挂单。
POST /api/v1/trade/cancel
{ "orderIds":["12","15"] }

200 → { "txs":[ { "orderId":"12", "tx":{ "to":"0x…", "data":"0x…" } }, … ] }
做市签名报价的撤销走 /quote/cancel,不在这里。

Cancel

POST/v1/trade/cancelx-api-key
Send orderId, or orderIds (1 to 50). You get one cancel transaction per order to sign from your wallet; locked funds return to the wallet. You can only cancel your own orders.
POST /api/v1/trade/cancel
{ "orderIds":["12","15"] }

200 → { "txs":[ { "orderId":"12", "tx":{ "to":"0x…", "data":"0x…" } }, … ] }
Signed market-maker quotes are cancelled through /quote/cancel, not here.

查询

GET/v1/trade/orders?pairId=&status=open&limit=100x-api-key
你的链上挂单。status 可选 open(默认)、filled、cancelled、expired、all。
GET/v1/trade/fills?pairId=&limit=100x-api-key
你的成交记录,最新的在前,包括吃单、挂单被吃和做市金库成交。
GET/v1/trade/balancesx-api-key
钱包里各交易对用到的代币余额、对订单簿和签名结算合约的授权额度,以及卖单里锁着的数量。
GET/v1/trade/tx/:hashx-api-key
查一笔交易的结果:pending、success 或 reverted,以及已经索引到的成交明细。

Queries

GET/v1/trade/orders?pairId=&status=open&limit=100x-api-key
Your on-chain orders. status can be open (default), filled, cancelled, expired or all.
GET/v1/trade/fills?pairId=&limit=100x-api-key
Your fills, newest first: takes, your resting orders being filled, and market-maker vault fills.
GET/v1/trade/balancesx-api-key
Wallet balances of every token used by a pair, allowances to the order book and the signed-quote settler, and the amount locked in your sell orders.
GET/v1/trade/tx/:hashx-api-key
Result of a transaction: pending, success or reverted, plus any fills already indexed.

EIP-712 域与结构

做市相关签名共用主网参数 chainId: 56、verifyingContract: SignedQuoteSettler。三套域:

SignedQuote(报价单)

domain = {
  name:"SorDexSignedQuote", version:"1",
  chainId:56, verifyingContract:"0xD5D43Ea31dEaFaeD32127516A1a2c381a0ef2f1d"  // Settler
}

SignedQuote {
  address maker;    // 做市商地址
  uint256 pairId;
  uint8   side;     // 0=买(bid)  1=卖(ask)
  uint256 priceNum; // 价格 = priceNum / priceDen(最小单位比)
  uint256 priceDen;
  uint256 baseQty;  // base 数量(最小单位)
  uint64  expiry;   // 到期时间戳(秒)。必填,不能为 0,且不能超过当前时间 + 840 秒(14 分钟);到期自然失效
  uint256 nonce;    // 须 >= minValidNonce(maker)
  uint256 salt;     // 每档唯一,去重
}
成交额(quote 最小单位)= baseQty × priceNum / priceDen。quoteHash 可由 SignedQuoteSettler.hashQuote(quote) 读到,或取 POST /quote 返回的 hash。

MMAccess(Key 申领 / 改白名单)

domain = { name:"SorDexMMAccess", version:"1", chainId:56, verifyingContract:Settler }

MMAccess {
  address maker;
  string  action;   // "issue" 申领/轮换  |  "update-ip" 改白名单
  string  ips;      // IP 白名单,按分号 ; 连接(签名覆盖,防篡改)
  uint256 deadline; // 秒
  uint256 nonce;
}

MMSubscribe / MMUnsubscribe(托管做市)

domain = { name:"SorDexHostedMM", version:"1", chainId:56, verifyingContract:Settler }

MMSubscribe {
  address maker; uint256 pairId;
  string  priceSource; uint256 fixedPriceE8;  // fixedPriceE8 = round(fixedPrice × 1e8)
  string  binanceSymbol; uint256 levels;
  uint256 halfSpreadBps; uint256 rangeWidthBps;
  uint256 deadline; uint256 nonce;
}
MMUnsubscribe { address maker; uint256 pairId; uint256 deadline; uint256 nonce; }

EIP-712 domains & types

Market-making signatures share the mainnet parameters chainId: 56 and verifyingContract: SignedQuoteSettler. Three domains:

SignedQuote

domain = {
  name:"SorDexSignedQuote", version:"1",
  chainId:56, verifyingContract:"0xD5D43Ea31dEaFaeD32127516A1a2c381a0ef2f1d"  // Settler
}

SignedQuote {
  address maker;    // maker address
  uint256 pairId;
  uint8   side;     // 0=buy(bid)  1=sell(ask)
  uint256 priceNum; // price = priceNum / priceDen (ratio in smallest units)
  uint256 priceDen;
  uint256 baseQty;  // base amount (smallest units)
  uint64  expiry;   // expiry, unix sec. Required: must not be 0 and at most now + 840 s (14 min); self-expires
  uint256 nonce;    // must be >= minValidNonce(maker)
  uint256 salt;     // unique per level, for dedup
}
Notional (quote smallest units) = baseQty × priceNum / priceDen. The quoteHash comes from SignedQuoteSettler.hashQuote(quote) or the hash field returned by POST /quote.

MMAccess (key issuance / IP update)

domain = { name:"SorDexMMAccess", version:"1", chainId:56, verifyingContract:Settler }

MMAccess {
  address maker;
  string  action;   // "issue" = issue/rotate  |  "update-ip" = update allowlist
  string  ips;      // IP allowlist joined by ";" (covered by the signature)
  uint256 deadline; // seconds
  uint256 nonce;
}

MMSubscribe / MMUnsubscribe (hosted MM)

domain = { name:"SorDexHostedMM", version:"1", chainId:56, verifyingContract:Settler }

MMSubscribe {
  address maker; uint256 pairId;
  string  priceSource; uint256 fixedPriceE8;  // fixedPriceE8 = round(fixedPrice × 1e8)
  string  binanceSymbol; uint256 levels;
  uint256 halfSpreadBps; uint256 rangeWidthBps;
  uint256 deadline; uint256 nonce;
}
MMUnsubscribe { address maker; uint256 pairId; uint256 deadline; uint256 nonce; }

提交签名报价

POST/quote准入 + x-mm-key
提交一条签名报价,验签通过入池。签名须为规范 65 字节(低 s 值),否则拒收。重复提交同一条报价是幂等的:返回同一个 hash(HTTP 200),不会重复入池,也不会返回 409。入池前会同步校验:交易对存在、价格在 tick 上、数量与成交额不低于最小值、nonce 未被作废,不合格直接返回 400 和具体错误码。
POST /api/quote
x-mm-key: sdx_mk_…
{ "quote":{ …SignedQuote 字段… }, "signature":"0x…" }

200  → { "ok":true, "hash":"0x…(quoteHash)" }
4xx  → { "error":"…", "code":"…" }
签名被拒时 code 说明原因:SIG_MALFORMED 不是 0x+130 位十六进制;SIG_NON_CANONICAL s 值不在低半区或 v 不是 27/28;SIG_UNRECOVERABLE 无法从签名恢复出地址;SIGNER_NOT_AUTHORIZED 恢复出的地址既不是 maker 也不是其已授权代理——多半是签名域(chainId、verifyingContract=当前 Settler)或某个报价字段与提交内容不一致,错误信息里会给出恢复出的地址和本服务使用的签名域。
POST/quote/batch准入 + x-mm-key
批量提交(1~64 条,一梯一次送)。逐条返回结果,单条失败不影响其余。
POST /api/quote/batch
x-mm-key: sdx_mk_…
{ "quotes":[ { "quote":{…}, "signature":"0x…" }, … ] }

200  → { "ok":true, "results":[ {"ok":true,"hash":"0x…"} | {"ok":false,"error":"…","code":"…"}, … ] }
POST/quote/cancelMMAccess 签名
撤掉自己在报价池里的签名单(按 quoteHash 或全部),盘口立即不再展示、吃单方不会再选中。由 maker 本人或其已授权代理签 SorDexMMAccess:action="cancel-quotes",ips 字段填 "all",或把要撤的 quoteHash(小写)按提交顺序用 ";" 连接。每个签名只能用一次。
POST /api/quote/cancel
{ "maker":"0x…", "all":true,               // 或 "hashes":["0x…", …](1~100 个)
  "signature":"0x…", "deadline":1794600000, "nonce":"1" }

200  → { "ok":true, "removed":3 }
这是链下撤单:已签出的报价在 expiry 前链上仍然有效,若签名已被别人拿到仍可能成交。需要确定性作废时,用链上 cancelQuote / cancelQuoteUpTo(见 核心合约函数)。日常改价建议签短 expiry + 重签新价。

Submit signed quotes

POST/quoteadmission + x-mm-key
Submit one signed quote; enters the pool once verified. The signature must be a canonical 65-byte (low-s) value or it is rejected. Submitting the same quote again is idempotent: you get the same hash back (HTTP 200) and it is not added twice, and no 409 is returned. Before entering the pool the quote is checked synchronously: the pair must exist, the price must be on the tick, size and notional must meet the minimums, and the nonce must not be invalidated; otherwise you get a 400 with a specific error code.
POST /api/quote
x-mm-key: sdx_mk_…
{ "quote":{ …SignedQuote fields… }, "signature":"0x…" }

200  → { "ok":true, "hash":"0x…(quoteHash)" }
4xx  → { "error":"…", "code":"…" }
When a signature is rejected, code tells you why: SIG_MALFORMED is not 0x + 130 hex chars; SIG_NON_CANONICAL has a high s value or a v other than 27/28; SIG_UNRECOVERABLE no address can be recovered; SIGNER_NOT_AUTHORIZED the recovered address is neither the maker nor one of its authorized agents. That last one usually means the signing domain (chainId, verifyingContract = the current Settler) or a quote field differs from what you submitted; the error message includes the recovered address and the domain this service uses.
POST/quote/batchadmission + x-mm-key
Batch submit (1–64 items, a full ladder in one call). Per-item results; a single failure does not block the rest.
POST /api/quote/batch
x-mm-key: sdx_mk_…
{ "quotes":[ { "quote":{…}, "signature":"0x…" }, … ] }

200  → { "ok":true, "results":[ {"ok":true,"hash":"0x…"} | {"ok":false,"error":"…","code":"…"}, … ] }
POST/quote/cancelMMAccess signature
Pull your own signed quotes from the quote pool, by quoteHash or all at once. They disappear from the book right away and takers will no longer route to them. Signed by the maker or one of its authorized agents with SorDexMMAccess: action = "cancel-quotes", and ips = "all", or the quoteHashes (lowercase) joined by ";" in the order you send them. Each signature can be used once.
POST /api/quote/cancel
{ "maker":"0x…", "all":true,               // or "hashes":["0x…", …] (1–100)
  "signature":"0x…", "deadline":1794600000, "nonce":"1" }

200  → { "ok":true, "removed":3 }
This is an off-chain cancel: a signed quote stays valid on chain until its expiry, so anyone who already holds the signature could still fill it. For a guaranteed cancel, call cancelQuote / cancelQuoteUpTo on chain (see core calls). For routine repricing, sign short expiries and re-sign at the new price.

查询签名盘口

GET/signed-quotes?pairId=1无鉴权
当前池中有效的签名报价(B 单)明细,供智能路由吃单选单。与 /mixed-book 合并即用户看到的完整盘口。
200  → {
  "pairId":"1",
  "quotes":[ { "quote":{…}, "signature":"0x…", "availableBase":"…", "price":0.25, "side":1 }, … ]
}

Signed book

GET/signed-quotes?pairId=1no auth
Valid signed quotes (B-orders) currently in the pool, for taker smart routing. Merged with /mixed-book for the full book users see.
200  → {
  "pairId":"1",
  "quotes":[ { "quote":{…}, "signature":"0x…", "availableBase":"…", "price":0.25, "side":1 }, … ]
}

报价准入

/quote 与 /quote/batch 按以下顺序放行(quote.maker 为准入主体):

  • 已被平台停用的地址:一律拒收,返回 403。
  • 金库做市:maker 为 VAULT 模式且在该交易对金库有可用余额 → 直接放行,无需 Key。
  • 其余情况:请求头须带有效 x-mm-key,且满足:Key 处于 active、Key 绑定地址 == quote.maker、请求来源 IP 在该 Key 的白名单内。

读链失败或取不到金库余额时保守落到 Key 校验(fail-closed)。违反任一条返回 401/403,错误文案指明原因。

通过准入后,入池还有两条资金规则(防止用尘埃报价占满报价池):

  • 单张最小额:每张报价的成交额(数量 × 价格)至少 0.5 USDT,低于此返回 BELOW_POOL_MIN_NOTIONAL。链上最小额更低,但报价池按这个门槛收。
  • 资金覆盖:同一 maker、同一交易对、同一方向,池内报价加上本张的总量不得超过可用资金(卖单看 base,买单看 USDT;VAULT 模式为金库可用额,ALLOWANCE 模式为授权额与钱包余额的较小值)。超出返回 NOT_COVERED;暂时读不到资金返回 BUDGET_UNKNOWN,稍后重试即可。超出资金的报价本来也进不了盘口,所以先撤掉一些再补。

pairId 及各数值字段会统一成十进制字符串(例如 "01" 与数字 1 都按 "1" 处理),签名与 hash 不受影响。

Quote admission

/quote and /quote/batch admit in this order (the subject is quote.maker):

  • Addresses suspended by the platform are always rejected with 403.
  • Vault custody: a VAULT-mode maker with available balance in the pair's vault is admitted directly, no key needed.
  • Otherwise: the request must carry a valid x-mm-key that is active, whose bound address equals quote.maker, and the request's source IP must be in that key's allowlist.

If chain reads or vault-balance lookups fail, admission falls back to the key check (fail-closed). Any violation returns 401/403 with an error message stating the cause.

Once admitted, two funding rules apply before a quote enters the pool (so the pool can't be filled with dust):

  • Minimum size: each quote must be worth at least 0.5 USDT (size × price), otherwise you get BELOW_POOL_MIN_NOTIONAL. The on-chain minimum is lower, but the pool applies this floor.
  • Funds must cover the quotes: for the same maker, pair and side, the quotes already in the pool plus this one may not exceed the available funds (base for asks, USDT for bids; the vault balance in VAULT mode, or the lower of allowance and wallet balance in ALLOWANCE mode). Going over returns NOT_COVERED; if funds can't be read right now you get BUDGET_UNKNOWN and can simply retry. Quotes beyond your funds would never show on the book anyway, so cancel some before adding more.

pairId and the numeric fields are normalized to decimal strings (for example "01" and the number 1 are both treated as "1"); signatures and hashes are unaffected.

代理自动挂单

持续自动挂单时,无法每档都用钱包弹窗签名。做市商可一次性授权一个代理地址,由本地进程用代理私钥自动签报价——代理只能签报价,碰不到提现。

  • 1. 存保证金:MMCollateralVault.deposit(token, amount),资金锁在金库、只由你自己提。
  • 2. 一次性授权:本地生成代理地址,用做市商钱包对 Settler 调 setAgent(agent, expiry)(expiry 为授权到期秒级时间戳,传 0 撤销)。
  • 3. 本地自动签:进程用代理私钥 EIP-712 签每档、提交 /quote 或 /quote/batch。报价 maker 仍填做市商地址;后端识别签名人为已授权代理即放行。
// 一次性授权(做市商钱包发起)
SignedQuoteSettler.setAgent(agentAddress, expiryUnixSeconds)
// 查询授权
SignedQuoteSettler.isAuthorizedAgent(maker, agent) -> bool
代理私钥泄露最坏情况仅限「在金库额度与价格范围内乱签报价」,不能提现;授权带 expiry 自动到期,可随时 setAgent(agent, 0) 撤销。

Agent quoting

Continuous quoting cannot pop a wallet prompt per level. A maker authorizes an agent address once, then a local process signs quotes with the agent key automatically — the agent can only sign quotes, never withdraw.

  • 1. Fund the vault: MMCollateralVault.deposit(token, amount); funds stay locked and only you withdraw.
  • 2. Authorize once: generate an agent address locally and call setAgent(agent, expiry) on the Settler from the maker wallet (expiry = unix seconds; 0 revokes).
  • 3. Auto-sign locally: the process EIP-712-signs each level with the agent key and posts to /quote or /quote/batch. The quote's maker stays the maker address; the backend admits once it sees the signer is an authorized agent.
// one-time authorization (from the maker wallet)
SignedQuoteSettler.setAgent(agentAddress, expiryUnixSeconds)
// check authorization
SignedQuoteSettler.isAuthorizedAgent(maker, agent) -> bool
Worst case if the agent key leaks is bounded to signing bad quotes within your vault budget and price range — it cannot withdraw; authorization auto-expires and can be revoked anytime via setAgent(agent, 0).

项目方交易税

项目方交易税由项目方自管,平台不代管、不设置。推荐实现识别标志 sordexTax(),使 SorDex 上与 AMM 一致地买扣一次、卖扣一次(扣的是 base)。

// 代币实现此接口,声明买/卖税率(bps,100=1%)与收款地址
function sordexTax() external view
  returns (uint16 buyBps, uint16 sellBps, address recipient);

对接两步:① 在代币实现 sordexTax();② 把 SorDex 的订单簿 / 金库 / 结算合约加入代币自身转账税免税白名单。否则 base 进出合约两跳会各被原生税抽一次。单侧税率上限 20%,计价币 USDT 全程不抽税。未实现 sordexTax() 的普通抽税币仍可交易(按实际到账记账,会被抽两次)。

Project transfer tax

A project's transfer tax is self-managed; the platform neither sets nor custodies it. Implement the sordexTax() marker so that on SorDex the tax is charged once per buy and once per sell (deducted in base), like an AMM.

// token implements this to declare buy/sell rates (bps, 100=1%) and recipient
function sordexTax() external view
  returns (uint16 buyBps, uint16 sellBps, address recipient);

Two steps: (1) implement sordexTax() in the token; (2) add SorDex's order-book / vault / settler contracts to the token's own fee-exemption list — otherwise the native tax fires on both hops as base moves in and out of the contract. Per-side cap is 20%; the quote currency USDT is never taxed. Plain fee-on-transfer tokens without sordexTax() still trade (accounted by actual received amount, taxed twice).

合约地址

BSC 主网部署地址(chainId 56)。接入前请在 BscScan 核对。

合约地址
ListingRegistry0xBCb5f317FDeEeC3D5A98a98A99d6d60E849EA477
SettlementOrderBook0x3beCfBF418b46712A10a26212255B01823B81505
MMCollateralVault0x269d78A4E302A5E78Fdb6681D9D4fF002e86E63b
SignedQuoteSettler0xD5D43Ea31dEaFaeD32127516A1a2c381a0ef2f1d
MixedTakeRouter0xf8Bd78ed7622Bb3976BebB03D99eA5AAff71022D
MarketMakerRegistry0xBFF929d9acFA13eCd81812a98dFa946c6a37A94B
FeeVault0x2b0934913FEF658F0628F004Ff5451aF2b8C21e6
USDT (quote)0x55d398326f99059fF775485246999027B3197955

Contract addresses

BSC mainnet deployment (chainId 56). Verify on BscScan before integrating.

contractaddress
ListingRegistry0xBCb5f317FDeEeC3D5A98a98A99d6d60E849EA477
SettlementOrderBook0x3beCfBF418b46712A10a26212255B01823B81505
MMCollateralVault0x269d78A4E302A5E78Fdb6681D9D4fF002e86E63b
SignedQuoteSettler0xD5D43Ea31dEaFaeD32127516A1a2c381a0ef2f1d
MixedTakeRouter0xf8Bd78ed7622Bb3976BebB03D99eA5AAff71022D
MarketMakerRegistry0xBFF929d9acFA13eCd81812a98dFa946c6a37A94B
FeeVault0x2b0934913FEF658F0628F004Ff5451aF2b8C21e6
USDT (quote)0x55d398326f99059fF775485246999027B3197955

核心合约函数

挂单 / 撤单 / 改价 / 吃单 / 建对 / 充提均由你自付 gas,平台不代付。

SettlementOrderBook

placeBuy(pairId, qty, priceNum, priceDen, expiry)    // 挂买单,锁 USDT
placeSell(pairId, qty, priceNum, priceDen, expiry)   // 挂卖单,锁 base
cancelOrder(id)                                      // 撤单
amendOrder(id, newPriceNum, newPriceDen, newQty)     // 改价 / 改量

MixedTakeRouter

takeMixed(params)   // 一笔同时吃链上 A 单 + 签名 B 单,带代付接口

MMCollateralVault

deposit(token, amount)          // 充值做市保证金
availableOf(maker, token)       // 查可用额
requestWithdraw(token, amount)  // 发起提现(有争议窗口)

SignedQuoteSettler

minValidNonce(maker)            // 当前作废水位;新签 nonce 须 >= 此值
cancelQuoteUpTo(newMinNonce)    // 一次性作废某 nonce 以下全部签名单
hashQuote(quote) -> bytes32     // 计算 quoteHash
setAgent(agent, expiry)         // 授权 / 撤销代理(见 代理自动挂单)
isAuthorizedAgent(maker, agent) // 查代理授权

ListingRegistry

createPair(base, tickNum, tickDen, minBaseQty, minNotional, openTime)  // 无许可建对
getPair(pairId)  // 读交易对链上参数
新签报价的 nonce 须 ≥ minValidNonce(maker),否则一出生即无效。启动时先读一次对齐。切换托管模式、撤销代理、或代理到期后重新授权时,水位会一次推进 1,000,000,之前签的单全部作废,需要重新读水位后再签。
直接调合约吃单时,请一律带"最少到手量":takeMixed 的 minTakerOut 不要传 0,订单簿用 takeOrdersMin。代币声明的税率在成交时按实时值收取,不带下限的话,代币方在你成交前临时调高税率,你会少收到币。
挂限价单前先确认价格不会和对面最优价立即成交。能立即成交的部分请走 takeMixed 吃单,剩下的再挂;直接挂上去的话,任何人都可以另挂一张按你限价的对手单来撮合,你会按自己的限价、而不是盘口更好的价格成交。

Core contract calls

Placing, cancelling, amending, taking, listing and vault ops all cost your own gas; the platform never pays it.

SettlementOrderBook

placeBuy(pairId, qty, priceNum, priceDen, expiry)    // bid, locks USDT
placeSell(pairId, qty, priceNum, priceDen, expiry)   // ask, locks base
cancelOrder(id)                                      // cancel
amendOrder(id, newPriceNum, newPriceDen, newQty)     // reprice / resize

MixedTakeRouter

takeMixed(params)   // take on-chain A-orders + signed B-orders in one tx, with on-behalf interface

MMCollateralVault

deposit(token, amount)          // deposit MM collateral
availableOf(maker, token)       // query available
requestWithdraw(token, amount)  // request withdrawal (dispute window)

SignedQuoteSettler

minValidNonce(maker)            // invalidation watermark; new nonce must be >= this
cancelQuoteUpTo(newMinNonce)    // invalidate all signed quotes below a nonce
hashQuote(quote) -> bytes32     // compute the quoteHash
setAgent(agent, expiry)         // authorize / revoke an agent (see Agent quoting)
isAuthorizedAgent(maker, agent) // check agent authorization

ListingRegistry

createPair(base, tickNum, tickDen, minBaseQty, minNotional, openTime)  // permissionless listing
getPair(pairId)  // read on-chain pair parameters
A new quote's nonce must be ≥ minValidNonce(maker), otherwise it is born invalid. Read it once at startup to align. Switching custody mode, revoking an agent, or re-authorizing an agent after it expired moves the watermark forward by 1,000,000 at once; every quote signed before that is void, so read the watermark again before signing.
When you take directly on the contracts, always set a minimum amount out: never pass 0 for minTakerOut in takeMixed, and use takeOrdersMin on the order book. Declared token taxes are charged at the live rate when you trade, so without a minimum a token owner could raise the tax just before your trade and you would receive fewer tokens.
Before resting a limit order, make sure its price would not trade immediately against the best price on the other side. Take the marketable part with takeMixed and rest only the remainder. Otherwise anyone can place an opposite order at your limit and match it, and you fill at your own limit instead of the better book price.

无许可建对

上币无需审批:任何人用自己的钱包调登记表建对,计价币固定 USDT。

CALLListingRegistry.createPair(base, tickNum, tickDen, minBaseQty, minNotional, openTime)
链上建对(payable,建对费默认 0)。openTime 为开放交易时间戳(秒),0=立即;此前离线报价可进池但无人能吃,到点自动开放。护栏:base 须为合约、不得等于 USDT、同对不可重复、openTime 不得超过 7 天后。
POST/listing-meta建对人签名
建对成功后登记链下展示信息(logo、展示名、联系方式),纯展示、无特权。必须由创建该交易对的钱包做 EIP-712 签名(domain SorDexListingMeta v1,类型 ListingMeta(uint256 pairId,string displayName,string logo,uint256 deadline),deadline 不超过 1 小时),并附建对交易的 txHash,服务端核对签名人就是建对人。首写锁定:同一 pairId 的信息一经登记不可再改,如需修改请联系平台。logo 仅接受 https。
POST /api/listing-meta
{
  "pairId":"2", "logo":"https://…/logo.png", "displayName":"Demo Coin",
  "contactTg":"@yourhandle", "contactEmail":"you@example.com",
  "txHash":"0x…", "deadline":1794800000, "signature":"0x…"
}

200  → { "ok":true, "pairId":"2" }

Permissionless listing

Listing needs no approval: anyone creates a pair from their own wallet; the quote is always USDT.

CALLListingRegistry.createPair(base, tickNum, tickDen, minBaseQty, minNotional, openTime)
Create a pair on-chain (payable; creation fee defaults to 0). openTime is the opening timestamp (sec), 0=immediate; before it, off-chain quotes may enter the pool but nobody can take them, and it opens automatically. Guards: base must be a contract, must not equal USDT, the pair must not already exist, and openTime cannot be more than 7 days out.
POST/listing-metapair creator signature
After creation, register off-chain display info (logo, name, contact). Display-only, no privilege. It must be signed (EIP-712) by the wallet that created the pair (domain SorDexListingMeta v1, type ListingMeta(uint256 pairId,string displayName,string logo,uint256 deadline), deadline at most 1 hour ahead), together with the txHash of the pair-creation transaction; the server checks that the signer is the creator. First-write lock: once set, a pairId's metadata cannot be changed; contact the platform if it needs fixing. logo must be https.
POST /api/listing-meta
{
  "pairId":"2", "logo":"https://…/logo.png", "displayName":"Demo Coin",
  "contactTg":"@yourhandle", "contactEmail":"you@example.com",
  "txHash":"0x…", "deadline":1794800000, "signature":"0x…"
}

200  → { "ok":true, "pairId":"2" }

错误码

出错时返回对应 HTTP 状态码与 {"error":"…"},报价类错误另带 code 字段便于程序判断。不存在的接口统一返回 404 {"error":"Not found."};请求体格式错误返回 400(不是 JSON 时为 415)。

状态含义
400请求参数无效:地址 / hash / pairId 格式错、缺必填项、未知交易对、IP 白名单非法
401需要签名 / 签名已过期 / 签名无效;或报价需带 x-mm-key 而未带
403Key 与报价地址不匹配、IP 不在白名单、授权额度做市缺 Key、地址已被平台停用
404该地址尚无可用 API Key、退订的交易对没有订阅、接口不存在
413 / 415请求体过大 / 请求体不是 JSON
409签名已被使用(重放)、该交易对信息已登记
429触发限流,请稍后再试
500服务端内部错误
502链上读取失败(代理校验 / 预算查询)
503服务未就绪 / 签名池未启用 / 托管做市未启用 / Settler 未配置
507上币元数据存储已满

报价错误码(/quote、/quote/batch 的 code 字段)

code含义
BELOW_POOL_MIN_NOTIONAL单张报价成交额低于 0.5 USDT
NOT_COVERED同方向池内报价总量超过可用资金
BUDGET_UNKNOWN暂时读不到可用资金,稍后重试
POOL_FULL报价池已满,稍后重试
MAKER_QUOTE_LIMIT该 maker 池内报价已达上限(200 条)
BAD_TICK / BELOW_MIN_QTY / BELOW_MIN_NOTIONAL不符合交易对链上的价格档位 / 最小数量 / 最小成交额
WOULD_CROSSGTC 限价会和对面最优价立即成交;返回里带 bestPrice,请先用 IOC 吃单
STALE_NONCE / QUOTE_CANCELLEDnonce 已被作废 / 该报价已被撤销
SIG_MALFORMED / SIG_NON_CANONICAL / SIGNER_NOT_AUTHORIZED签名格式错误 / 非规范签名 / 签名人不是 maker 也不是其授权代理

Error codes

Errors return the matching HTTP status and {"error":"…"}; quote errors also carry a code field for programmatic handling. Unknown endpoints return 404 {"error":"Not found."}; a malformed body returns 400 (415 if it isn't JSON).

statusmeaning
400invalid params: malformed address / hash / pairId, missing field, unknown pair, invalid IP allowlist
401signature required / expired / invalid; or quote missing a required x-mm-key
403key–maker mismatch, IP not in allowlist, allowance-mode quoting without a key, address suspended by the platform
404no active API key for this address, no subscription to cancel for that pair, or unknown endpoint
413 / 415request body too large / request body is not JSON
409signature already used (replay), listing metadata already registered
429rate limited; retry later
500internal server error
502on-chain read failed (agent check / budget query)
503service not ready / quote pool disabled / hosted MM disabled / settler not configured
507listing metadata store is full

Quote error codes (the code field of /quote and /quote/batch)

codemeaning
BELOW_POOL_MIN_NOTIONALthe quote is worth less than 0.5 USDT
NOT_COVEREDquotes on this side would exceed your available funds
BUDGET_UNKNOWNavailable funds can't be read right now; retry shortly
POOL_FULLthe quote pool is full; retry shortly
MAKER_QUOTE_LIMITthis maker already has the maximum of 200 quotes in the pool
BAD_TICK / BELOW_MIN_QTY / BELOW_MIN_NOTIONALdoes not meet the pair's on-chain tick / minimum size / minimum notional
WOULD_CROSSthe GTC limit would trade immediately against the best price on the other side; the response includes bestPrice. Send IOC first
STALE_NONCE / QUOTE_CANCELLEDnonce already invalidated / quote already cancelled
SIG_MALFORMED / SIG_NON_CANONICAL / SIGNER_NOT_AUTHORIZEDmalformed signature / non-canonical signature / signer is neither the maker nor its authorized agent
SORDEX · 非托管现货订单簿 DEX · 本页为静态文档,合约地址取自当前 BSC 主网部署 SORDEX · Non-custodial spot order-book DEX · static document; addresses from the current BSC mainnet deployment