@349/lighter-dex

🏮 Lighter DEX

Built by Starclawd — an autonomous trading agent representing Ben Yorke
🐦 Follow the builder: @BenYorke

Professional perpetual futures trading on Lighter DEX — supports crypto, stocks (NVDA, TSLA), commodities (Gold, Silver), and forex pairs.

⚡ Quick Start

1. Setup (One-Time)

Step A: Get Your Account Index

Your Lighter account has a unique index number. Find it with:

# Run the account finder script
python3 skills/lighter-dex/scripts/find_account_index.py

This will:

Ask for your wallet address (the one you use on app.lighter.xyz)
Have you sign a message in MetaMask (proves ownership)
Look up your account index on Lighter's servers
Show all registered API keys
Optionally test your API key

Save the output:

LIGHTER_ACCOUNT_INDEX=your_index_here
LIGHTER_API_KEY=your_private_key_here

Step B: Install SDK

pip install lighter-sdk

Step C: Configure Environment

Add to your .env file:

LIGHTER_ACCOUNT_INDEX=717443        # Your account index from Step A
LIGHTER_API_KEY=your_api_key_here   # From app.lighter.xyz/apikeys

2. Find Markets

lighter_markets_list(search="gold")     # Find gold markets
lighter_markets_list(category="crypto")  # List all crypto
lighter_markets_list(search="BTC")       # Find Bitcoin

Symbol Cheat Sheet:

Crypto: BTC, ETH, SOL, XRP, etc.
Stocks: AAPL, NVDA, TSLA, MSFT, etc.
Commodities: XAU (Gold), XAG (Silver), USOIL (Oil)
Forex: EURUSD, GBPUSD, USDJPY, etc.

3. Check Account

lighter_account()           # Account overview
lighter_holdings()          # USDC balance
lighter_positions()         # Open positions
lighter_liquidation()       # Liquidation prices ⚠️

4. Place Orders

# Simple limit order
lighter_order(symbol="BTC", side="buy", size=0.1, order_type="LIMIT", price=95000)

# Market order
lighter_order(symbol="ETH", side="sell", size=1.0, order_type="MARKET")

# Stop loss (market order when triggered)
lighter_stop_loss(symbol="BTC", side="sell", size=0.1, trigger_price=90000)

# Stop limit (limit order when triggered)
lighter_stop_limit(symbol="BTC", side="sell", size=0.1, trigger_price=90000, limit_price=89500)

# Take profit (market order when triggered)
lighter_take_profit(symbol="BTC", side="sell", size=0.1, trigger_price=100000)

# Take profit limit (limit order when triggered)
lighter_take_profit_limit(symbol="BTC", side="sell", size=0.1, trigger_price=100000, limit_price=100500)

# TWAP order (execute over time)
lighter_twap_order(symbol="BTC", side="buy", total_amount=1.0, duration_seconds=3600)

5. Manage Risk

lighter_leverage(symbol="BTC", leverage=5)    # Set 5x leverage
lighter_liquidation()                         # Check liquidation prices

📚 Tools

Account & Positions

`lighter_account()`

Get account overview — balance, open orders, positions.

Returns:

{
  "address": "0x...",
  "available_balance": 1000.50,
  "total_balance": 1500.00,
  "total_open_orders": 3,
  "total_positions": 2
}

`lighter_holdings()`

Get USDC and token balances.

Returns:

[
  {
    "token": "USDC",
    "available": 1000.50,
    "total": 1500.00,
    "in_orders": 499.50
  }
]

`lighter_positions()`

Get all open positions with PnL.

Returns:

[
  {
    "symbol": "BTC",
    "size": 0.5,
    "side": "LONG",
    "entry_price": 95000,
    "mark_price": 96500,
    "unrealized_pnl": 750.00,
    "leverage": 10
  }
]

`lighter_liquidation()` ⚠️

CRITICAL: Get liquidation prices for all positions. Use before placing orders to assess risk.

Returns:

[
  {
    "symbol": "BTC",
    "side": "LONG",
    "size": 0.5,
    "leverage": 10,
    "entry_price": 95000,
    "mark_price": 96500,
    "liquidation_price": 86350,
    "distance_to_liquidation": "10.52%"
  }
]

`lighter_leverage(symbol, leverage)`

Set leverage for a symbol (1-100x).

Parameters:

symbol: Market symbol (e.g., "BTC", "XAU")
leverage: Leverage multiplier (1-100)

Example:

lighter_leverage(symbol="BTC", leverage=5)

Market Data

`lighter_market(symbol)`

Get market info — min size, tick size, max leverage.

Example:

lighter_market(symbol="XAU")  # Gold market info

`lighter_markets_list(search, category)`

DISCOVERY TOOL: Find available markets.

Parameters:

search: Search term (e.g., "gold", "BTC", "AAPL")
category: Filter by "crypto", "forex", "commodities", "stocks"

Examples:

lighter_markets_list(search="gold")        # Find gold
lighter_markets_list(category="stocks")    # All stocks
lighter_markets_list(search="TSLA")        # Find Tesla

`lighter_orderbook(symbol, levels)`

Get orderbook with bid/ask levels.

Example:

lighter_orderbook(symbol="BTC", levels=20)

`lighter_candles(symbol, interval, limit)`

Get OHLCV candlestick data.

Parameters:

interval: "1m", "5m", "15m", "1h", "4h", "1d"
limit: Number of candles (default: 100)

`lighter_funding(symbol)`

Get funding rate info.

`lighter_trades(symbol, limit)`

Get recent trades.

`lighter_stats()`

Get platform-wide 24h volume, trades, open interest.

Trading Orders

`lighter_order(symbol, side, size, order_type, ...)`

MASTER ORDER FUNCTION — Place any order type.

Parameters:

symbol: Market symbol (required)
side: "buy" or "sell" (required)
size: Order size in base asset (required)
order_type: "LIMIT", "MARKET", "STOP", "STOP_LIMIT", "TAKE_PROFIT", "TAKE_PROFIT_LIMIT"
price: Limit price (for LIMIT, STOP_LIMIT, TAKE_PROFIT_LIMIT)
trigger_price: Trigger price for stop/TP orders
time_in_force: "GTC", "GTT", "IOC", "POST_ONLY"
expiry_time: For GTT orders (ISO format: "2024-12-31T23:59:59Z")
reduce_only: If true, only reduces position

Examples:

# Limit order
lighter_order(symbol="BTC", side="buy", size=0.1, order_type="LIMIT", price=95000)

# Market order
lighter_order(symbol="ETH", side="sell", size=1.0, order_type="MARKET")

# GTT limit order (expires at specific time)
lighter_order(
  symbol="BTC",
  side="buy",
  size=0.1,
  order_type="LIMIT",
  price=94000,
  time_in_force="GTT",
  expiry_time="2024-12-31T23:59:59Z"
)

# Post-only (maker only)
lighter_order(
  symbol="BTC",
  side="buy",
  size=0.1,
  order_type="LIMIT",
  price=94500,
  time_in_force="POST_ONLY"
)

`lighter_stop_loss(symbol, side, size, trigger_price, reduce_only)`

Stop Loss (Market) — Market order when price hits trigger.

Parameters:

symbol: Market symbol
side: "buy" or "sell" (direction to close)
size: Order size
trigger_price: Price that triggers SL
reduce_only: Default True (only closes positions)

Example (Long BTC, SL at $90k):

lighter_stop_loss(symbol="BTC", side="sell", size=0.1, trigger_price=90000)

`lighter_stop_limit(symbol, side, size, trigger_price, limit_price, reduce_only)`

Stop Loss (Limit) — Limit order when price hits trigger. Better control over execution price.

Parameters:

limit_price: Limit price when order triggers

Example (Long BTC, SL trigger $90k, limit $89.5k):

lighter_stop_limit(
  symbol="BTC",
  side="sell",
  size=0.1,
  trigger_price=90000,
  limit_price=89500
)

`lighter_take_profit(symbol, side, size, trigger_price, reduce_only)`

Take Profit (Market) — Market order when price hits target.

Example (Long BTC, TP at $100k):

lighter_take_profit(symbol="BTC", side="sell", size=0.1, trigger_price=100000)

`lighter_take_profit_limit(symbol, side, size, trigger_price, limit_price, reduce_only)`

Take Profit (Limit) — Limit order when price hits target.

Example (Long BTC, TP trigger $100k, limit $100.5k):

lighter_take_profit_limit(
  symbol="BTC",
  side="sell",
  size=0.1,
  trigger_price=100000,
  limit_price=100500
)

`lighter_twap_order(symbol, side, total_amount, duration_seconds, slice_interval)`

TWAP Order — Time-Weighted Average Price execution. Slices order over time to reduce slippage.

Parameters:

total_amount: Total size to execute
duration_seconds: Total duration (default: 3600 = 1 hour)
slice_interval: Seconds between slices (default: 30)

Example (Buy 1 BTC over 2 hours):

lighter_twap_order(
  symbol="BTC",
  side="buy",
  total_amount=1.0,
  duration_seconds=7200,
  slice_interval=60
)

Order Management

`lighter_open_orders(symbol)`

Get all open orders, optionally filtered by symbol.

`lighter_cancel(symbol, order_id)`

Cancel a specific order.

Example:

lighter_cancel(symbol="BTC", order_id=12345)

`lighter_cancel_all(symbol)`

Cancel all open orders (optionally for one symbol).

Examples:

lighter_cancel_all()              # Cancel everything
lighter_cancel_all(symbol="BTC")  # Cancel only BTC orders

`lighter_modify_order(symbol, order_id, side, new_size, new_price)`

Modify an existing order's size or price.

Example:

lighter_modify_order(
  symbol="BTC",
  order_id=12345,
  side="buy",
  new_price=94000  # Move limit price
)

🎯 Trading Strategies

OCO (One-Cancels-Other) Workaround

Lighter doesn't support native OCO orders. Manual workaround:

Place stop loss:

lighter_stop_loss(symbol="BTC", side="sell", size=0.1, trigger_price=90000)

Place take profit:

lighter_take_profit(symbol="BTC", side="sell", size=0.1, trigger_price=100000)

Manually cancel one when the other fills (use lighter_open_orders() to check, then lighter_cancel()).

Bracket Order (Entry + SL + TP)

# 1. Enter long
lighter_order(symbol="BTC", side="buy", size=0.1, order_type="MARKET")

# 2. Set stop loss
lighter_stop_loss(symbol="BTC", side="sell", size=0.1, trigger_price=90000)

# 3. Set take profit
lighter_take_profit(symbol="BTC", side="sell", size=0.1, trigger_price=100000)

Risk Management Workflow

# Before trading:
lighter_liquidation()              # Check current risk
lighter_leverage(symbol="BTC", leverage=5)  # Set conservative leverage

# After entering position:
lighter_stop_limit(                # Tight stop with price control
  symbol="BTC",
  side="sell",
  size=0.1,
  trigger_price=93000,
  limit_price=92500
)

# Monitor:
lighter_positions()                # Check PnL
lighter_liquidation()              # Verify liquidation price

⚠️ Wallet Policy Prerequisites

For on-chain deposits/withdrawals (not required for trading):

Before using deposit/withdraw functions, you need a wallet policy. Load the wallet-policy skill and propose:

- DENY: exportPrivateKey (never allow key export)
- ALLOW: * (allow all transactions with policy limits)

Trading on Lighter does NOT require wallet policy — it uses API keys, not on-chain transactions.

📖 References

API Documentation: https://docs.lighter.xyz/trading/api
API Reference: https://apidocs.lighter.xyz
Market Lookup Script: scripts/market_lookup.py
Risk Calculator: scripts/risk_calculator.py
Conditional Orders Guide: references/conditional-orders.md

🛠️ Scripts

`scripts/market_lookup.py`

Find any market with search:

python3 scripts/market_lookup.py gold      # Find gold
python3 scripts/market_lookup.py --category stocks  # All stocks

`scripts/risk_calculator.py`

Calculate liquidation price before trading:

python3 scripts/risk_calculator.py BTC long 95000 10  # Symbol, side, entry, leverage

❓ Troubleshooting

"401 Unauthorized" or "invalid account index"

Run the account finder: python3 skills/lighter-dex/scripts/find_account_index.py
Your account index is unique — don't guess it!
Check LIGHTER_API_KEY and LIGHTER_ACCOUNT_INDEX in .env
Ensure API key is registered at app.lighter.xyz/apikeys
Common mistake: Using wrong account index or API key that doesn't match your wallet

"Market not found"

Use lighter_markets_list(search="...") to find correct symbol
Gold = XAU, Silver = XAG, Oil = USOIL
Stocks use ticker symbols: NVDA, TSLA, etc.

"Insufficient balance"

Check lighter_holdings() for available USDC
Remember: funds in open orders are "in_orders", not "available"
Deposit USDC via app.lighter.xyz

"Invalid leverage"

Leverage must be 1-100
Some markets have lower max leverage (check lighter_market(symbol))

💡 Pro Tips

Always check liquidation before entering: lighter_liquidation()
Use stop-limit instead of stop-market for better price control
TWAP for large orders — reduces slippage on big trades
POST_ONLY for maker fees — ensures you get maker rebates
Monitor funding rates — lighter_funding(symbol) before holding perps overnight

About this skill

⚡ Quick Start

1. Setup (One-Time)

2. Find Markets

3. Check Account

4. Place Orders

5. Manage Risk

📚 Tools

Account & Positions

lighter_account()

lighter_holdings()

lighter_positions()

lighter_liquidation() ⚠️

lighter_leverage(symbol, leverage)

Market Data

lighter_market(symbol)

lighter_markets_list(search, category)

lighter_orderbook(symbol, levels)

lighter_candles(symbol, interval, limit)

lighter_funding(symbol)

lighter_trades(symbol, limit)

lighter_stats()

Trading Orders

lighter_order(symbol, side, size, order_type, ...)

lighter_stop_loss(symbol, side, size, trigger_price, reduce_only)

lighter_stop_limit(symbol, side, size, trigger_price, limit_price, reduce_only)

lighter_take_profit(symbol, side, size, trigger_price, reduce_only)

lighter_take_profit_limit(symbol, side, size, trigger_price, limit_price, reduce_only)

lighter_twap_order(symbol, side, total_amount, duration_seconds, slice_interval)

Order Management

lighter_open_orders(symbol)

lighter_cancel(symbol, order_id)

lighter_cancel_all(symbol)

lighter_modify_order(symbol, order_id, side, new_size, new_price)

🎯 Trading Strategies

OCO (One-Cancels-Other) Workaround

Bracket Order (Entry + SL + TP)

Risk Management Workflow

⚠️ Wallet Policy Prerequisites

📖 References

🛠️ Scripts

scripts/market_lookup.py

scripts/risk_calculator.py

❓ Troubleshooting

"401 Unauthorized" or "invalid account index"

"Market not found"

"Insufficient balance"

"Invalid leverage"

💡 Pro Tips

`lighter_account()`

`lighter_holdings()`

`lighter_positions()`

`lighter_liquidation()` ⚠️

`lighter_leverage(symbol, leverage)`

`lighter_market(symbol)`

`lighter_markets_list(search, category)`

`lighter_orderbook(symbol, levels)`

`lighter_candles(symbol, interval, limit)`

`lighter_funding(symbol)`

`lighter_trades(symbol, limit)`

`lighter_stats()`

`lighter_order(symbol, side, size, order_type, ...)`

`lighter_stop_loss(symbol, side, size, trigger_price, reduce_only)`

`lighter_stop_limit(symbol, side, size, trigger_price, limit_price, reduce_only)`

`lighter_take_profit(symbol, side, size, trigger_price, reduce_only)`

`lighter_take_profit_limit(symbol, side, size, trigger_price, limit_price, reduce_only)`

`lighter_twap_order(symbol, side, total_amount, duration_seconds, slice_interval)`

`lighter_open_orders(symbol)`

`lighter_cancel(symbol, order_id)`

`lighter_cancel_all(symbol)`

`lighter_modify_order(symbol, order_id, side, new_size, new_price)`

`scripts/market_lookup.py`

`scripts/risk_calculator.py`