> ## 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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.