grid_skeleton/docs/API_SPEC_Pacifica_Signing.md

Pacifica API 对接规范（仓库内说明）

重要：以下为仓库集成的对接说明与占位模板。以官方文档为准： https://docs.pacifica.fi/api-documentation/api

1. 环境

• 主网 REST: https://api.pacifica.fi/api/v1
• 测试网 REST: https://test-api.pacifica.fi/api/v1
• WebSocket：按官方文档使用（若提供）。

2. 鉴权与签名（Ed25519）

• POST 请求需签名；GET/行情通常无需签名（以官方为准）。
• 请求必须包含：timestamp、type（operation type）、signature、X-API-KEY 等（字段名以官方为准）。
• 签名输入：确定性 JSON 序列化 的请求体；算法：Ed25519；编码：Base64/Hex 以官方为准。
• 本仓库的占位代码：packages/connectors/pacifica/src/signing.ts。你必须按照官方规范替换 signRequest 的实现。

签名步骤（模板）

1. 生成 timestamp（毫秒）；
2. 构造 payload（字段顺序按官方示例）；
3. 对序列化字节做哈希（如需）→ Ed25519 私钥签名；
4. 在 Header 中放入 X-API-KEY、X-TS、X-SIGNATURE（或官方要求的键名）；
5. Body 放 payload JSON。

3. 主要端点（示例清单）

• 市场规格：GET /api/v1/info
• 订单簿：GET /api/v1/book?symbol=XXX&agg_level=1
• 下单：POST /api/v1/orders/create（字段：symbol/side/price/size/tif/postOnly/clientId/...）
• 撤单：POST /api/v1/orders/cancel（字段：orderId/...）
• 批量撤：POST /api/v1/orders/cancel_all
• 持仓：GET /api/v1/account/positions
• 资金费率/最近成交/K线：参考 Markets 章节

注意：以上字段名/路径仅作仓库内对接导航，请以官方页面实时为准。

4. 错误与限频

• HTTP 4xx/5xx 需解析并上报；
• 遵守 API Config Keys / Rate limits；
• 对 429/限频，使用指数退避 + 配额窗口重试。

5. STP（自成交预防）

• 若平台原生支持，仍建议在本地做影子簿检查：
  • 下单前校验对手价是否为自家挂单；
  • 必要时先撤旧单再挂新单。

6. 本仓库落地位置

• packages/connectors/pacifica/src/adapter.ts：REST 封装；
• packages/connectors/pacifica/src/signing.ts：签名占位；
• docs/PRD_Pacifica_DeltaNeutral_Scalping.md：策略与系统需求；
• docs/API_SPEC_Pacifica_Signing.md：本文。