## Pacifica 集成测试说明（可直接运行）

### 一、准备工作

- 环境变量（.env）：
  - `PACIFICA_BASE_URL=https://api.pacifica.fi`
  - `PACIFICA_WS_URL=wss://ws.pacifica.fi`
  - `PACIFICA_ACCOUNT`（主账户公钥，Base58）
  - `PACIFICA_PRIVATE_KEY` 或 `PACIFICA_ACCOUNT_PRIVATE_KEY`（主账户私钥，Base58 或 32/64 字节 JSON 数组）
  - 可选代理钱包：`PACIFICA_AGENT_WALLET`、`PACIFICA_AGENT_PRIVATE_KEY`
- 推荐开启 debug：`PACIFICA_DEBUG=1`（会打印签名数据与打码后的最终请求体）

### 二、测试脚本

- 入口：`examples/pacifica_test.ts`
- 运行：

```bash
PACIFICA_ENABLE_TEST_ORDER=1 yarn test:pacifica
# 启用 TP/SL 单例测试
PACIFICA_ENABLE_TEST_ORDER=1 PACIFICA_ENABLE_TEST_STOP=1 yarn test:pacifica
# WebSocket 简易订阅（深度/订单/余额/成交），默认 15s 后退出
yarn test:pacifica:ws
```

### 三、覆盖范围（已打通）

- 市价下单（BUY/SELL，IOC）
- 限价下单（GTC）与撤单（cancelOrder）
- 全撤（cancelAll）
- 仓位 TP/SL（使用 `/api/v1/positions/tpsl`，`set_position_tpsl` 签名）
  - 支持单独设置 `TP` 或 `SL`（推荐先验证单例，可规避部分后端校验路径）
- 批量接口（`/api/v1/orders/batch`）：
  - 混合用例（Create 两笔 + Cancel 其中一笔），逐动作单独签名
  - 注意 Create 的签名字段需包含 `reduce_only`

### 四、重要细节

- 符号规范化：下单/TP/SL/订单簿等都使用基础符号（如 `BTC`），测试脚本已统一处理
- 签名仅覆盖业务字段；`account/agent_wallet` 不参与签名
- `client_order_id` 使用 UUID；`slippage_percent` 默认 `0.5`
- 知悉问题：`openOrders()` 在当前环境返回 403（CDN/白名单/权限），不影响其他路径
- WebSocket（无需 login）：
  - 连接 `wss://ws.pacifica.fi/ws`，然后直接发送订阅消息：

```json
{"method":"subscribe","params":{"source":"prices"}}
{"method":"subscribe","params":{"source":"book","symbol":"BTC","agg_level":1}}
{"method":"subscribe","params":{"source":"account_info","account":"<BASE58>"}}
{"method":"subscribe","params":{"source":"account_balance","account":"<BASE58>"}}
{"method":"subscribe","params":{"source":"account_positions","account":"<BASE58>"}}
{"method":"subscribe","params":{"source":"account_orders","account":"<BASE58>"}}
```

- 心跳：每 60s 内需有消息；建议每 30s 发送 `{"method":"ping"}`，服务端会返回 `{"channel":"pong"}`
- `channel` 值与订阅源一致：`prices`、`book`、`trades`、`account_info`、`account_balance`、`account_positions`、`account_orders`

### 五、常见错误与处理

- Verification failed：
  - 检查签名字段是否与文档一致（大小写、嵌套结构）；
  - 检查 `PACIFICA_ACCOUNT` 与私钥派生公钥是否一致；
- 500 Internal server error（TP/SL）：
  - 先用 TP 或 SL 单例测试；保留 `PACIFICA_DEBUG=1` 日志提交官方定位

### 六、参考文档

- 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
- Create stop order：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/create-stop-order
- Create position TP/SL：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/create-position-tp-sl
- Batch order：https://docs.pacifica.fi/api-documentation/api/rest-api/orders/batch-order
- 签名实现：https://docs.pacifica.fi/api-documentation/api/signing/implementation
- WS 订阅：
  - Prices：https://docs.pacifica.fi/api-documentation/api/websocket/subscriptions/prices
  - Orderbook：https://docs.pacifica.fi/api-documentation/api/websocket/subscriptions/orderbook
  - Account info：https://docs.pacifica.fi/api-documentation/api/websocket/subscriptions/account-info
  - Account balance：https://docs.pacifica.fi/api-documentation/api/websocket/subscriptions/account-balance
  - Account positions：https://docs.pacifica.fi/api-documentation/api/websocket/subscriptions/account-positions