# Pacifica API 完整参考文档

**文档来源**: https://docs.pacifica.fi/api-documentation/api
**更新时间**: 2025-09-26
**SDK支持**: Python SDK - https://github.com/pacifica-fi/python-sdk

## 概述

Pacifica 是基于 Solana 的永续合约去中心化交易所，提供完整的 REST 和 WebSocket API 来支持程序化交易和账户管理。

### 关键特性

- 🔐 **安全认证**: 支持API签名和硬件钱包集成
- ⚡ **实时数据**: WebSocket 订阅实时市场和账户数据
- 🎯 **全面交易**: 支持市价单、限价单、止损单等多种订单类型
- 👥 **子账户**: 完整的子账户管理功能
- 📊 **数据丰富**: 历史交易、资金费率、K线数据等

## 认证机制

### 1. API 签名认证

```javascript
// 签名流程
const message = `${method}${path}${timestamp}${body}`
const signature = sign(message, privateKey)
```

### 2. 支持的认证方式

- **API Agent Keys**: 用于程序化交易
- **硬件钱包**: 支持 Ledger、Phantom 等
- **私钥签名**: 标准的 Ed25519 签名

## REST API 端点

### 基础信息

**Base URL**: `https://api.pacifica.fi`
**内容类型**: `application/json`
**签名头**: `Pacifica-Signature`

### 市场数据 API

#### 1. 获取市场信息

```http
GET /api/v1/info
```

**响应**: 返回所有可交易市场的基本信息

#### 2. 获取价格信息

```http
GET /api/v1/prices
```

**响应**: 所有交易对的最新价格

#### 3. 获取K线数据

```http
GET /api/v1/kline
```

**参数**:

- `symbol`: 交易对符号
- `interval`: 时间间隔 (1m, 5m, 15m, 1h, 4h, 1d)
- `startTime`: 开始时间戳
- `endTime`: 结束时间戳

#### 4. 获取订单簿

```http
GET /api/v1/book
```

**参数**:

- `symbol`: 交易对符号
- `depth`: 深度级别 (可选)

#### 5. 获取最近交易

```http
GET /api/v1/trades
```

**参数**:

- `symbol`: 交易对符号
- `limit`: 返回数量限制

#### 6. 获取历史资金费率

```http
GET /api/v1/funding
```

**参数**:

- `symbol`: 交易对符号
- `startTime`: 开始时间
- `endTime`: 结束时间

### 账户管理 API

#### 1. 获取账户信息

```http
POST /api/v1/account/info
```

**认证**: 必需
**响应**: 账户基础信息、权益、保证金等

#### 2. 更新杠杆

```http
POST /api/v1/account/leverage
```

**认证**: 必需
**参数**:

```json
{
  "account": "账户地址",
  "symbol": "交易对",
  "leverage": 10,
  "agent_wallet": "代理钱包地址",
  "timestamp": 1234567890,
  "expiry_window": 30000,
  "signature": "签名"
}
```

#### 3. 更新保证金模式

```http
POST /api/v1/account/margin_mode
```

**认证**: 必需
**参数**: 保证金模式设置

#### 4. 获取仓位信息

```http
GET /api/v1/account/positions
```

**认证**: 必需
**响应**: 当前所有持仓信息

#### 5. 获取交易历史

```http
GET /api/v1/account/trades
```

**认证**: 必需
**参数**:

- `symbol`: 交易对 (可选)
- `startTime`: 开始时间
- `endTime`: 结束时间
- `limit`: 数量限制

#### 6. 获取资金历史

```http
GET /api/v1/account/funding
```

**认证**: 必需
**响应**: 资金费率支付记录

#### 7. 请求提现

```http
POST /api/v1/account/withdraw
```

**认证**: 必需
**参数**: 提现金额和目标地址

#### 8. 获取余额

```http
GET /api/v1/account/balance
```

**认证**: 必需
**响应**: 账户各资产余额

### 子账户管理 API

#### 1. 创建子账户

```http
POST /api/v1/account/subaccount/create
```

**认证**: 必需
**参数**:

```json
{
  "main_account": "主账户地址",
  "subaccount": "子账户地址",
  "timestamp": 1234567890,
  "expiry_window": 30000,
  "main_signature": "主账户签名",
  "sub_signature": "子账户签名"
}
```

#### 2. 子账户资金转移

```http
POST /api/v1/account/subaccount/transfer
```

**认证**: 必需
**参数**: 转移金额和方向

### 订单管理 API

#### 1. 下市价单

```http
POST /api/v1/order/market
```

**认证**: 必需
**参数**:

```json
{
  "account": "账户地址",
  "symbol": "BTCUSDT",
  "side": "BUY", // BUY | SELL
  "quantity": "0.1",
  "reduce_only": false,
  "timestamp": 1234567890,
  "expiry_window": 30000,
  "signature": "签名"
}
```

#### 2. 下限价单

```http
POST /api/v1/order/limit
```

**认证**: 必需
**参数**:

```json
{
  "account": "账户地址",
  "symbol": "BTCUSDT",
  "side": "BUY",
  "quantity": "0.1",
  "price": "50000.0",
  "time_in_force": "GTC", // GTC | IOC | FOK
  "post_only": false,
  "reduce_only": false,
  "timestamp": 1234567890,
  "expiry_window": 30000,
  "signature": "签名"
}
```

#### 3. 下止损单

```http
POST /api/v1/order/stop
```

**认证**: 必需
**参数**: 包含触发价格的止损单参数

#### 4. 取消订单

```http
POST /api/v1/order/cancel
```

**认证**: 必需
**参数**:

```json
{
  "account": "账户地址",
  "order_id": "订单ID",
  "timestamp": 1234567890,
  "expiry_window": 30000,
  "signature": "签名"
}
```

#### 5. 批量下单

```http
POST /api/v1/order/batch
```

**认证**: 必需
**参数**: 多个订单的数组

#### 6. 获取当前委托

```http
GET /api/v1/order/open
```

**认证**: 必需
**响应**: 所有未成交订单

#### 7. 获取订单历史

```http
GET /api/v1/order/history
```

**认证**: 必需
**参数**:

- `symbol`: 交易对 (可选)
- `startTime`: 开始时间
- `endTime`: 结束时间
- `limit`: 数量限制

## WebSocket API

### 连接信息

**URL**: `wss://ws.pacifica.fi/ws`
**协议**: WebSocket
**消息格式**: JSON

### 订阅主题

#### 1. 价格订阅

```json
{
  "method": "SUBSCRIBE",
  "params": ["prices@all"],
  "id": 1
}
```

#### 2. 订单簿订阅

```json
{
  "method": "SUBSCRIBE",
  "params": ["orderbook@BTCUSDT"],
  "id": 2
}
```

#### 3. 交易订阅

```json
{
  "method": "SUBSCRIBE",
  "params": ["trades@BTCUSDT"],
  "id": 3
}
```

#### 4. K线订阅

```json
{
  "method": "SUBSCRIBE",
  "params": ["candle@BTCUSDT@1m"],
  "id": 4
}
```

#### 5. 账户余额订阅

```json
{
  "method": "SUBSCRIBE",
  "params": ["balance@{account}"],
  "id": 5
}
```

#### 6. 账户保证金订阅

```json
{
  "method": "SUBSCRIBE",
  "params": ["margin@{account}"],
  "id": 6
}
```

#### 7. 仓位订阅

```json
{
  "method": "SUBSCRIBE",
  "params": ["positions@{account}"],
  "id": 7
}
```

#### 8. 订单更新订阅

```json
{
  "method": "SUBSCRIBE",
  "params": ["orders@{account}"],
  "id": 8
}
```

### 消息格式示例

#### 价格更新消息

```json
{
  "stream": "prices@all",
  "data": {
    "BTCUSDT": {
      "price": "50000.00",
      "change_24h": "2.5%",
      "volume_24h": "1000000"
    }
  }
}
```

#### 订单簿更新消息

```json
{
  "stream": "orderbook@BTCUSDT",
  "data": {
    "bids": [
      ["49900", "0.5"],
      ["49800", "1.0"]
    ],
    "asks": [
      ["50100", "0.3"],
      ["50200", "0.8"]
    ],
    "timestamp": 1234567890
  }
}
```

#### 账户余额更新消息

```json
{
  "stream": "balance@{account}",
  "data": {
    "USDT": {
      "available": "1000.00",
      "locked": "100.00"
    },
    "timestamp": 1234567890
  }
}
```

## 错误处理

### HTTP 状态码

- `200`: 成功
- `400`: 请求参数错误
- `401`: 认证失败
- `403`: 权限不足
- `404`: 端点不存在
- `429`: 请求频率限制
- `500`: 服务器内部错误

### 错误响应格式

```json
{
  "error": {
    "code": 1001,
    "message": "Invalid signature",
    "details": "Signature verification failed"
  }
}
```

### 常见错误码

- `1001`: 签名无效
- `1002`: 时间戳过期
- `1003`: 账户不存在
- `1004`: 余额不足
- `1005`: 订单不存在
- `1006`: 市场暂停交易

## 速率限制

### REST API 限制

- **公开端点**: 每分钟 1000 次请求
- **私有端点**: 每分钟 500 次请求
- **订单相关**: 每秒 10 次请求

### WebSocket 限制

- **连接数**: 每个IP最多 5 个连接
- **订阅数**: 每个连接最多 100 个订阅
- **消息频率**: 每秒 1000 条消息

## 交易规范

### 订单类型

1. **市价单** (Market): 立即按市场价格执行
2. **限价单** (Limit): 指定价格执行
3. **止损单** (Stop): 触发价格后转为市价单
4. **止损限价单** (Stop-Limit): 触发后转为限价单

### 时间有效性 (TIF)

- **GTC** (Good Till Cancelled): 直到取消
- **IOC** (Immediate Or Cancel): 立即执行或取消
- **FOK** (Fill Or Kill): 全部成交或取消

### 订单状态

- `NEW`: 新建订单
- `PARTIALLY_FILLED`: 部分成交
- `FILLED`: 完全成交
- `CANCELED`: 已取消
- `REJECTED`: 被拒绝
- `EXPIRED`: 已过期

## SDK 集成

### Python SDK

```bash
pip install pacifica-fi
```

### 基础用法

```python
from pacifica import PacificaClient

client = PacificaClient(
    base_url="https://api.pacifica.fi",
    private_key="your_private_key"
)

# 获取账户信息
account_info = client.get_account_info()

# 下限价单
order = client.place_limit_order(
    symbol="BTCUSDT",
    side="BUY",
    quantity="0.1",
    price="50000"
)
```

## 最佳实践

### 1. 安全建议

- 使用环境变量存储私钥
- 实施IP白名单
- 定期轮换API密钥
- 启用双重认证

### 2. 性能优化

- 使用WebSocket获取实时数据
- 实施指数退避重试机制
- 批量处理订单操作
- 缓存市场数据

### 3. 错误处理

- 监控速率限制状态
- 实施断线重连机制
- 记录所有API调用
- 设置超时和重试策略

## 技术支持

### 获取帮助

- **Discord**: Pacifica API 频道
- **GitHub**: https://github.com/pacifica-fi/python-sdk
- **文档**: https://docs.pacifica.fi

### 开发资源

- API状态页面
- 测试网环境
- 示例代码库
- 开发者社区

---

_本文档基于 Pacifica 官方 API 文档整理，如有更新请参考官方文档_