grid_skeleton/docs/API_CONNECTOR_SPEC.md

Pacifica 连接器接口规范

覆盖 REST / WebSocket 端点、鉴权、错误处理以及调度策略，为 packages/connectors/pacifica 的实现提供统一参考。

---

1. REST API

功能	Method	Path	关键参数	返回值 (JSON)	说明
查询合约配置	GET	/products/{symbol}	symbol	tickSize, lotSize, minOrderSize, maxLeverage	启动时拉取一次，落盘缓存
查询余额	GET	/account/balances	subaccount	[{ asset, available, total, equity }]	按账户区分，聚合至 RiskEngine
查询持仓	GET	/account/positions	account, subaccount	[{ symbol, base, quote, entryPrice, pnl }]	每次下单或定时刷新
新建订单	POST	/orders/create	symbol, side (bid/ask), price, amount, tif, postOnly, clientOrderId, account, subaccount?	{ orderId }	clientOrderId 由 Router 生成，需幂等
批量撤单	POST	/orders/cancel	orderIds[] 或 clientOrderIds[]	{ cancelled: string[] }	对 Kill-switch、重置网格使用
订单列表	GET	/orders	symbol, status, limit	[{ orderId, status, filledSize, avgPrice }]	同步本地影子簿
成交列表	GET	/fills	symbol, since	[{ orderId, tradeId, price, size, fee, liquidity }]	对账或调试
资金费率	GET	/funding/{symbol}	symbol	{ rate, markPrice, timestamp }	HedgeEngine / FundingMonitor 使用

1.1 请求与签名

Header:
  X-Pacific-Key: <account_address>
  X-Pacific-Timestamp: <epoch_ms>
  X-Pacific-Signature: <ed25519_signature_base64>

Signature base string = `${timestamp}:${method}:${path}:${body || ''}`
signature = sign_ed25519(private_key, base_string_bytes)

• <account_address> 为 Pacifica 账户地址（原文档中称 api_key），与 config.accounts.*.address 一致。
• timestamp 精度毫秒，容忍 ±5 秒；偏差超出将返回 401。
• body 需按原始 JSON 字符串序列化（不去空格）；GET、DELETE 无 body 也需保留空字符串。
• 提供单元测试覆盖：空 body、数组体、浮点数序列化。

1.2 限频与退避

端点	限速	退避策略
下单/撤单	60 req/min	429 → 100ms 起步指数退避 (×2)，最多 5 次
查询类	120 req/min	429 → 200ms 固定延迟，最多 3 次
资金费率	10 req/min	429 → 1s 固定延迟，放弃超过 3 次

• 所有调用统一写入 metrics：pacifica_rest_requests_total{endpoint, status} 与 pacifica_rest_latency_ms。
• 超过最大重试次数时抛出自定义错误 PacificaRateLimitError，由上层降级策略处理。

1.3 错误码映射

HTTP 状态	Pacifica 错误码	含义	处理建议
400	INVALID_SIZE	订单尺寸不符合 tick/lot	记录告警，阻止重试
400	POST_ONLY_WOULD_CROSS	Post-only 订单会吃单	Router 调整价差或放弃
401	UNAUTHENTICATED	签名/时间戳错误	立即 Halt 账户，通知运维
404	ORDER_NOT_FOUND	撤单目标不存在	视为成功，更新本地缓存
409	DUPLICATE_CLIENT_ID	clientId 重复	Router 重新生成 ID 重试一次
429	RATE_LIMITED	超限	按退避策略重试
500	INTERNAL_ERROR	服务异常	快速重试 3 次，仍失败上报

---

2. WebSocket API

2.1 连接与鉴权

{
  "op": "login",
  "args": {
    "key": "<account_address>",
    "timestamp": "<epoch_ms>",
    "signature": "<ed25519_signature_base64>"
  }
}

• 连接 URL：wss://ws.pacifica.fi/ws
• 心跳：客户端每 30 秒发送 {"op":"ping"}，收到 {"op":"pong"}；10 秒内无响应视为断线。
• 断线重连需回放增量：lastSeq 由订阅回调附带，重连时通过 {"op":"subscribe","channel":"orders","lastSeq":12345}。

2.2 订阅频道

频道	事件结构	说明
book.{symbol}	{ seq, bids:[[px,sz],...], asks:[], ts }	影子订单簿、延迟监控
trades.{symbol}	{ seq, side, price, size, tradeId, ts }	剥头皮信号、回测
orders.{subaccount}	{ seq, orderId, clientId, status, filled, remaining, avgPrice, ts }	同步本地状态
fills.{subaccount}	{ seq, orderId, tradeId, price, size, fee, liquidity, ts }	GridMaker / Scalper onFill
account.{subaccount}	{ seq, balances:[...], positions:[...] }	风控快照

2.3 消息处理规范

1. 依据 seq 单调递增校验；出现跳号立即触发 full snapshot。
2. 所有事件写入 events.log（用于回放），并发送到内存事件总线。

3. WS 错误回执：

   { "op":"error", "code":"RATE_LIMITED", "message":"..." }
   

   • RATE_LIMITED → 立刻退订 5 秒，重订。
   • AUTH_FAILED → 触发 Kill-switch。

2.4 重连策略

flowchart TD
    A[连接断开] --> B{重试次数 < 5?}
    B -- 是 --> C[等待 backoff (0.5s × 2^n)]
    C --> D[重连 → login → resubscribe]
    D -->|成功| E[恢复]
    D -->|失败| B
    B -- 否 --> F[触发 HALT + 告警]

---

3. 调用封装约定

• 所有 REST 请求均通过 PacificaHttpClient，统一附加签名、限频控制、日志。
• WS 由 PacificaWebSocket 封装，提供：
  • subscribe(channel, handler)
  • unsubscribe(channel)
  • onReconnect(cb)：用于重新分发共享 socket。
• Adapter 暴露 Promise API，错误以自定义错误类区分：
  • PacificaValidationError
  • PacificaRateLimitError
  • PacificaAuthError
  • PacificaUnavailableError

---

4. 监控指标

指标	标签	含义
pacifica_rest_requests_total	endpoint, status	REST 请求计数
pacifica_rest_latency_ms_bucket	endpoint	REST 延迟直方图
pacifica_ws_events_total	channel, type	WS 事件数量
pacifica_ws_reconnects_total		重连次数
pacifica_ws_gaps_total	channel	序列号断层次数

报警建议：

• 5 分钟内 pacifica_ws_reconnects_total 增长 > 3：触发网络告警。
• pacifica_rest_requests_total{status="429"} 连续 10 次：提示策略降频。

---

5. 集成清单

• signing.ts 单元测试覆盖空 body、有序列化差异、错误私钥。
• REST/WS 客户端具备重试、限流、断线恢复。
• 统一错误码映射并接入降级策略。
• Prometheus 指标注册并在 Telemetry 包内导出。
• 文档随 API 变化更新版本号。