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. Identifier on Mobula: order Supported exchanges: lighter, gains Supported chains: 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

Example - Liquidation (Long):

{
  "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"
}

Example - Market Order:

{
  "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"
}

Example - Take Profit:

{
  "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"
}

Example - TP/SL Update:

{
  "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"
}

Example - Trade Stored (Uncategorized):

{
  "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:

// 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.

Support

Slack

Introduction

Data

Execution

Cookbook

Streams

Reference

Order model

Event Categories

Field Reference - Executed Orders

Field Reference - TP/SL Updates

Field Reference - Uncategorized Events

Extra Data (Lighter/Gains)

Calculating Position Value

Explorer Links

Support

Support

Need help?

​Order model

​Event Categories

​Field Reference - Executed Orders

​Field Reference - TP/SL Updates

​Field Reference - Uncategorized Events

​Extra Data (Lighter/Gains)

​Calculating Position Value

​Explorer Links

Support

Support

Need help?

Order model

Event Categories

Field Reference - Executed Orders

Field Reference - TP/SL Updates

Field Reference - Uncategorized Events

Extra Data (Lighter/Gains)

Calculating Position Value

Explorer Links