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

# Perpetuals (Perps)

Perpetual trading events from decentralized perpetual exchanges like Lighter and Gains Network.

### Order model

Orders represent perpetual trading activity including market orders, liquidations, limit orders, take profits, and stop losses.

<b>Identifier on Mobula:</b> `order`

<b>Supported exchanges:</b> `lighter`, `gains`

<b>Supported chains:</b> `lighter:301`, `lighter:304`, `evm:42161` (Arbitrum)

#### Event Categories

Perps events are divided into three categories based on their structure:

**1. Executed Orders (`PerpOrderExecuted`)** - Full trade executions with pricing data

| Type                | Description                   |
| ------------------- | ----------------------------- |
| `MARKET_BUY`        | Market buy order execution    |
| `MARKET_SELL`       | Market sell order execution   |
| `LIQUIDATION_LONG`  | Liquidated long position      |
| `LIQUIDATION_SHORT` | Liquidated short position     |
| `LIMIT_BUY`         | Limit buy order execution     |
| `LIMIT_SELL`        | Limit sell order execution    |
| `TAKE_PROFIT`       | Take profit trigger execution |
| `STOP_LOSS`         | Stop loss trigger execution   |

**2. TP/SL Updates (`PerpTpSlUpdate`)** - Take profit and stop loss modifications

| Type        | Description              |
| ----------- | ------------------------ |
| `UPDATE_TP` | Take profit level update |
| `UPDATE_SL` | Stop loss level update   |

**3. Uncategorized Events (`PerpUncategorizedEvent`)** - Position management events

| Type                              | Description                          |
| --------------------------------- | ------------------------------------ |
| `TRADE_STORED`                    | New trade stored (pending execution) |
| `POSITION_SIZE_INCREASE_EXECUTED` | Position size increased              |
| `POSITION_SIZE_DECREASE_EXECUTED` | Position size decreased              |
| `LEVERAGE_UPDATE_EXECUTED`        | Leverage updated on position         |
| `MARKET_CLOSE_CANCELED`           | Market close order canceled          |
| `MARKET_OPEN_CANCELED`            | Market open order canceled           |

#### Field Reference - Executed Orders

Fields available on `PerpOrderExecuted` events (MARKET\_BUY, MARKET\_SELL, LIQUIDATION\_LONG, LIQUIDATION\_SHORT, etc.):

| Field                 | Type             | Description                                                    |
| --------------------- | ---------------- | -------------------------------------------------------------- |
| `market`              | `string`         | Market identifier (e.g., `lighter-eth-usd`, `lighter-btc-usd`) |
| `exchange`            | `string`         | Exchange identifier (`lighter`, `gains`)                       |
| `chainId`             | `string`         | Chain identifier (e.g., `lighter:301`, `evm:42161`)            |
| `type`                | `string`         | Order type (see table above)                                   |
| `priceQuote`          | `number`         | Execution price in quote currency                              |
| `priceUSD`            | `number`         | Execution price in USD                                         |
| `baseAmountRaw`       | `string`         | Base asset amount in wei (18 decimals)                         |
| `collateralAmountRaw` | `string`         | Collateral amount in wei (18 decimals)                         |
| `traderAddress`       | `string`         | Trader's wallet address                                        |
| `transactionHash`     | `string`         | Transaction hash                                               |
| `tradeId`             | `string`         | Unique trade identifier (`{exchange}-{address}-{market}-{id}`) |
| `leverage`            | `number \| null` | Position leverage multiplier                                   |
| `takeProfitUSD`       | `number \| null` | Take profit price in USD                                       |
| `stopLossUSD`         | `number \| null` | Stop loss price in USD                                         |
| `collateralAsset`     | `string \| null` | Collateral token contract address                              |
| `date`                | `string`         | ISO 8601 timestamp                                             |
| `extra`               | `object`         | Exchange-specific additional data                              |

#### Field Reference - TP/SL Updates

Fields available on `PerpTpSlUpdate` events (UPDATE\_TP, UPDATE\_SL):

| Field                | Type     | Description                       |
| -------------------- | -------- | --------------------------------- |
| `market`             | `string` | Market identifier                 |
| `exchange`           | `string` | Exchange identifier               |
| `chainId`            | `string` | Chain identifier                  |
| `type`               | `string` | `UPDATE_TP` or `UPDATE_SL`        |
| `traderAddress`      | `string` | Trader's wallet address           |
| `transactionHash`    | `string` | Transaction hash                  |
| `tradeId`            | `string` | Unique trade identifier           |
| `newPriceQuote`      | `number` | New TP/SL price in quote currency |
| `quantityPercentage` | `number` | Percentage of position affected   |
| `date`               | `string` | ISO 8601 timestamp                |

#### Field Reference - Uncategorized Events

Fields available on `PerpUncategorizedEvent` events:

| Field             | Type     | Description                     |
| ----------------- | -------- | ------------------------------- |
| `market`          | `string` | Market identifier               |
| `exchange`        | `string` | Exchange identifier             |
| `chainId`         | `string` | Chain identifier                |
| `type`            | `string` | Event type (see table above)    |
| `traderAddress`   | `string` | Trader's wallet address         |
| `transactionHash` | `string` | Transaction hash                |
| `tradeId`         | `string` | Unique trade identifier         |
| `date`            | `string` | ISO 8601 timestamp              |
| `extra`           | `object` | Event-specific data (see below) |

**Extra data by event type:**

| Event Type                        | Extra Fields                                                                          |
| --------------------------------- | ------------------------------------------------------------------------------------- |
| `TRADE_STORED`                    | `tradeType`, `leverage`, `long`, `collateralAmount`, `index`, `openPrice`, `tp`, `sl` |
| `POSITION_SIZE_INCREASE_EXECUTED` | `cancelReason`                                                                        |
| `POSITION_SIZE_DECREASE_EXECUTED` | `cancelReason`                                                                        |
| `LEVERAGE_UPDATE_EXECUTED`        | *(none)*                                                                              |
| `MARKET_OPEN_CANCELED`            | `cancelReason`, `orderId`                                                             |
| `MARKET_CLOSE_CANCELED`           | `cancelReason`, `index`                                                               |

#### Extra Data (Lighter/Gains)

For liquidations and limit orders, additional data is available in the `extra` field:

| Field                         | Type      | Description                                         |
| ----------------------------- | --------- | --------------------------------------------------- |
| `extra.trade.long`            | `boolean` | Position direction (`true` = long, `false` = short) |
| `extra.trade.index`           | `number`  | Trade index on the exchange                         |
| `extra.trade.openPrice`       | `bigint`  | Position open price                                 |
| `extra.trade.tradeType`       | `number`  | Internal trade type identifier                      |
| `extra.trade.collateralIndex` | `number`  | Collateral asset index                              |
| `extra.open`                  | `boolean` | Whether this opens a new position                   |
| `extra.amountSentToTrader`    | `bigint`  | Amount returned to trader (for closes)              |
| `extra.percentProfit`         | `bigint`  | Profit percentage (for closes)                      |
| `extra.oraclePrice`           | `bigint`  | Oracle price at execution                           |
| `extra.collateralPriceUsd`    | `bigint`  | Collateral USD price at execution                   |

<b>Example - Liquidation (Long):</b>

```json theme={null}
{
  "data": {
    "market": "lighter-eth-usd",
    "exchange": "lighter",
    "chainId": "lighter:301",
    "type": "LIQUIDATION_LONG",
    "priceQuote": 3181.58,
    "priceUSD": 3181.58,
    "baseAmountRaw": "500000000000000000",
    "collateralAmountRaw": "150000000000000000000",
    "traderAddress": "0xa186830de4555bb1f8be570e3bf08cd7d7497e53",
    "transactionHash": "344391ee477a1ef9aec7fb9867d2f7ba212811015d64b92f130b92904b0e27315b3adb158c0152e2",
    "tradeId": "lighter-0xa186830de4555bb1f8be570e3bf08cd7d7497e53-lighter-eth-usd-122724811",
    "leverage": 10,
    "takeProfitUSD": null,
    "stopLossUSD": null,
    "collateralAsset": null,
    "date": "2025-12-11T03:40:28.000Z",
    "extra": {
      "open": false,
      "amountSentToTrader": "0",
      "trade": {
        "long": true,
        "index": 122724811,
        "tradeType": 0,
        "openPrice": "3250000000000000000000",
        "collateralIndex": 0
      },
      "percentProfit": "-1000000000000000000",
      "oraclePrice": "3181580000000000000000",
      "collateralPriceUsd": "1000000000000000000"
    }
  },
  "chainId": "lighter:301",
  "subscriptionId": "sub_abc123"
}
```

<b>Example - Market Order:</b>

```json theme={null}
{
  "data": {
    "market": "lighter-btc-usd",
    "exchange": "lighter",
    "chainId": "lighter:304",
    "type": "MARKET_BUY",
    "priceQuote": 89854.80,
    "priceUSD": 89854.80,
    "baseAmountRaw": "100000000000000000",
    "collateralAmountRaw": "8985480000000000000000",
    "traderAddress": "0xb234567890abcdef1234567890abcdef12345678",
    "transactionHash": "5405828ee77e29a54fc33b333cb4c5b5de086ceb409d8ad10fe37eaf5aa56fed9546d3260a755cb9",
    "tradeId": "lighter-0xb234567890abcdef1234567890abcdef12345678-lighter-btc-usd-98765432",
    "leverage": 5,
    "takeProfitUSD": 95000.00,
    "stopLossUSD": 85000.00,
    "collateralAsset": null,
    "date": "2025-12-11T03:35:15.000Z",
    "extra": {
      "open": true,
      "amountSentToTrader": "0",
      "trade": {
        "long": true,
        "index": 98765432,
        "tradeType": 0,
        "openPrice": "89854800000000000000000",
        "collateralIndex": 0
      }
    }
  },
  "chainId": "lighter:304",
  "subscriptionId": "sub_def456"
}
```

<b>Example - Take Profit:</b>

```json theme={null}
{
  "data": {
    "market": "lighter-eth-usd",
    "exchange": "lighter",
    "chainId": "lighter:301",
    "type": "TAKE_PROFIT",
    "priceQuote": 3500.00,
    "priceUSD": 3500.00,
    "baseAmountRaw": "1000000000000000000",
    "collateralAmountRaw": "350000000000000000000",
    "traderAddress": "0xc345678901bcdef2345678901bcdef2345678901",
    "transactionHash": "7890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12345678",
    "tradeId": "lighter-0xc345678901bcdef2345678901bcdef2345678901-lighter-eth-usd-11223344",
    "leverage": 10,
    "takeProfitUSD": 3500.00,
    "stopLossUSD": 3000.00,
    "collateralAsset": null,
    "date": "2025-12-11T04:15:30.000Z",
    "extra": {
      "open": false,
      "amountSentToTrader": "385000000000000000000",
      "trade": {
        "long": true,
        "index": 11223344,
        "tradeType": 1,
        "openPrice": "3200000000000000000000",
        "collateralIndex": 0
      },
      "percentProfit": "93750000000000000",
      "oraclePrice": "3500000000000000000000",
      "collateralPriceUsd": "1000000000000000000"
    }
  },
  "chainId": "lighter:301",
  "subscriptionId": "sub_ghi789"
}
```

<b>Example - TP/SL Update:</b>

```json theme={null}
{
  "data": {
    "market": "lighter-eth-usd",
    "exchange": "lighter",
    "chainId": "lighter:301",
    "type": "UPDATE_TP",
    "traderAddress": "0xd456789012cdef3456789012cdef3456789012cd",
    "transactionHash": "890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12345678",
    "tradeId": "lighter-0xd456789012cdef3456789012cdef3456789012cd-lighter-eth-usd-55667788",
    "newPriceQuote": 3800.00,
    "quantityPercentage": 100,
    "date": "2025-12-11T05:00:00.000Z"
  },
  "chainId": "lighter:301",
  "subscriptionId": "sub_jkl012"
}
```

<b>Example - Trade Stored (Uncategorized):</b>

```json theme={null}
{
  "data": {
    "market": "lighter-btc-usd",
    "exchange": "lighter",
    "chainId": "lighter:304",
    "type": "TRADE_STORED",
    "traderAddress": "0xe567890123def4567890123def4567890123def45",
    "transactionHash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "tradeId": "lighter-0xe567890123def4567890123def4567890123def45-lighter-btc-usd-99887766",
    "date": "2025-12-11T05:30:00.000Z",
    "extra": {
      "tradeType": 0,
      "leverage": 20,
      "long": true,
      "collateralAmount": "5000000000000000000000",
      "index": 99887766,
      "openPrice": "95000000000000000000000",
      "tp": "100000000000000000000000",
      "sl": "90000000000000000000000"
    }
  },
  "chainId": "lighter:304",
  "subscriptionId": "sub_mno345"
}
```

### Calculating Position Value

To calculate the USD value of a position:

```typescript theme={null}
// Collateral is already in USD (stablecoin)
const collateralUsd = Number(order.collateralAmountRaw) / 1e18;

// Position size = collateral × leverage
const positionSizeUsd = collateralUsd * (order.leverage || 1);
```

### Explorer Links

For Lighter transactions, you can view details on their explorer:

```
https://app.lighter.xyz/explorer/logs/{transactionHash}/
```

Can't find what you're looking for? Reach out to us, response times \< 1h.

<CardGroup>
  <Card title="Support" icon="Telegram" href="https://t.me/mobuladevelopers?start=Mobula_API_Support_Key">
    Telegram
  </Card>

  <Card title="Support" icon="Slack" href="https://join.slack.com/t/mobulaapi/shared_invite/zt-29zrrpjnl-I0tyD73sy7zKy8q~KLL3Ug">
    Slack
  </Card>

  <Card title="Need help?" icon="envelope" href="mailto:contact@mobulalabs.org">
    Email
  </Card>
</CardGroup>