# Import Gain/Loss

### API Overview

This API enables the batch import of Gain/Loss records into the system, supporting the import of multiple data entries in a single request.

* **Request Method：**`POST`
* **Request URL：**`https://openapi.elven.com/open/v3/transaction/gainloss`

### Request Headers

<table><thead><tr><th width="202">Parameter Name</th><th width="90">Type</th><th width="100">Required</th><th>Description</th></tr></thead><tbody><tr><td>elven-api-key</td><td>String</td><td>Yes</td><td>The API key assigned to you</td></tr><tr><td>elven-api-sign</td><td>String</td><td>Yes</td><td>Request signature, used to verify the legitimacy of the request</td></tr><tr><td>elven-api-timestamp</td><td>String</td><td>Yes</td><td>Request timestamp, in milliseconds</td></tr></tbody></table>

[View Details](https://docs.elven.com/v3/openapi/obtaining-api-authorization)

### Request Parameters

#### Body Parameters (JSON Format)

<table><thead><tr><th width="207">Parameter Name</th><th width="91">Type</th><th width="98">Required</th><th>Description</th></tr></thead><tbody><tr><td>entityAccountId</td><td>String</td><td>Yes</td><td>The primary key of the account.</td></tr><tr><td>sourceId</td><td>String</td><td>Yes</td><td>The primary key of the source.</td></tr><tr><td>timezone</td><td>String</td><td>No</td><td>Time Zone: If left empty, it will default to the entity’s time zone.<a href="timezone">View Details</a></td></tr><tr><td>list</td><td>Array</td><td>Yes</td><td>Transaction record list, containing multiple transaction objects, with a maximum of 1000 records supported per request.</td></tr></tbody></table>

**Elements in the List**

| Parameter Name | Type   | Required | Description                                                                                                            |
| -------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| datetime       | String | Yes      | Transaction time in the format `YYYY-MM-DD HH:mm:ss`                                                                   |
| gainLossID     | String | No       | Unique identifier for the gain or loss record.                                                                         |
| type           | String | Yes      | Type of gain or loss transaction.                                                                                      |
| positionSide   | String | No       | Future position direction (values: LONG/SHORT). Required only when `type` is `FUTURE_REALIZED` or `FUTURE_UNREALIZED`. |
| asset          | String | Yes      | Name of the underlying asset (maximum 200 characters).                                                                 |
| gainLossAsset  | String | Yes      | Name of the asset used to measure gain or loss (case-sensitive).                                                       |
| gainLossAmount | Number | Yes      | Amount of gain or loss.                                                                                                |
| memo           | String | No       | Additional notes or information.                                                                                       |

#### **Type Parameter Description**

| Type                | Description                             |
| ------------------- | --------------------------------------- |
| FUTURE\_REALIZED    | Realized gain or loss from contracts.   |
| FUTURE\_UNREALIZED  | Unrealized gain or loss from contracts. |
| OPTIONS\_REALIZED   | Realized gain or loss from options.     |
| OPTIONS\_UNREALIZED | Unrealized gain or loss from options.   |

***

#### **PositionSide Parameter Description**

| Type          | Is positionSide required? |
| ------------- | ------------------------- |
| FUTURE\_OPEN  | Required                  |
| FUTURE\_CLOSE | Required                  |
| Other Types   | Must be left empty        |

#### Example Request

```json
{
    "entityAccountId": "QfgBd6vH2ptevhqZjNTn06MiJOFUXGcD",
    "sourceId": "RHFjsy6UIgM1rdxvefXVsJy8L3NOhBmQ",
    "timezone": "UTC",
    "list": [
        {
            "datetime": "2024-08-01 15:59:00",
            "gainLossID": "123458",
            "type": "FUTURE_UNREALIZED",
            "asset": "ETHUSDT-PERP1",
            "positionSide": "LONG",
            "gainLossAsset": "USDT",
            "gainLossAmount": 500,
            "memo": ""
        },
        {
            "datetime": "2024-08-01 16:00:00",
            "gainLossID": "123459",
            "type": "FUTURE_REALIZED",
            "asset": "ETHUSDT-PERP1",
            "positionSide": "LONG",
            "gainLossAsset": "USDT",
            "gainLossAmount": 600,
            "memo": ""
        }
    ]
}

```

### Response Parameters

<table><thead><tr><th width="204">Parameter Name</th><th width="141"> Type</th><th>Description</th></tr></thead><tbody><tr><td>success</td><td>String</td><td>Request status (e.g., <code>success</code>).</td></tr><tr><td>data</td><td>Boolean</td><td>Request result (e.g., <code>true</code> indicates success).</td></tr></tbody></table>

#### Example Response

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

### **Notes**

* **Asynchronous Processing:**  This API only imports the transaction data into a pre-processing database. The system processes the data asynchronously, and the imported transactions will appear in the user's transaction list after processing is complete.
* **Record Limit:**  Each request supports importing up to 1000 transaction records. For larger datasets, split them into multiple requests.
* **Data Integrity:**  Ensure the transaction data is complete and accurate to avoid import errors.
* **Datetime Format**: The `datetime` field must strictly follow the format `YYYY-MM-DD HH:mm:ss`. Parsing errors may occur if the format is incorrect.