> ## Documentation Index
> Fetch the complete documentation index at: https://dev.jup.ag/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Order History

> Query order history, filter by state, and understand the order lifecycle.

## Get Order History

Retrieve your orders with optional filters for state, mint, and pagination.

```typescript  theme={null}
const historyResponse = await fetch(
  'https://api.jup.ag/trigger/v2/orders/history?state=active&limit=20&offset=0',
  {
    headers: {
      'x-api-key': 'your-api-key',
      'Authorization': `Bearer ${token}`,
    },
  }
);

const history = await historyResponse.json();
```

### Query Parameters

| Parameter | Type     | Default      | Description                                                 |
| :-------- | :------- | :----------- | :---------------------------------------------------------- |
| `state`   | `string` | —            | `active` (open orders) or `past` (filled/cancelled/expired) |
| `mint`    | `string` | —            | Filter by token mint address (input or output)              |
| `limit`   | `number` | `20`         | Results per page (1-100)                                    |
| `offset`  | `number` | `0`          | Number of results to skip                                   |
| `sort`    | `string` | `updated_at` | Sort field: `updated_at`, `created_at`, `expires_at`        |
| `dir`     | `string` | `desc`       | Sort direction: `asc` or `desc`                             |

### Response

```json  theme={null}
{
  "orders": [
    {
      "id": "order-uuid",
      "orderType": "single",
      "orderState": "open",
      "rawState": "open",
      "userPubkey": "YourWalletPublicKey...",
      "privyWalletPubkey": "VaultPublicKey...",
      "inputMint": "So11111111111111111111111111111111111111112",
      "initialInputAmount": "1000000000",
      "remainingInputAmount": "1000000000",
      "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "triggerMint": "So11111111111111111111111111111111111111112",
      "triggerCondition": "above",
      "triggerPriceUsd": 200.00,
      "slippageBps": 100,
      "expiresAt": 1704067200000,
      "createdAt": 1704000000000,
      "updatedAt": 1704000000000,
      "events": [
        {
          "type": "deposit",
          "timestamp": 1704000000000,
          "txSignature": "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d...",
          "mint": "So11111111111111111111111111111111111111112",
          "amount": "1000000000",
          "state": "success"
        }
      ]
    }
  ],
  "pagination": {
    "total": 50,
    "limit": 20,
    "offset": 0
  }
}
```

### Additional Fields for Filled Orders

Orders that have been fully or partially filled include extra fields:

| Field          | Description                                |
| :------------- | :----------------------------------------- |
| `triggeredAt`  | Timestamp when the price condition was met |
| `outputAmount` | Total output tokens received               |
| `inputUsed`    | Total input tokens consumed                |
| `fillPercent`  | Fill ratio (1.0 = fully filled)            |

### Execution Attempts

Order history includes execution attempts for each order. When an order fails to execute (due to slippage, quote generation failure, or other reasons), the attempt is recorded in the history. The reason for failure is not included in the response.

Users can adjust slippage settings via the [update endpoint](/trigger/manage-orders) if execution keeps failing due to slippage.

### Event Types

Each order includes an `events` array tracking its lifecycle:

| Event Type   | Description                      |
| :----------- | :------------------------------- |
| `deposit`    | Tokens deposited into vault      |
| `fill`       | Order executed (full or partial) |
| `withdrawal` | Tokens withdrawn back to wallet  |
| `cancelled`  | Order cancelled by user          |
| `expired`    | Order expired                    |

Each event includes `type`, `timestamp`, and `state`. Events that involve token movement (`deposit`, `fill`, `withdrawal`) also include:

| Field         | Description                     |
| :------------ | :------------------------------ |
| `txSignature` | On-chain transaction signature  |
| `mint`        | Token mint address              |
| `amount`      | Token amount (in smallest unit) |

Fill events include additional fields:

| Field          | Description                                                                  |
| :------------- | :--------------------------------------------------------------------------- |
| `outputMint`   | Output token mint address                                                    |
| `outputAmount` | Output amount received                                                       |
| `orderContext` | Semantic order type: `take_profit`, `stop_loss`, `buy_above`, or `buy_below` |

## Order States

Orders follow a state machine from creation to completion. The `orderState` field provides a human-friendly state, while `rawState` shows the exact internal state.

### Display States

| State              | Description                                        |
| :----------------- | :------------------------------------------------- |
| `pending`          | Deposit is being processed                         |
| `open`             | Active and waiting for price trigger               |
| `executing`        | Price condition met, swap in progress              |
| `filled`           | Order completed successfully                       |
| `pending_withdraw` | Cancellation initiated, awaiting signed withdrawal |
| `cancelled`        | User cancelled the order                           |
| `expired`          | Order expired before execution                     |
| `failed`           | Execution failed                                   |

### Raw States

The `rawState` field exposes the internal processing state. Multiple raw states map to each display state:

| `orderState`       | `rawState`              | Meaning                                                              |
| :----------------- | :---------------------- | :------------------------------------------------------------------- |
| `pending`          | `pending_deposit`       | Deposit transaction not yet submitted                                |
| `pending`          | `depositing`            | Deposit transaction submitted, awaiting confirmation                 |
| `open`             | `open`                  | Active and monitoring price                                          |
| `executing`        | `ready_execute`         | Price condition met, preparing swap                                  |
| `executing`        | `ready_expire`          | Order expiry detected, processing                                    |
| `executing`        | `executing`             | Swap transaction in flight                                           |
| `executing`        | `execute_success`       | Swap landed, validating output                                       |
| `executing`        | `execute_failed`        | Swap attempt failed, may retry                                       |
| `executing`        | `ready_withdraw_output` | Output ready to withdraw to wallet                                   |
| `executing`        | `withdrawing`           | Withdrawal transaction in flight                                     |
| `filled`           | `fill_success`          | Order fully filled and output withdrawn                              |
| `executing`        | `partial_fill_success`  | Order partially filled, may continue filling                         |
| `pending_withdraw` | `ready_to_cancel`       | Cancellation initiated, awaiting signed withdrawal                   |
| `cancelled`        | `cancelled`             | User cancelled the order                                             |
| `cancelled`        | `oco_cancelled`         | Automatically cancelled because the other side of an OCO pair filled |
| `expired`          | `expired`               | Order expired before execution                                       |
| `failed`           | `deposit_failed`        | Deposit transaction failed on-chain (e.g. insufficient balance)      |
| `failed`           | `withdraw_failed`       | Output withdrawal failed after execution                             |
| `failed`           | `fill_failed`           | Fill validation failed after execution                               |

### State Flow

```
pending ──→ open ──→ executing ──→ filled
   │          │          │
   │          │          └──→ failed
   └──→ failed│
   (deposit)  ├──→ expired
              │
              └──→ pending_withdraw ──→ cancelled
```

For OCO orders, when one side fills, the other transitions to `cancelled` automatically (displayed as `oco_cancelled` in the raw state).

For OTOCO orders, the child OCO pair only activates after the parent order reaches `filled`. If the parent expires or fails, the children are never created.


Built with [Mintlify](https://mintlify.com).