---
title: "List Past Orders"
method: POST
path: "/v1/orders/history"
tags: ["Orders"]
---

# List Past Orders

`POST /v1/orders/history`

## Request

- Base URL: `https://api.gemini.com`
- URL: `https://api.gemini.com/v1/orders/history`
- Auth: API key in header `X-GEMINI-APIKEY` and API key in header `X-GEMINI-SIGNATURE` and API key in header `X-GEMINI-PAYLOAD`

This API retrieves (closed) orders history for an account.

### Roles
The API key you use to access this endpoint must have the Trader or Auditor role assigned. See [Roles](/roles#roles) for more information.

The OAuth scope must have `history:read` assigned to access this endpoint. See [OAuth Scopes](/authentication/oauth#oauth-scopes) for more information.


### How to retrieve your order history

To retrieve your full order history walking backwards,

1. Initial request: `POST` to https://api.gemini.com/v1/orders/history with a JSON payload including a `timestamp` key with value `0` and a `limit_orders` key with value `500`
2. When you receive the list of orders, it will be sorted by `timestamp` descending - so the first element in the list will have the highest `timestamp` value. For this example, say that value is `X`.
3. Create a second `POST` request with a JSON payload including a `timestamp` key with value `X+1` and a `limit_orders` key with value `500`.
4. Take the first element of the list returned with highest `timestamp` value `Y` and create a third `POST` request with a JSON payload including a `timestamp` key with value `Y+1` and a `limit_orders` key with value `500`.
5. Continue creating `POST` requests and retrieving orders until an empty list is returned.

### Break Types

In the rare event that a trade has been reversed (broken), the trade that is broken will have this flag set. The field will contain one of these values

|Value|Description|
|--- |--- |
|manual|The trade was reversed manually.  This means that all fees, proceeds, and debits associated with the trade have been credited or debited to the account seperately.  That means that this reported trade must be included for order for the account balance to be correct.|
|full|The trade was fully broken.  The reported trade should not be accounted for.  It will be as though the transfer of fund associated with the trade had simply not happened.|

## Headers

- `X-GEMINI-APIKEY` string, required
- `X-GEMINI-SIGNATURE` string, required
- `X-GEMINI-PAYLOAD` string, required
- `Content-Type` string
- `Content-Length` string
- `Cache-Control` string

## Request body

- object
  - `request` string, required: The API endpoint `/v1/orders/history`
  - `nonce` union, required: The nonce, as described in [Private API Invocation](/authentication/api-key#private-api-invocation)
    - union: timestamp
      - string: Gemini strongly recommends using milliseconds instead of seconds for timestamps. | Timestamp format | Example | Supported request type | |-----------------------|-----------------------|------------------------| | string (seconds) | `1495127793` | `POST` only | | string (milliseconds) | `1495127793000` | `POST` only |
      - integer: Gemini strongly recommends using milliseconds instead of seconds for timestamps. | Timestamp format | Example | Supported request type | |-----------------------------|---------------------------|------------------------| | whole number (seconds) | `1495127793` | `GET`, `POST` | | whole number (milliseconds) | `1495127793000` | `GET`, `POST` |
    - integer
  - `symbol` string: The symbol to retrieve orders for
  - `limit_orders` integer: The maximum number of orders to return. Default is 50, max is 500.
  - `timestamp` union: timestamp
    - string: Gemini strongly recommends using milliseconds instead of seconds for timestamps. | Timestamp format | Example | Supported request type | |-----------------------|-----------------------|------------------------| | string (seconds) | `1495127793` | `POST` only | | string (milliseconds) | `1495127793000` | `POST` only |
    - integer: Gemini strongly recommends using milliseconds instead of seconds for timestamps. | Timestamp format | Example | Supported request type | |-----------------------------|---------------------------|------------------------| | whole number (seconds) | `1495127793` | `GET`, `POST` | | whole number (milliseconds) | `1495127793000` | `GET`, `POST` |
  - `account` string: Required for Master API keys as described in [Private API Invocation](/authentication/api-key#private-api-invocation). The name of the account within the subaccount group.

## Response `200`

Successful operation

- Order[]
  - `order_id` string, integer: The order id
  - `client_order_id` string, integer: An optional [client-specified order id](/client-order-id#client-order-id)
  - `symbol` string: The [symbol](/market-data/symbols-and-minimums#symbols-and-minimums) of the order
  - `exchange` string: Will always be "gemini"
  - `price` string, decimal: The price the order was issued at
  - `avg_execution_price` string, decimal: The average price at which this order as been executed so far. 0 if the order has not been executed at all.
  - `side` 'buy' | 'sell'
  - `type` 'exchange limit' | 'exchange stop limit' | 'exchange market': Description of the order
  - `options` string[]: An array containing at most one supported order execution option. See [Order execution options](/rest/orders#create-new-order) for details.
  - `timestamp` union: timestamp
    - string: Gemini strongly recommends using milliseconds instead of seconds for timestamps. | Timestamp format | Example | Supported request type | |-----------------------|-----------------------|------------------------| | string (seconds) | `1495127793` | `POST` only | | string (milliseconds) | `1495127793000` | `POST` only |
    - integer: Gemini strongly recommends using milliseconds instead of seconds for timestamps. | Timestamp format | Example | Supported request type | |-----------------------------|---------------------------|------------------------| | whole number (seconds) | `1495127793` | `GET`, `POST` | | whole number (milliseconds) | `1495127793000` | `GET`, `POST` |
  - `timestampms` union: timestamp
    - string: Gemini strongly recommends using milliseconds instead of seconds for timestamps. | Timestamp format | Example | Supported request type | |-----------------------|-----------------------|------------------------| | string (seconds) | `1495127793` | `POST` only | | string (milliseconds) | `1495127793000` | `POST` only |
    - integer: Gemini strongly recommends using milliseconds instead of seconds for timestamps. | Timestamp format | Example | Supported request type | |-----------------------------|---------------------------|------------------------| | whole number (seconds) | `1495127793` | `GET`, `POST` | | whole number (milliseconds) | `1495127793000` | `GET`, `POST` |
  - `is_live` boolean: `true` if the order is active on the book (has remaining quantity and has not been canceled)
  - `is_cancelled` boolean: `true` if the order has been canceled. Note the spelling, "cancelled" instead of "canceled". This is for compatibility reasons.
  - `reason` string: Populated with the reason your order was canceled, if available.
  - `was_forced` boolean: Will always be `false`.
  - `executed_amount` string, decimal: The amount of the order that has been filled.
  - `remaining_amount` string, decimal: The amount of the order that has not been filled.
  - `original_amount` string, decimal: The originally submitted amount of the order.
  - `is_hidden` boolean: Will always return `false`.
  - `trades` object[]: Contains an array of JSON objects with trade details.
    - `price` string, decimal: The price that the execution happened at
    - `amount` string, decimal: The quantity that was executed
    - `timestamp` union: timestamp
      - string: Gemini strongly recommends using milliseconds instead of seconds for timestamps. | Timestamp format | Example | Supported request type | |-----------------------|-----------------------|------------------------| | string (seconds) | `1495127793` | `POST` only | | string (milliseconds) | `1495127793000` | `POST` only |
      - integer: Gemini strongly recommends using milliseconds instead of seconds for timestamps. | Timestamp format | Example | Supported request type | |-----------------------------|---------------------------|------------------------| | whole number (seconds) | `1495127793` | `GET`, `POST` | | whole number (milliseconds) | `1495127793000` | `GET`, `POST` |
    - `timestampms` union: timestamp
      - string: Gemini strongly recommends using milliseconds instead of seconds for timestamps. | Timestamp format | Example | Supported request type | |-----------------------|-----------------------|------------------------| | string (seconds) | `1495127793` | `POST` only | | string (milliseconds) | `1495127793000` | `POST` only |
      - integer: Gemini strongly recommends using milliseconds instead of seconds for timestamps. | Timestamp format | Example | Supported request type | |-----------------------------|---------------------------|------------------------| | whole number (seconds) | `1495127793` | `GET`, `POST` | | whole number (milliseconds) | `1495127793000` | `GET`, `POST` |
    - `type` 'Buy' | 'Sell': Will be either "Buy" or "Sell", indicating the side of the original order
    - `aggressor` boolean: If `true`, this order was the taker in the trade
    - `fee_currency` string: Currency that the fee was paid in
    - `fee_amount` string, decimal: The amount charged
    - `tid` integer: Unique identifier for the trade
    - `order_id` string: The order that this trade executed against
    - `exchange` string: Will always be "gemini"
    - `break` string: Will only be present if the trade is broken. See `Break Types` below for more information.

## Other responses

- `400`: Bad request - malformed request or invalid parameters
- `401`: Unauthorized - missing or invalid authentication
- `403`: ApiKey fails IP Filtering Check
- `404`: Resource not found
- `429`: Too many requests - you have exceeded the rate limit
- `500`: Internal server error

---

[API](https://skmtc.dev/gemini/apis/rest-api.md) - [All operations](https://skmtc.dev/gemini/apis/rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gemini/apis/rest-api/revisions/24979792d748?raw)