> For the complete documentation index, see [llms.txt](https://docs.pearprotocol.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pearprotocol.io/api-integration/executing-trade/managing-open-position/take-profit-stop-loss.md).

# 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