# Position Commands

## What is a position?

A position is an open trade. When you place a market or limit order that fills, it becomes a position. You hold that position until you close it, either manually or through a take-profit or stop-loss trigger.

Positions have a few key properties:

* **Side:** Long (you profit when price goes up) or short (you profit when price goes down)
* **Size:** How much of the asset you are holding
* **Leverage:** How much your exposure is multiplied relative to your collateral. With 10x leverage and $100 deposited, you control $1,000 worth of the asset. This amplifies both gains and losses
* **Margin mode:** Whether your collateral is shared across all positions (cross) or locked to this position individually (isolated)
* **Unrealised PnL:** How much you are up or down on the position right now

## Viewing your positions

Run `byreal-perps-cli position list` to see all open positions, including their size, entry price, current mark price, leverage, margin mode, and unrealised PnL.

## Leverage

Leverage multiplies your exposure. A 5x leveraged position on $200 of USDC gives you $1,000 of market exposure. This means a 10% price move in your favour gives you 50% return on your collateral, but a 10% move against you loses 50%.

Higher leverage increases both potential gains and the risk of liquidation, which is when your position is automatically closed because your losses have consumed your collateral.

To set leverage on a position:

```bash
byreal-perps-cli position leverage BTC 10
```

Leverage can be set between 1x and 50x. You can also include `--cross` or `--isolated` to switch margin mode at the same time.

## Margin mode

Margin mode controls how your collateral is allocated.

**Cross margin** uses your entire account balance as collateral across all positions. If one position is losing, your other funds can help keep it open. This lowers the chance of liquidation but means a liquidation event can affect your whole account.

**Isolated margin** locks a set amount of collateral to a specific position. If that position is liquidated, only the allocated collateral is lost and the rest of your account is unaffected.

To switch margin mode:

```bash
byreal-perps-cli position margin-mode BTC cross
byreal-perps-cli position margin-mode ETH isolated
```

{% hint style="info" %}
Note: Some assets on Hyperliquid only support isolated margin. The CLI will block a cross-margin request on those assets and return a clear error message.
{% endhint %}

## Closing positions

There are three ways to close a position:

**Close at market price** fills immediately at the best available price. Use this when you want out quickly:

```bash
byreal-perps-cli position close-market BTC
```

**Close with a limit order** lets you set the price you want to exit at. The order sits in the book until the market reaches your price. Use this when you are not in a rush and want a specific exit:

```bash
byreal-perps-cli position close-limit BTC 105000
```

The CLI will warn you if the price you set would fill immediately with more than 5% slippage from the current mark price.

**Close all positions** closes everything at once. This always requires confirmation:

```bash
byreal-perps-cli position close-all -y
```

## Position commands summary

| Command                                           | Description                         |
| ------------------------------------------------- | ----------------------------------- |
| `position list`                                   | View all open positions             |
| `position leverage <coin> <1-50>`                 | Set leverage between 1x and 50x     |
| `position margin-mode <coin> <cross or isolated>` | Switch margin mode                  |
| `position tpsl <coin>`                            | View existing TP/SL orders          |
| `position tpsl <coin> --tp <price> --sl <price>`  | Set or replace TP/SL on a position  |
| `position tpsl <coin> --cancel-tp`                | Cancel the take-profit order        |
| `position tpsl <coin> --cancel-sl`                | Cancel the stop-loss order          |
| `position close-market <coin>`                    | Close a position at market price    |
| `position close-limit <coin> <price>`             | Close a position with a limit order |
| `position close-all -y`                           | Close all open positions            |


---

# 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.byreal.io/byreal-perps-agent-skills/position-commands.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.