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.
基址 · 鉴权 · 限流
基址:https://sordexpro.com/api,所有路径拼在其后,返回 JSON。
鉴权:只读接口无需鉴权。做市报价按 报价准入规则,带 x-mm-key 请求头或满足金库余额条件。做市管理接口(申领 Key、托管订阅等)用钱包 EIP-712 签名鉴权,无账户密码体系。
限流(按 IP):
| 接口 | 限额 |
|---|---|
| /quote · /quote/batch | 120 / 分钟 |
| /mm/issue · /mm/update-ips | 10 / 分钟 |
| /mm/subscribe · /mm/unsubscribe | 60 / 分钟 |
| /mm/contact | 5 / 分钟 |
| /scan-token · /listing-meta | 10 / 分钟 |
| /token-meta | 20 / 分钟 |
行情类只读接口为轻量缓存,实时数据请用 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):
| endpoint | limit |
|---|---|
| /quote · /quote/batch | 120 / min |
| /mm/issue · /mm/update-ips | 10 / min |
| /mm/subscribe · /mm/unsubscribe | 60 / min |
| /mm/contact | 5 / min |
| /scan-token · /listing-meta | 10 / min |
| /token-meta | 20 / 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.
交易对
| 字段 | 说明 |
|---|---|
| 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
| field | meaning |
|---|---|
| pairId | pair id |
| base / quote | base / quote token address (quote is always USDT) |
| baseSymbol / quoteSymbol | symbols |
| baseDecimals / quoteDecimals | decimals |
| tick / tickNum / tickDen | price step; price must be a multiple of tickNum/tickDen |
| minBaseQty / minNotional | min order size / min notional (smallest units) |
| takerFeeBps / makerFeeBps | taker / maker fee in bps (10 = 0.10%) |
| buyTaxBps / sellTaxBps | project transfer-tax rates (bps) |
| openTime / isOpen / paused | opening timestamp (sec, 0=immediate) / open now / paused |
| logo / displayName | off-chain display info (may be null) |
| listingComplete | all listing steps done |
| openOrders | live 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
}]
盘口
{pairId, bids:[{price,qty}], asks:[{price,qty}], updatedAt}。| 字段 | 说明 |
|---|---|
| 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
}
{pairId, orders:[{id, side, price, remainingBaseQty, seq}]}。Order book
{pairId, bids:[{price,qty}], asks:[{price,qty}], updatedAt}.| field | meaning |
|---|---|
| bids / asks | per level {price, qty, src}; src is onchain / signed / onchain+signed |
| signedQuotes | quotes currently in the signed pool |
| updatedAt | generation 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
}
{pairId, orders:[{id, side, price, remainingBaseQty, seq}]}.成交 · K 线 · 订单
{trades:[{price, qty, cost, fee, taker, txHash, block}]}(qty/cost/fee 为最小单位字符串)。{candles:[{t,o,h,l,c,v}], source:"fills", bucketBlocks},t 为桶首区块号。{orders:[{id, pairId, side, price, originalBaseQty, remainingBaseQty, status}]}。Trades · Candles · Orders
{trades:[{price, qty, cost, fee, taker, txHash, block}]} (qty/cost/fee are smallest-unit strings).{candles:[{t,o,h,l,c,v}], source:"fills", bucketBlocks}; t is the bucket's first block number.{orders:[{id, pairId, side, price, originalBaseQty, remainingBaseQty, status}]}.聚合商标准数据
供 DexScreener / GeckoTerminal / DefiLlama / CoinGecko / CMC 收录的订单簿型交易所标准接口。ticker_id 规则为 BASE_USDT(符号大写)。只读、轻量缓存。
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 /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
}]
代币检测
{token, name, symbol, decimals, totalSupply, logoCandidates, verdict, risks, summary}。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
{token, name, symbol, decimals, totalSupply, logoCandidates, verdict, risks, summary}.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":[]
}
WebSocket
{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
{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
| 字段 | 说明 |
|---|---|
| maker | 资金地址 |
| ips | IP 白名单数组(精确 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
| field | meaning |
|---|---|
| maker | funding address |
| ips | IP 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) |
| signature | EIP-712 signature over MMAccess (action="issue"); see EIP-712 |
| deadline / nonce | signature expiry (sec) / anti-replay nonce |
| label / contactEmail | optional 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":[…] }
setAgent; the backend verifies isAuthorizedAgent against the maker.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 /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 状态
allowedIps 只在请求头带上该地址自己的 x-mm-key 时返回。200 → { "status":"active"|"banned"|"none", "hasKey":true, "allowedIps":[…], "required":true }
required 表示当前平台是否强制报价带 Key。
Key status
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.
做市预算与指标
200 → {
"maker":"0x…", "pairId":"1", "custody":"vault"|"allowance",
"base":"0x…", "quote":"0x…", "baseBudget":"…", "quoteBudget":"…"
}
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
200 → {
"maker":"0x…", "pairId":"1", "custody":"vault"|"allowance",
"base":"0x…", "quote":"0x…", "baseBudget":"…", "quoteBudget":"…"
}
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 签名。
setAgent 授权用。返回 {agent, enabled}。/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":{…} }
{ok, removed};该交易对没有订阅时返回 404。{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.
setAgent call. Returns {agent, enabled}./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.| field | meaning |
|---|---|
| maker / pairId | funding address / pair |
| params.priceSource | anchor price source: fixed / binance ("book" is no longer accepted: anchoring on our own book can be pushed by tiny orders) |
| params.fixedPrice | fixed anchor price (when priceSource=fixed) |
| params.binanceSymbol | external feed symbol (when priceSource=binance) |
| params.levels | levels per side (1–20) |
| params.halfSpreadBps | half spread in bps (1–2000) |
| params.rangeWidthBps | ladder price-band width in bps (10–5000) |
| signature / deadline / nonce | EIP-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":{…} }
{ok, removed}, or 404 if there is no subscription for that pair.{subscriptions:[…]}.高级做市联系
POST /api/mm/contact
{ "email":"you@example.com", "note":"…", "token":"0x…" }
200 → { "ok":true }
Advanced MM contact
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: 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.
| type | how it fills |
|---|---|
| Market | The 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 GTC | Rests 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 IOC | Takes only what is on the book at or better than your limit price. Nothing rests. |
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.
下单
| 字段 | 说明 |
|---|---|
| pairId | 交易对编号,见 GET /pairs |
| side | buy 或 sell |
| type | market(默认)或 limit |
| qty | 基础币数量,最小单位整数字符串 |
| price | 限价单必填,必须落在交易对的最小价格变动上;不在的话会返回 PRICE_NOT_ON_TICK 和建议价 |
| timeInForce | 限价单用:GTC(默认,挂单)或 IOC(只吃不挂) |
| slippageBps | 市价单允许的滑点,默认 100(1%),最多 1000 |
| allowPartial | 市价单深度不够时是否按现有深度成交,默认 true;传 false 则深度不够直接报错 |
| expiry | GTC 挂单的到期时间(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
| field | meaning |
|---|---|
| pairId | pair id, see GET /pairs |
| side | buy or sell |
| type | market (default) or limit |
| qty | base amount, integer string in the smallest unit |
| price | required for limit orders and must sit on the pair's tick; otherwise you get PRICE_NOT_ON_TICK with a suggested price |
| timeInForce | for limit orders: GTC (default, rests on the book) or IOC (take only) |
| slippageBps | market order slippage tolerance, default 100 (1%), max 1000 |
| allowPartial | for market orders, whether to trade what is available when the book is thin; default true, send false to get an error instead |
| expiry | GTC order expiry as a unix timestamp in seconds; 0 means never |
| deadlineSec | validity 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
}
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.撤单
orderId,或者 orderIds(1 到 50 个)。每张单返回一笔撤单交易,由你的钱包签名发送,锁仓退回钱包。只能撤自己的挂单。POST /api/v1/trade/cancel
{ "orderIds":["12","15"] }
200 → { "txs":[ { "orderId":"12", "tx":{ "to":"0x…", "data":"0x…" } }, … ] }
Cancel
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…" } }, … ] }
查询
status 可选 open(默认)、filled、cancelled、expired、all。pending、success 或 reverted,以及已经索引到的成交明细。Queries
status can be open (default), filled, cancelled, expired or all.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; // 每档唯一,去重
}
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
}
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 /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 /api/quote/batch
x-mm-key: sdx_mk_…
{ "quotes":[ { "quote":{…}, "signature":"0x…" }, … ] }
200 → { "ok":true, "results":[ {"ok":true,"hash":"0x…"} | {"ok":false,"error":"…","code":"…"}, … ] }
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 }
cancelQuote / cancelQuoteUpTo(见 核心合约函数)。日常改价建议签短 expiry + 重签新价。Submit signed quotes
POST /api/quote
x-mm-key: sdx_mk_…
{ "quote":{ …SignedQuote fields… }, "signature":"0x…" }
200 → { "ok":true, "hash":"0x…(quoteHash)" }
4xx → { "error":"…", "code":"…" }
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 /api/quote/batch
x-mm-key: sdx_mk_…
{ "quotes":[ { "quote":{…}, "signature":"0x…" }, … ] }
200 → { "ok":true, "results":[ {"ok":true,"hash":"0x…"} | {"ok":false,"error":"…","code":"…"}, … ] }
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 }
cancelQuote / cancelQuoteUpTo on chain (see core calls). For routine repricing, sign short expiries and re-sign at the new price.查询签名盘口
/mixed-book 合并即用户看到的完整盘口。200 → {
"pairId":"1",
"quotes":[ { "quote":{…}, "signature":"0x…", "availableBase":"…", "price":0.25, "side":1 }, … ]
}
Signed book
/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-keythat 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 getBUDGET_UNKNOWNand 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
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
/quoteor/quote/batch. The quote'smakerstays 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
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 核对。
| 合约 | 地址 |
|---|---|
| ListingRegistry | 0xBCb5f317FDeEeC3D5A98a98A99d6d60E849EA477 |
| SettlementOrderBook | 0x3beCfBF418b46712A10a26212255B01823B81505 |
| MMCollateralVault | 0x269d78A4E302A5E78Fdb6681D9D4fF002e86E63b |
| SignedQuoteSettler | 0xD5D43Ea31dEaFaeD32127516A1a2c381a0ef2f1d |
| MixedTakeRouter | 0xf8Bd78ed7622Bb3976BebB03D99eA5AAff71022D |
| MarketMakerRegistry | 0xBFF929d9acFA13eCd81812a98dFa946c6a37A94B |
| FeeVault | 0x2b0934913FEF658F0628F004Ff5451aF2b8C21e6 |
| USDT (quote) | 0x55d398326f99059fF775485246999027B3197955 |
Contract addresses
BSC mainnet deployment (chainId 56). Verify on BscScan before integrating.
| contract | address |
|---|---|
| ListingRegistry | 0xBCb5f317FDeEeC3D5A98a98A99d6d60E849EA477 |
| SettlementOrderBook | 0x3beCfBF418b46712A10a26212255B01823B81505 |
| MMCollateralVault | 0x269d78A4E302A5E78Fdb6681D9D4fF002e86E63b |
| SignedQuoteSettler | 0xD5D43Ea31dEaFaeD32127516A1a2c381a0ef2f1d |
| MixedTakeRouter | 0xf8Bd78ed7622Bb3976BebB03D99eA5AAff71022D |
| MarketMakerRegistry | 0xBFF929d9acFA13eCd81812a98dFa946c6a37A94B |
| FeeVault | 0x2b0934913FEF658F0628F004Ff5451aF2b8C21e6 |
| 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
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.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.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。
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.
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 而未带 |
| 403 | Key 与报价地址不匹配、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_CROSS | GTC 限价会和对面最优价立即成交;返回里带 bestPrice,请先用 IOC 吃单 |
| STALE_NONCE / QUOTE_CANCELLED | nonce 已被作废 / 该报价已被撤销 |
| 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).
| status | meaning |
|---|---|
| 400 | invalid params: malformed address / hash / pairId, missing field, unknown pair, invalid IP allowlist |
| 401 | signature required / expired / invalid; or quote missing a required x-mm-key |
| 403 | key–maker mismatch, IP not in allowlist, allowance-mode quoting without a key, address suspended by the platform |
| 404 | no active API key for this address, no subscription to cancel for that pair, or unknown endpoint |
| 413 / 415 | request body too large / request body is not JSON |
| 409 | signature already used (replay), listing metadata already registered |
| 429 | rate limited; retry later |
| 500 | internal server error |
| 502 | on-chain read failed (agent check / budget query) |
| 503 | service not ready / quote pool disabled / hosted MM disabled / settler not configured |
| 507 | listing metadata store is full |
Quote error codes (the code field of /quote and /quote/batch)
| code | meaning |
|---|---|
| BELOW_POOL_MIN_NOTIONAL | the quote is worth less than 0.5 USDT |
| NOT_COVERED | quotes on this side would exceed your available funds |
| BUDGET_UNKNOWN | available funds can't be read right now; retry shortly |
| POOL_FULL | the quote pool is full; retry shortly |
| MAKER_QUOTE_LIMIT | this maker already has the maximum of 200 quotes in the pool |
| BAD_TICK / BELOW_MIN_QTY / BELOW_MIN_NOTIONAL | does not meet the pair's on-chain tick / minimum size / minimum notional |
| WOULD_CROSS | the GTC limit would trade immediately against the best price on the other side; the response includes bestPrice. Send IOC first |
| STALE_NONCE / QUOTE_CANCELLED | nonce already invalidated / quote already cancelled |
| SIG_MALFORMED / SIG_NON_CANONICAL / SIGNER_NOT_AUTHORIZED | malformed signature / non-canonical signature / signer is neither the maker nor its authorized agent |