# Take Profit / Stop Loss

### Take Profit & Stop Loss

TP/SL orders automatically close positions when specified conditions are met. They are handled internally and off-chain, with price updates occurring every second.

TP/SL can be included when creating a new position or updated on an existing position via the `PUT /positions/:positionId/risk-parameters` endpoint.

#### Trigger Types

| Type             | Description                                                      | `value`                  |
| ---------------- | ---------------------------------------------------------------- | ------------------------ |
| `PERCENTAGE`     | Triggers based on P\&L % relative to entry                       | TP: profit %; SL: loss % |
| `DOLLAR`         | Triggers based on absolute P\&L in USD                           | TP: profit $; SL: loss $ |
| `POSITION_VALUE` | Triggers when position notional value crosses threshold          | USD value                |
| `PRICE`          | Triggers when primary asset price crosses threshold              | Asset price              |
| `PRICE_RATIO`    | Triggers when long/short price ratio crosses threshold           | Price ratio              |
| `WEIGHTED_RATIO` | Triggers when weighted ratio across all assets crosses threshold | Weighted ratio           |

#### Setting TP/SL on Position Creation

Include `stopLoss` and/or `takeProfit` in the create position payload:

```json
{
  "executionType": "MARKET",
  "leverage": 5,
  "usdValue": 1000,
  "slippage": 0.01,
  "longAssets": [{ "asset": "BTC", "weight": 1 }],
  "shortAssets": [{ "asset": "ETH", "weight": 1 }],
  "stopLoss": { "type": "PERCENTAGE", "value": 10 },
  "takeProfit": { "type": "PERCENTAGE", "value": 25 }
}
```

#### Updating TP/SL on Existing Position

`PUT /positions/:positionId/risk-parameters`

```json
{
  "stopLoss": { "type": "DOLLAR", "value": 100 },
  "takeProfit": { "type": "POSITION_VALUE", "value": 1200 }
}
```

Set to `null` to remove:

```json
{
  "stopLoss": null
}
```

#### Examples by Trigger Type

**Percentage** — close when P\&L hits +25% (TP) or -10% (SL):

```json
{
  "takeProfit": { "type": "PERCENTAGE", "value": 25 },
  "stopLoss": { "type": "PERCENTAGE", "value": 10 }
}
```

**Dollar** — close when P\&L hits +$200 (TP) or -$100 (SL):

```json
{
  "takeProfit": { "type": "DOLLAR", "value": 200 },
  "stopLoss": { "type": "DOLLAR", "value": 100 }
}
```

**Position Value** — close when notional value hits $1,200 (TP) or $800 (SL):

```json
{
  "takeProfit": { "type": "POSITION_VALUE", "value": 1200 },
  "stopLoss": { "type": "POSITION_VALUE", "value": 800 }
}
```

**Price** — close when primary asset price hits $120,000 (TP) or $90,000 (SL):

```json
{
  "takeProfit": { "type": "PRICE", "value": 120000 },
  "stopLoss": { "type": "PRICE", "value": 90000 }
}
```

**Price Ratio** — close when long/short price ratio hits 28 (TP) or 22 (SL):

```json
{
  "takeProfit": { "type": "PRICE_RATIO", "value": 28 },
  "stopLoss": { "type": "PRICE_RATIO", "value": 22 }
}
```

**Weighted Ratio** — close when weighted ratio hits 1.15 (TP) or 0.90 (SL):

```json
{
  "takeProfit": { "type": "WEIGHTED_RATIO", "value": 1.15 },
  "stopLoss": { "type": "WEIGHTED_RATIO", "value": 0.90 }
}
```

#### Trailing Stop

Trailing stops automatically advance the stop loss trigger as the position moves in your favor. The stop trails behind the best observed metric value by a configurable delta percentage.

When the metric (P\&L %, price, ratio, etc.) improves past the `trailingActivationValue`, the stop loss trigger is recalculated as:

* **Long positions**: `triggerValue = currentMetric × (1 - trailingDeltaValue / 100)`
* **Short positions (PRICE type)**: `triggerValue = currentMetric × (1 + trailingDeltaValue / 100)`

The activation value updates each time the stop advances, so it only ever moves in your favor.

**Example** — trailing stop that activates at 5% profit, trails by 3%:

```json
{
  "stopLoss": {
    "type": "PERCENTAGE",
    "value": 5,
    "isTrailing": true,
    "trailingDeltaValue": 3,
    "trailingActivationValue": 5
  }
}
```

If P\&L reaches 10%, the stop loss advances to 10% × (1 - 0.03) = 9.7%. If P\&L later reaches 15%, stop advances to 14.55%. The stop never moves backward.

**Trailing stop with price trigger**:

```json
{
  "stopLoss": {
    "type": "PRICE",
    "value": 95000,
    "isTrailing": true,
    "trailingDeltaValue": 2,
    "trailingActivationValue": 100000
  }
}
```

#### Execution Behavior

* **TP**: triggers when metric reaches or exceeds the target value
* **SL**: triggers when metric falls to or below the target value
* **PRICE type** is side-aware: for short positions, TP triggers when price drops below target, SL triggers when price rises above target
* When triggered, the position is closed via a market order
* Notifications are sent on both successful fills and failures


---

# 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/managing-open-position/take-profit-stop-loss.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.