# 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`：本文。