# 导入交易记录接口

### 接口概述

该接口用于批量导入交易记录到系统中，支持一次性导入多条交易数据。新增按照**资产代码**传递资产信息的能力。（原有 V3 版本接口，必须使用 Elven 系统的资产 id 来传递资产信息）

* **请求方式**：`POST`
* **请求 URL**：`https://openapi.elven.com/open/v4/transaction/trade`

### 请求头参数

<table><thead><tr><th width="202">参数名</th><th width="90">类型</th><th width="64">必填</th><th>说明</th></tr></thead><tbody><tr><td>elven-api-key</td><td>String</td><td>是</td><td>分配给您的API密钥</td></tr><tr><td>elven-api-sign</td><td>String</td><td>是</td><td>请求签名，用于验证请求合法性</td></tr><tr><td>elven-api-timestamp</td><td>String</td><td>是</td><td>请求时间戳，毫秒级</td></tr></tbody></table>

[查看详细说明](https://docs.elven.com/v3/openapi/jie-kou-shou-quan#elven-api-sign)

### 请求参数

#### Body 参数（JSON 格式）

<table><thead><tr><th width="207">参数名</th><th width="91">类型</th><th width="65">必填</th><th>说明</th></tr></thead><tbody><tr><td>entityAccountId</td><td>String</td><td>是</td><td>账户的主键 ID</td></tr><tr><td>sourceId</td><td>String</td><td>是</td><td>Source 的主键 ID</td></tr><tr><td>timezone</td><td>String</td><td>否</td><td>时区，为空时视为 entity 时区。<a href="../shi-qu-xin-xi">具体介绍</a></td></tr><tr><td>list</td><td>Array</td><td>是</td><td>包含多条交易记录的数组（每次最多支持 5000 条记录）</td></tr></tbody></table>

**list 数组元素**

<table><thead><tr><th width="203">参数名</th><th width="95">类型</th><th width="57">必填</th><th>说明</th></tr></thead><tbody><tr><td>datetime</td><td>String</td><td>是</td><td>交易时间，格式为 <code>YYYY-MM-DD HH:mm:ss</code></td></tr><tr><td>tradeID</td><td>String</td><td>否</td><td>交易哈希或唯一标识</td></tr><tr><td>type</td><td>String</td><td>是</td><td>交易类型</td></tr><tr><td>positionSide</td><td>String</td><td>否</td><td>合约持仓方向（枚举值：LONG/SHORT）。仅在 type 为 <code>FUTURE_OPEN</code> 或 <code>FUTURE_CLOSE</code> 时必填</td></tr><tr><td>baseAssetID</td><td>String</td><td>否</td><td><p>标的资产名称（最大 200 字符）<br>SPOT_BUY/SPOT_SELL/SWAP类型的交易，需要填写对应加密货币的币种 ID/Symbol，区分大小写<br>FOREIGN_EXCHANGE类型的交易，需要填写对应法币的币种 ID/Symbol，区分大小写<br>可从<a href="../v3/zi-chan-cha-xun-jie-kou">资产查询接口</a>当前 entity 所支持的币种<br><code>baseAssetID</code>和<code>baseAssetSymbol</code>至少填写一个</p><p>都填写时，只会识别<code>baseAssetID</code><br><code>FUTURE_OPEN</code>、<code>FUTURE_CLOSE</code>、<code>FUTURE_ONEWAY_BUY</code>、<code>FUTURE_ONEWAY_SELL</code>  类型的的transfer将只会识别<code>baseAssetSymbol</code></p></td></tr><tr><td>baseAssetSymbol</td><td>String</td><td>否</td><td><p>标的资产名称（最大 200 字符）<br>SPOT_BUY/SPOT_SELL/SWAP类型的交易，需要填写对应加密货币的币种 ID/Symbol，区分大小写<br>FOREIGN_EXCHANGE类型的交易，需要填写对应法币的币种 ID/Symbol，区分大小写<br>可从<a href="../v3/zi-chan-cha-xun-jie-kou">资产查询接口</a>当前 entity 所支持的币种<br><code>baseAssetID</code>和<code>baseAssetSymbol</code>至少填写一个</p><p>都填写时，只会识别<code>baseAssetID</code></p></td></tr><tr><td>baseAmount</td><td>Number</td><td>是</td><td>标的资产金额</td></tr><tr><td>counterAssetID</td><td>String</td><td>否</td><td>计价资产币种ID，需区分大小写，可从<a href="../v3/zi-chan-cha-xun-jie-kou">资产查询接口</a>当前 entity 所支持的币种<br><code>counterAssetID</code> 和<code>counterAssetSymbol</code> 都填写时，只会识别<code>counterAssetID</code></td></tr><tr><td>counterAssetSymbol</td><td>String</td><td>否</td><td>计价资产币种代码，需区分大小写，可从<a href="../v3/zi-chan-cha-xun-jie-kou">资产查询接口</a>当前 entity 所支持的币种<br><code>counterAssetID</code> 和<code>counterAssetSymbol</code> 都填写时，只会识别<code>counterAssetID</code></td></tr><tr><td>counterAmount</td><td>Number</td><td>是</td><td>计价资产金额</td></tr><tr><td>feeAssetID</td><td>String</td><td>否</td><td>手续费币种ID，需区分大小写，可从<a href="../v3/zi-chan-cha-xun-jie-kou">资产查询接口</a>当前 entity 所支持的币种<br><code>feeAssetID</code> 和<code>feeAssetSymbol</code> 都填写时，只会识别<code>feeAssetID</code></td></tr><tr><td>feeAssetSymbol</td><td>String</td><td>否</td><td>手续费币种代码，需区分大小写，可从<a href="../v3/zi-chan-cha-xun-jie-kou">资产查询接口</a>当前 entity 所支持的币种<br><code>feeAssetID</code> 和<code>feeAssetSymbol</code> 都填写时，只会识别<code>feeAssetID</code></td></tr><tr><td>feeAmount</td><td>Number</td><td>否</td><td>手续费金额</td></tr><tr><td>memo</td><td>String</td><td>否</td><td>备注信息</td></tr></tbody></table>

**type 参数说明**

<table><thead><tr><th width="254">交易类型</th><th>说明</th></tr></thead><tbody><tr><td>FUTURE_OPEN</td><td>开仓</td></tr><tr><td>FUTURE_CLOSE</td><td>平仓</td></tr><tr><td></td><td></td></tr><tr><td></td><td></td></tr><tr><td>OPTION_BUY</td><td>期权买入</td></tr><tr><td>OPTION_SELL</td><td>期权卖出</td></tr><tr><td>OPTION_EXERCISE</td><td>期权行权</td></tr><tr><td>SPOT_BUY</td><td>现货买入</td></tr><tr><td>SPOT_SELL</td><td>现货卖出</td></tr><tr><td>FOREIGN_EXCHANGE</td><td>外汇交易</td></tr><tr><td>SWAP</td><td>兑换</td></tr></tbody></table>

#### **PositionSide 参数说明**

| type          | positionSide 是否必填 |
| ------------- | ----------------- |
| FUTURE\_OPEN  | 必填                |
| FUTURE\_CLOSE | 必填                |
| 其他类型          | 必须为空              |

#### 请求示例

```json
{
    "entityAccountId": "w597WQZ5SzfKegoGB8qF1XRA2D39dr0U",
    "sourceId": "mKEd2CxfIvclgwCMqOpn8m9iYZ16Bde4",
    "timezone":"UTC",
    "list": [
        {
        	"datetime": "2025-01-02 11:13:00",
            "tradeID": "12341",
            "type": "FUTURE_ONEWAY_BUY",
            "positionSide":"BOTH",
            "baseAssetID":"",
            "baseAssetSymbol":"Binance-ETHUSDT-PERP1",
            "baseAmount":1,
            "counterAssetID":"USDT",
            "counterAssetSymbol":"Binance-ETHUSDT-PERP1",
            "counterAmount":2,
            "feeAssetSymbol":"USDT",
            "feeAssetID":"USDT",
            "feeAmount":3,
            "memo":"231",
            "originalType":"231"
        }
    ]
}
```

#### 响应参数

| 参数名    | 类型      | 说明                  |
| ------ | ------- | ------------------- |
| status | String  | 请求状态（如 `success`）   |
| data   | Boolean | 请求结果（如 `true` 表示成功） |

#### 响应示例

```json
{
    "status": "success",
    "data": true
}

```

### 注意事项

1. **异步处理**：该接口调用成功后只是将数据导入到预处理数据库，系统需要一段时间来处理导入的交易数据，处理完成后才会显示在用户交易列表内。
2. **记录数量限制**：每次请求最多支持导入 **5000** 条交易记录。
3. **数据完整性**：请确保提供的交易数据完整且准确，避免因数据错误导致导入失败。
4. **时间格式**：`datetime` 参数的格式必须严格按照 `YYYY-MM-DD HH:mm:ss`，否则可能导致解析错误。
5. **交易类型**：`type` 参数必须选择正确的值，具体规则见上文。