Skip to main content

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.

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
TypeDescription
MARKET_BUYMarket buy order execution
MARKET_SELLMarket sell order execution
LIQUIDATION_LONGLiquidated long position
LIQUIDATION_SHORTLiquidated short position
LIMIT_BUYLimit buy order execution
LIMIT_SELLLimit sell order execution
TAKE_PROFITTake profit trigger execution
STOP_LOSSStop loss trigger execution
2. TP/SL Updates (PerpTpSlUpdate) - Take profit and stop loss modifications
TypeDescription
UPDATE_TPTake profit level update
UPDATE_SLStop loss level update
3. Uncategorized Events (PerpUncategorizedEvent) - Position management events
TypeDescription
TRADE_STOREDNew trade stored (pending execution)
POSITION_SIZE_INCREASE_EXECUTEDPosition size increased
POSITION_SIZE_DECREASE_EXECUTEDPosition size decreased
LEVERAGE_UPDATE_EXECUTEDLeverage updated on position
MARKET_CLOSE_CANCELEDMarket close order canceled
MARKET_OPEN_CANCELEDMarket open order canceled

​
Field Reference - Executed Orders

Fields available on PerpOrderExecuted events (MARKET_BUY, MARKET_SELL, LIQUIDATION_LONG, LIQUIDATION_SHORT, etc.):
FieldTypeDescription
marketstringMarket identifier (e.g., lighter-eth-usd, lighter-btc-usd)
exchangestringExchange identifier (lighter, gains)
chainIdstringChain identifier (e.g., lighter:301, evm:42161)
typestringOrder type (see table above)
priceQuotenumberExecution price in quote currency
priceUSDnumberExecution price in USD
baseAmountRawstringBase asset amount in wei (18 decimals)
collateralAmountRawstringCollateral amount in wei (18 decimals)
traderAddressstringTrader’s wallet address
transactionHashstringTransaction hash
tradeIdstringUnique trade identifier ({exchange}-{address}-{market}-{id})
leveragenumber | nullPosition leverage multiplier
takeProfitUSDnumber | nullTake profit price in USD
stopLossUSDnumber | nullStop loss price in USD
collateralAssetstring | nullCollateral token contract address
datestringISO 8601 timestamp
extraobjectExchange-specific additional data

​
Field Reference - TP/SL Updates

Fields available on PerpTpSlUpdate events (UPDATE_TP, UPDATE_SL):
FieldTypeDescription
marketstringMarket identifier
exchangestringExchange identifier
chainIdstringChain identifier
typestringUPDATE_TP or UPDATE_SL
traderAddressstringTrader’s wallet address
transactionHashstringTransaction hash
tradeIdstringUnique trade identifier
newPriceQuotenumberNew TP/SL price in quote currency
quantityPercentagenumberPercentage of position affected
datestringISO 8601 timestamp

​
Field Reference - Uncategorized Events

Fields available on PerpUncategorizedEvent events:
FieldTypeDescription
marketstringMarket identifier
exchangestringExchange identifier
chainIdstringChain identifier
typestringEvent type (see table above)
traderAddressstringTrader’s wallet address
transactionHashstringTransaction hash
tradeIdstringUnique trade identifier
datestringISO 8601 timestamp
extraobjectEvent-specific data (see below)
Extra data by event type:
Event TypeExtra Fields
TRADE_STOREDtradeType, leverage, long, collateralAmount, index, openPrice, tp, sl
POSITION_SIZE_INCREASE_EXECUTEDcancelReason
POSITION_SIZE_DECREASE_EXECUTEDcancelReason
LEVERAGE_UPDATE_EXECUTED(none)
MARKET_OPEN_CANCELEDcancelReason, orderId
MARKET_CLOSE_CANCELEDcancelReason, index

​
Extra Data (Lighter/Gains)

For liquidations and limit orders, additional data is available in the extra field:
FieldTypeDescription
extra.trade.longbooleanPosition direction (true = long, false = short)
extra.trade.indexnumberTrade index on the exchange
extra.trade.openPricebigintPosition open price
extra.trade.tradeTypenumberInternal trade type identifier
extra.trade.collateralIndexnumberCollateral asset index
extra.openbooleanWhether this opens a new position
extra.amountSentToTraderbigintAmount returned to trader (for closes)
extra.percentProfitbigintProfit percentage (for closes)
extra.oraclePricebigintOracle price at execution
extra.collateralPriceUsdbigintCollateral 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);
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

Telegram

Support

Slack

Need help?

Email