RFQ Swap 接口

状态：规范（LP 协议 v1，2026-09-23 草案）。 由 Rocky 提供的接口。前半部分面向流动性提供方，后半部分面向集成交易者侧的钱包提供方。

基础地址：https://api.rocky.exchange。约定、错误结构与限流遵循基本信息。

面向流动性提供方的接口

与 USER_DATA 接口一样用你的现货 API key 签名（鉴权）：X-MBX-APIKEY、timestamp、signature。该 key 必须属于 Rocky 登记为你 LP 的账户，否则返回 -2110；LP 的 key 按 ext-mm 限流档位签发。

`GET /v1/lp/signing-keys`

公开。Rocky 用于对调用你服务的请求签名的 Ed25519 密钥。

{
  "keys": [
    { "keyId": "rocky-lp-2026-09", "algorithm": "ED25519", "publicKey": "base64-32-bytes", "fingerprint": "sha256-first-16-hex", "validFrom": "2026-09-23T00:00:00Z", "validUntil": null }
  ]
}

轮换：新密钥至少在开始签名前 7 天发布在此；旧密钥的 validUntil 设为之后 7 天。凡在请求时间戳时有效的列表内密钥都应接受。

`GET /v1/lp/me`

Rocky 视角下你的 LP 登记信息。

{
  "lpId": "acme",
  "party": "lp-acme::1220…",
  "serviceUrl": "https://rfq.acme.example/rocky",
  "status": "ACTIVE",
  "symbols": [
    { "symbol": "CBTC-USDCB", "minBaseQty": "0.0001", "maxBaseQty": "0.5", "enabled": true }
  ],
  "quoteTimeoutMs": 800,
  "acceptTimeoutMs": 5000,
  "makerFeeBps": "0",
  "health": { "lastOkAt": "2026-09-23T08:00:00Z", "consecutiveFailures": 0 },
  "fanOutShare": "1.00"
}

status 取值：TESTING（上线测试：只有 Rocky 的测试交易者会询价）、ACTIVE、PAUSED（你自己暂停）、DEGRADED（健康检查失败）、SUSPENDED（Rocky 运营停用）。公开询价只发给 ACTIVE。

`POST /v1/lp/pause` 与 `POST /v1/lp/resume`

你的紧急开关。pause 立即把你移出广播，一秒内确认；已处于 LP_ALLOCATED 或 SETTLING 的 swap 仍会结算。resume 在你服务的 GET /health 通过后恢复广播。

`GET /v1/lp/trades`

参数	类型	必填	说明
`symbol`	string	否
`status`	string	否	状态机中的任一状态
`startTime`、`endTime`	ms	否	按 `createdAt`；窗口 ≤ 7 天
`fromId`	string	否	从该 `swapId` 起分页
`limit`	int	否	默认 500，最大 1000

响应为下述交易对象的数组，按时间升序。

`GET /v1/lp/trades/{swapId}`

{
  "swapId": "01a0d0f2-6c3a-7b1e-8f2a-3b4c5d6e7f80",
  "symbol": "CBTC-USDCB",
  "side": "SELL",
  "price": "86206.60",
  "baseQty": "0.0125",
  "quoteQty": "1077.5825",
  "quoteId": "acme-q-000123",
  "status": "SUCCEEDED",
  "reason": null,
  "traderParty": "rockywallet-user::1220…",
  "legs": {
    "traderSends": { "instrument": "CBTC", "amount": "0.0125" },
    "traderFee": { "instrument": "CBTC", "amount": "0.00001206" },
    "lpSends": { "instrument": "USDC.B", "amount": "1077.5825" },
    "lpFee": null
  },
  "allocations": {
    "trader": [ { "contractId": "00a1…", "state": "EXECUTED" } ],
    "lp": [ { "contractId": "00b2…", "state": "EXECUTED" } ]
  },
  "settlement": { "executor": "Rocky::1220…", "allocateBefore": "…", "settleBefore": "…" },
  "cantonUpdateId": "1220…",
  "createdAt": "2026-09-23T08:00:05.000Z",
  "updatedAt": "2026-09-23T08:00:07.410Z"
}

allocation 的 state 取值：PENDING、LOCKED、EXECUTED、CANCELLED、WITHDRAWN、EXPIRED。side 为交易者方向，与询价请求一致。

LP 错误码

码	消息	场景
`-2110`	LP endpoint requires an LP-tier key	key 不属于已登记为 LP 的账户
`-2111`	LP is suspended	联系 Rocky 运营
`-2112`	Unknown swap	`swapId` 不属于你或不存在

面向钱包提供方的接口（交易者侧）

使用交易所钱包会话 bearer token 鉴权，与 /v1/spot-chain/… 使用的会话相同。Rocky 网页 Swap 页用的就是这些接口；钱包可以直接调用，在自己的界面里提供 RFQ swap。

`GET /v1/swaps/rfq/quote/{symbol}/{side}?baseQty=`

向活跃 LP 广播并返回最优到手报价；无人报价时返回 -2100。

{
  "rfqId": "7d2f5a4e-1b0e-4f2a-9a5b-1c2d3e4f5a6b",
  "symbol": "CBTC-USDCB",
  "side": "SELL",
  "baseQty": "0.0125",
  "price": "86206.60",
  "grossQuoteQty": "1077.5825",
  "fees": {
    "takerFee": { "instrument": "CBTC", "amount": "0.00000625", "bps": "5" },
    "networkFee": { "instrument": "CBTC", "amount": "0.00000581" }
  },
  "traderSends": { "instrument": "CBTC", "amount": "0.01251206" },
  "traderReceives": { "instrument": "USDC.B", "amount": "1077.5825" },
  "validUntil": "2026-09-23T08:00:04.000Z",
  "lpCount": 3,
  "source": "RFQ"
}

Rocky 的全部费用都以输入资产计：SELL 时以基础资产计、加在 baseQty 之上（交易者付出 baseQty + takerFee + networkFee）；BUY 时以计价资产计、加在 grossQuoteQty 之上。networkFee 是 Swap 页固定的执行成本，按报价折算成输入资产。交易者始终收到 LP 的全部输出。traderSends 与 traderReceives 就是应展示给用户的数字。

`POST /v1/swaps/rfq`

接受报价。请求体：{ "rfqId": "…", "party": "<交易者 party>" }。会话的 party 必须等于 party。

{
  "swapId": "01a0d0f2-6c3a-7b1e-8f2a-3b4c5d6e7f80",
  "status": "QUOTED",
  "allocations": [
    { "purpose": "INPUT",     "instrument": { "admin": "…", "id": "CBTC" }, "amount": "0.0125",     "receiver": "lp-acme::1220…" },
    { "purpose": "TAKER_FEE", "instrument": { "admin": "…", "id": "CBTC" }, "amount": "0.00001206", "receiver": "Rocky-fees::1220…" }
  ],
  "settlement": {
    "executor": "Rocky::1220…",
    "settlementRef": { "id": "01a0d0f2-6c3a-7b1e-8f2a-3b4c5d6e7f80", "cid": null },
    "requestedAt": "2026-09-23T08:00:05.000Z",
    "allocateBefore": "2026-09-23T08:01:05.000Z",
    "settleBefore": "2026-09-23T08:02:05.000Z",
    "meta": { "values": { "rocky.swapId": "01a0d0f2-…", "rocky.symbol": "CBTC-USDCB" } }
  }
}

钱包必须精确创建这些 allocation，有两种方式。

`POST /v1/swaps/rfq/{swapId}/prepare` 与 `…/execute`（Rocky 准备）

对外部签名的钱包（Rocky Wallet、Loop、Console、Send），Rocky 通过 Canton 交互式提交准备好 AllocationFactory_Allocate 命令，钱包对哈希签名，Rocky 执行：

Canton 的交互式提交一次只准备一条命令，所以有输入腿和手续费腿的 swap 需要两轮。每轮：

POST /v1/swaps/rfq/{swapId}/prepare → { "commandId", "purpose", "remaining", "preparedTransaction", "preparedTransactionHash", "hashingSchemeVersion", "commands", "actAs", "readAs", "disclosedContracts", "synchronizerId" }，与 MemberAuth 的 prepare 步骤同一形状，另加 purpose（INPUT 或 TAKER_FEE，先输入腿）与 remaining（含本条在内还需提交的 allocation 数）。附带 commands 以便偏好自行提交的钱包使用。
POST /v1/swaps/rfq/{swapId}/execute，请求体 { "signature": "<对 preparedTransactionHash 的 ed25519 签名，base64 或 hex>" } → 返回交易对象，status 至少为 TRADER_ALLOCATING，并带 remaining；remaining > 0 时再次调用 prepare。两个 allocation 都必须在 allocateBefore 前上链。

`POST /v1/swaps/rfq/{swapId}/attach`（钱包自行提交）

对自行构造并提交 allocation 的钱包：{ "updateId": "1220…", "allocationContractIds": ["00a1…", "00a3…"] }。Rocky 读取这些 allocation 并对照 swap 核验。不匹配返回 -2102，swap 变为 CANCELLED，钱包应随后撤回其 allocation。

两条路径殊途同归：交易者 allocation 核验通过后，Rocky 调用 LP 并完成结算，不再需要钱包参与。

`GET /v1/swaps/rfq/{swapId}`

交易对象（同 GET /v1/lp/trades/{swapId}，不含 LP 私有字段）。每 1–2 s 轮询直到终态；从 execute 到 SUCCEEDED 通常在 10 s 内。

`POST /v1/swaps/rfq/{swapId}/withdraw/prepare` 与 `…/execute`

当 swap 终于 EXPIRED、LP_ACCEPT_FAILED、SETTLEMENT_FAILED 或 CANCELLED，且交易对象显示交易者 allocation 仍为 LOCKED 时，Rocky 先以 executor 身份尝试 Allocation_Cancel。若 settleBefore 之后仍有 allocation 为 LOCKED，这两个调用为钱包准备并执行 Allocation_Withdraw，每轮一个 allocation（purpose、remaining 同上）。自行提交的钱包可直接执行 Allocation_Withdraw。

`GET /v1/swaps/rfq?status=&limit=`

会话 party 的 RFQ swap 列表，最新在前。

交易者侧错误码

码	消息	场景
`-2100`	No liquidity for this request	没有 LP 给出有效报价
`-2101`	Quote expired	`POST /v1/swaps/rfq` 时 `rfqId` 已过 `validUntil`
`-2102`	Allocation does not match the swap	资产、数量、收款方、executor 或 `settlementRef` 有误
`-2103`	Liquidity provider rejected the trade	终态 `LP_ACCEPT_FAILED`；请重新询价
`-2104`	Settlement failed	终态 `SETTLEMENT_FAILED`；输入可撤回
`-2105`	Size out of range	`baseQty` 低于 `minNotional` 或高于所有 LP 的 `maxBaseQty`
`-2106`	Party mismatch	请求体 `party` 与会话 party 不同

限流

LP 接口与其他签名接口一样计入你 key 档位的配额（权重 1；GET /v1/lp/trades 权重 5）。交易者侧询价按会话限制为每秒 1 次、每分钟 30 次；广播成本由 Rocky 承担。

面向流动性提供方的接口​

GET /v1/lp/signing-keys​

GET /v1/lp/me​

POST /v1/lp/pause 与 POST /v1/lp/resume​

GET /v1/lp/trades​

GET /v1/lp/trades/{swapId}​

LP 错误码​

面向钱包提供方的接口（交易者侧）​

GET /v1/swaps/rfq/quote/{symbol}/{side}?baseQty=​

POST /v1/swaps/rfq​

POST /v1/swaps/rfq/{swapId}/prepare 与 …/execute（Rocky 准备）​

POST /v1/swaps/rfq/{swapId}/attach（钱包自行提交）​

GET /v1/swaps/rfq/{swapId}​

POST /v1/swaps/rfq/{swapId}/withdraw/prepare 与 …/execute​

GET /v1/swaps/rfq?status=&limit=​

交易者侧错误码​

限流​