> For the complete documentation index, see [llms.txt](https://faq.finerymarkets.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faq.finerymarkets.com/api-reference/rest-api/deals-and-positions/dealhistory.md).

# dealHistory

{% hint style="info" %}
 If the number of deals in the specified period may exceed the limit, the request returns 250 latest deals. To get other deals, a user needs to remember the earliest `DealId` and specify it in the next request(s).
{% endhint %}

**POST api/dealHistory**

{% tabs %}
{% tab title="Payload" %}

```json
{
    "instrument": "BTC-USD",
    "filter": "all"
}
```

{% endtab %}

{% tab title="200 OK" %}

```json
[
    [
        "BTC-USD",       // Instrument name
        0,               // Order type
        0,               // Side
        0,               // Cancel reason
        1234,            // Order id
        0,               // Client order id
        9900000000,      // Order price
        10000000,        // Order initial size or volume
        9998000,         // Remaining order size or volume
        1558051200000,   // Order created at
        1558052600000,   // Deal moment
        12,              // Deal id
        1,               // Deal aggressor side
        9900000000,      // Deal price
        2000,            // Deal size
        19800000000000,  // Deal volume
        100000,          // Deal delta
        14,              // Counterparty id
        0,               // Order created by size or volume
        10,              // Taker order owner id
        0,               // Linked deal id
        0,               // Deal type
        15,              // Maker order owner id
        0,               // Liquidity source
        100000000        // Balance currency price in USD
    ]
]
```

{% endtab %}

{% tab title="400 Bad request" %}

```json
{
    "error": 2
}
```

{% endtab %}
{% endtabs %}

**Request parameters**

| Field name      | Type                | Description                                                                                                                                                                                                                                                            |
| --------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| instrument      | Array \<string>     | <p>Instrument names.</p><p>If specified only return deals for these instruments</p>                                                                                                                                                                                    |
| counterpartyIds | Array Efx::ClientId | Counterparty Ids. If specified only return deals for these counterparties                                                                                                                                                                                              |
| filter          | string              | <p><em>Optional</em> <em>field</em> for master accounts only (FM Liquidity Match).<br>- absent or "all": returns full deals history<br>- "subaccounts": returns deals history with subaccounts<br>- "external": returns deals history with external counterparties</p> |
| till            | Efx::DealId         | If specified only return deals with lesser ID                                                                                                                                                                                                                          |
| from            | Efx::Timestamp      | If specified only return deals with equal or greater timestamp                                                                                                                                                                                                         |
| to              | Efx::Timestamp      | If specified only return deals with lesser timestamp                                                                                                                                                                                                                   |
| limit           | unsigned int16      | <p>Default: 250</p><p>Maximum number of deals to return (capped at 250)</p>                                                                                                                                                                                            |

**Response description**

| Feild name | Type                 | Description                                                                                                                                                                                 |
| ---------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|            | Array of Deals       |                                                                                                                                                                                             |
| **Deal**   | Array\[21]           |                                                                                                                                                                                             |
| 0          | string               | Instrument name                                                                                                                                                                             |
| 1          | unsigned int16       | <p>Order Type</p><p>0 - limit</p><p>1 - post only</p><p>2 - limit IOC</p><p>3 - limit FOK</p><p>4 - market IOC</p><p>5 - market FOK<br>6 - manual trade<br>7 - pending limit<br>9 - RFQ</p> |
| 2          | Efx::Side            | <p>Side</p><p>0 - bid</p><p>1 - ask</p>                                                                                                                                                     |
| 3          | unsigned int16       | <p>Cancel reason</p><p>0 - in place or filled</p><p>1 - by client</p><p>2 - as non-book order</p><p>3 - by self-trade prevention</p><p>4 - cancel-on-disconnect</p>                         |
| 4          | Efx::OrderId         | Order id                                                                                                                                                                                    |
| 5          | Efx::ClientOrderId   | Client order id                                                                                                                                                                             |
| 6          | Efx::Price           | Order price                                                                                                                                                                                 |
| 7          | Efx::Size            | Order Initial Size Or Volume (depending on whether order was initiated by volume)                                                                                                           |
| 8          | Efx::Size            | Remaining Order Size Or Volume after deal (depending on whether order was initiated by volume)                                                                                              |
| 9          | Efx::Timestamp       | Order Created At                                                                                                                                                                            |
| 10         | Efx::Timestamp       | Deal Moment                                                                                                                                                                                 |
| 11         | Efx::DealId          | Deal id                                                                                                                                                                                     |
| 12         | Efx::Side            | <p>Deal aggressor side</p><p>0 - bid</p><p>1 - ask</p>                                                                                                                                      |
| 13         | Efx::Price           | Deal price                                                                                                                                                                                  |
| 14         | Efx::Size            | Deal size                                                                                                                                                                                   |
| 15         | Efx::Size            | Deal volume                                                                                                                                                                                 |
| 16         | Efx::Size            | Deal delta in quote (balance) currency                                                                                                                                                      |
| 17         | Efx::ClientId        | Counterparty id                                                                                                                                                                             |
| 18         | unsigned int16       | <p>If order was created by size or by volume</p><p>0 - by size</p><p>1 - by volume</p>                                                                                                      |
| 19         | Efx::ClientId        | Id of a taker who placed the order                                                                                                                                                          |
| 20         | Efx::DealId          | Deal ID current deal is linked to. Deals can be linked when trade happens through the master's account.                                                                                     |
| 21         | DealType             | <p>0 - regular<br>1 - authorized trade<br>2 - liquidation trade</p>                                                                                                                         |
| 22         | Efx::ClientId        | Id of a maker who placed the order                                                                                                                                                          |
| 23         | Efx::LiquiditySource | Source of the liquidity for the deal                                                                                                                                                        |
| 24         | Efx::Price           | Balance currency price in USD                                                                                                                                                               |