# Trigger Order

### Trigger Orders

Trigger orders execute pair trading positions when a specified condition is met. Conditions range from pair price ratios to BTC dominance thresholds to prediction market outcomes. Trigger orders are handled internally and off-chain, with oracle price updates occurring every second.

#### Trigger Types

All trigger types use `direction`: `MORE_THAN` or `LESS_THAN`.

| Type                        | Description                                                   | `triggerValue`              |
| --------------------------- | ------------------------------------------------------------- | --------------------------- |
| `PRICE`                     | Fires when the pair's price crosses a threshold               | Target price                |
| `PRICE_LIMIT`               | Limit order placed directly on Hyperliquid at a target price  | Target price                |
| `PRICE_RATIO`               | Fires when the pair's price ratio reaches a target            | Target ratio                |
| `WEIGHTED_RATIO`            | Fires when the weighted ratio across assets reaches a target  | Target ratio                |
| `BTC_DOM`                   | Fires when BTC dominance crosses a threshold                  | Dominance % (e.g. `"62.5"`) |
| `CROSS_ASSET_PRICE`         | Fires when an external asset's price crosses a threshold      | Target price                |
| `PREDICTION_MARKET_OUTCOME` | Fires when a prediction market resolves to a specific outcome | Outcome value               |

#### Oracle Sources

Each trigger type pulls price data from a different source, checked at different intervals:

| Trigger Type                                                  | Oracle Source                     | Check Interval |
| ------------------------------------------------------------- | --------------------------------- | -------------- |
| `PRICE`, `PRICE_RATIO`, `WEIGHTED_RATIO`, `CROSS_ASSET_PRICE` | Hyperliquid mark price (`markPx`) | Every \~500ms  |
| `PREDICTION_MARKET_OUTCOME` (Hyperliquid HIP-4)               | Hyperliquid mid price             | Every 1s       |
| `PREDICTION_MARKET_OUTCOME` (Kalshi)                          | Kalshi last price                 | Every 1s       |
| `BTC_DOM`                                                     | CoinGecko BTC dominance %         | Every 60s      |

#### Placing a Trigger Order

Use `executionType: "TRIGGER"` with the appropriate `triggerType`, `triggerValue`, and `direction`.

**Price ratio trigger** — open when BTC/ETH ratio exceeds 25:

```json
{
  "executionType": "TRIGGER",
  "triggerType": "PRICE_RATIO",
  "triggerValue": "25",
  "direction": "MORE_THAN",
  "leverage": 5,
  "usdValue": 1000,
  "slippage": 0.01,
  "longAssets": [{ "asset": "BTC", "weight": 0.5 }],
  "shortAssets": [{ "asset": "ETH", "weight": 0.5 }]
}
```

**BTC dominance trigger** — open when BTC dominance drops below 60%:

```json
{
  "executionType": "TRIGGER",
  "triggerType": "BTC_DOM",
  "triggerValue": "60",
  "direction": "LESS_THAN",
  "leverage": 3,
  "usdValue": 500,
  "slippage": 0.01,
  "longAssets": [{ "asset": "ETH", "weight": 0.25 }, { "asset": "SOL", "weight": 0.25 }],
  "shortAssets": [{ "asset": "BTC", "weight": 0.5 }]
}
```

**Cross-asset price trigger** — open when ETH crosses above $4,000:

```json
{
  "executionType": "TRIGGER",
  "triggerType": "CROSS_ASSET_PRICE",
  "triggerValue": "4000",
  "direction": "MORE_THAN",
  "assetName": "ETH",
  "leverage": 5,
  "usdValue": 1000,
  "slippage": 0.01,
  "longAssets": [{ "asset": "ETH", "weight": 0.5 }],
  "shortAssets": [{ "asset": "BTC", "weight": 0.5 }]
}
```

**Prediction market trigger** — open when a Hyperliquid prediction market outcome resolves:

```json
{
  "executionType": "TRIGGER",
  "triggerType": "PREDICTION_MARKET_OUTCOME",
  "triggerValue": "0.9",
  "direction": "MORE_THAN",
  "marketCode": "#10",
  "marketSource": "HYPERLIQUID",
  "leverage": 3,
  "usdValue": 500,
  "slippage": 0.01,
  "longAssets": [{ "asset": "BTC", "weight": 0.5 }],
  "shortAssets": [{ "asset": "ETH", "weight": 0.5 }]
}
```

#### Browsing Available Triggers

Use the `GET /triggers` endpoint to discover available trigger conditions. Filter by category with the `category` query parameter:

| Category            | What it returns                                        |
| ------------------- | ------------------------------------------------------ |
| `all`               | All available triggers (default)                       |
| `prediction_market` | Hyperliquid prediction markets with live oracle prices |
| `btcdom`            | Current BTC dominance data from CoinGecko              |

Kalshi prediction markets are available via a separate `GET /triggers/kalshi` endpoint with `category`, `search`, and pagination support.

Each trigger response includes an `oracle` field with the current value and unit (`cent` for prediction markets, `percent` for BTC dominance), so you can assess proximity to your target before placing an order.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pearprotocol.io/api-integration/executing-trade/order-type/trigger-order.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.