## Pacifica 集成指引（Node/TypeScript）

本文件总结了在本项目中成功打通 Pacifica REST 下单/撤单/全撤 与订单簿的方式、要点与排错建议。快速回归与更完整的用例请参考 `docs/pacifica/TESTS.md`。

### 关键要点（务必遵守）

- 签名实现必须严格按官方“签名实现”流程：构造 { timestamp, expiry_window, type, data }，递归按键名排序，生成紧凑 JSON，再用 Ed25519 对字节串签名；最终请求体将签名头与“原始业务字段”平铺，而不是包裹在 data 中。
  - 参考文档：签名实现 https://docs.pacifica.fi/api-documentation/api/signing/implementation
- 下单与撤单“签名仅覆盖业务字段”，不能包含 `account` 或 `agent_wallet` 等请求体外层字段。
- 交易对符号：Pacifica 订单簿与下单要求基础符号，如 `BTC`。若你使用 `BTC-USD` 或 `BTCUSDT`，请在发起请求前归一化为 `BTC`。
- `client_order_id` 需要 UUID（v4）。
- 市价单必须带 `slippage_percent`（如 "0.5"），可使用 IOC。
- 撤单签名字段：`symbol + (order_id 或 client_order_id)`。
- 全撤签名字段：`all_symbols`、`exclude_reduce_only`、可选 `symbol`（当 all_symbols=false 时必需）。
- 批量接口不对整个 batch 体签名，而是对内部每个 Create/Cancel 动作分别签名。

### 主要 REST 端点（已对齐）

- 订单簿：`GET /api/v1/book?symbol=BTC`（成功）
  - 文档：https://docs.pacifica.fi/api-documentation/api/rest-api/markets/get-orderbook
- 市价单：`POST /api/v1/orders/create_market`（成功）
  - 文档：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/create-market-order
- 限价单：`POST /api/v1/orders/create`（成功）
  - 文档：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/create-limit-order
- 撤单：`POST /api/v1/orders/cancel`（成功）
  - 文档：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/cancel-order
- 全撤：`POST /api/v1/orders/cancel_all`（成功）
  - 文档：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/cancel-all-orders
- 批量：`POST /api/v1/orders/batch`（已支持每动作单独签名）
  - 文档：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/batch-order

### 环境变量（最小集合）

- `PACIFICA_ACCOUNT`：主账户公钥（Base58）。必须与私钥派生一致。
- `PACIFICA_ACCOUNT_PRIVATE_KEY`：主账户私钥（Base58 或 64/32 字节 JSON 数组）。
- 可选：`PACIFICA_USE_AGENT=1`、`PACIFICA_AGENT_WALLET`、`PACIFICA_AGENT_PRIVATE_KEY` 用于代理钱包下单（需先绑定）。
- 调试：`PACIFICA_DEBUG=1` 打印签名数据与最终请求体（签名值只打印前缀）。

### 成功请求示例（简化）

- 订单簿（公开）

```bash
curl 'https://api.pacifica.fi/api/v1/book?symbol=BTC'
```

- 市价单（IOC）签名覆盖字段：symbol, amount, side, reduce_only, client_order_id, slippage_percent

```typescript
const res = await ex.placeOrder({
  symbol: 'BTC',
  side: 'BUY',
  type: 'MARKET',
  quantity: '0.001',
  tif: 'IOC',
})
```

- 限价单（GTC）签名覆盖字段：symbol, price, amount, side, tif, reduce_only, client_order_id

```typescript
const res = await ex.placeOrder({
  symbol: 'BTC',
  side: 'SELL',
  type: 'LIMIT',
  quantity: '0.001',
  price: '112200',
  tif: 'GTC',
})
```

- 撤单（优先用 order_id；如无则用 client_order_id）

```typescript
await ex.cancelOrder('BTC', '281317418')
```

- 全撤（按符号）

```typescript
await ex.cancelAll('BTC')
```

- 批量（每个动作单独签名后打包）

```json
{
  "actions": [
    {
      "type": "Create",
      "data": {
        /* 已签名的 create_order 体 */
      }
    },
    {
      "type": "Cancel",
      "data": {
        /* 已签名的 cancel_order 体 */
      }
    }
  ]
}
```

### 常见错误与定位

- 400 Verification failed
  - 检查 `PACIFICA_ACCOUNT` 与 `PACIFICA_ACCOUNT_PRIVATE_KEY` 是否一致（用私钥派生的公钥需等于 account）。
  - 检查签名数据集是否仅包含“业务字段”，字段名/大小写与文档一致；`client_order_id` 必须是 UUID。
  - `symbol` 必须是基础符号（如 `BTC`）。
- 500 Internal server error（下单）
  - 常见因 `symbol` 不规范或 `client_order_id` 非 UUID；或价格/精度不合法（限价）。
- 403 openOrders
  - 受保护/受限端点（可能为 CDN/鉴权策略）；不影响下单/撤单功能验证。

### 当前实现要点（本项目）

- `PacificaClient`：Ed25519 签名、固定端点、可选代理钱包；Header 级签名已对敏感 POST 关闭（仅用 body 签名）。
- `PacificaAdapter`：
  - `symbols()`/`depth()`：使用公开端点；`depth()` 支持符号归一化。
  - `placeOrder()`：市价单自动补 `slippage_percent='0.5'`；所有下单/撤单均归一化 symbol 为基础符号。
  - `cancelOrder()`：签名字段仅 `symbol + (order_id|client_order_id)`。
  - `cancelAll()`：签名 `cancel_all_orders` 的数据字段，再与 `account` 平铺。
  - `batch()`：逐动作单签名，然后统一提交。
  - `setPositionTpSl()`：使用 `/api/v1/positions/tpsl`，统一规范化符号并按 `set_position_tpsl` 规则签名。

### 参考文档

- 签名实现：https://docs.pacifica.fi/api-documentation/api/signing/implementation
- Get orderbook：https://docs.pacifica.fi/api-documentation/api/rest-api/markets/get-orderbook
- Create market order：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/create-market-order
- Create limit order：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/create-limit-order
- Cancel order：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/cancel-order
- Cancel all orders：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/cancel-all-orders
- Batch order：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/batch-order