### Lighter Agent Kit Credentials File Example

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/references/env-vars.md

An example of how to format your personal `lighter-agent-kit` credentials file. This file can be used as an alternative to setting environment variables.

```text
LIGHTER_API_PRIVATE_KEY=...
LIGHTER_ACCOUNT_INDEX=...
LIGHTER_API_KEY_INDEX=...
LIGHTER_HOST=https://testnet.zklighter.elliot.ai
```

--------------------------------

### Install Lighter Agent Kit

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/README.md

Installs the Lighter Agent Kit using a curl command. This script detects your platform, installs Python if necessary, and registers the skill with selected agents. Restart your agent session after installation.

```bash
curl -fsSL https://github.com/elliottech/lighter-agent-kit/releases/latest/download/install.sh | bash
```

--------------------------------

### Install Lighter SDK

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/SKILL.md

Verifies the correct installation of the lighter-sdk. Should return a JSON object with a status: ok field upon successful verification. This is a diagnostic step and not typically needed for regular use.

```bash
python3 scripts/bootstrap.py
```

--------------------------------

### Install Lighter Agent Kit

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

Installs the Lighter Agent Kit using a curl command. Verifies installation with a health check script.

```bash
# One-line install (macOS arm64, Linux x86_64, Linux arm64)
curl -fsSL https://github.com/elliottech/lighter-agent-kit/releases/latest/download/install.sh | bash
```

```bash
# Verify installation
python3 scripts/health.py
```

```json
{"status": "ok", "version": "0.1.0"}
```

```bash
# Manual installation
git clone https://github.com/elliottech/lighter-agent-kit ~/.agents/skills/lighter-agent-kit
ln -s ~/.agents/skills/lighter-agent-kit ~/.claude/skills/lighter-agent-kit
```

--------------------------------

### Manual Installation of Lighter Agent Kit

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/README.md

Manually installs the Lighter Agent Kit by cloning the repository and creating symbolic links for specific agent environments like Claude Code. Adjust paths for project-scoped installs.

```bash
git clone https://github.com/elliottech/lighter-agent-kit ~/.agents/skills/lighter-agent-kit
ln -s ~/.agents/skills/lighter-agent-kit ~/.claude/skills/lighter-agent-kit  # for Claude Code
```

--------------------------------

### Example: Fund Spot Trade

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/SKILL.md

Demonstrates transferring USDC from the perpetual account to the spot account to fund a subsequent spot trade.

```bash
python3 scripts/trade.py funds transfer --asset usdc --amount 250 \
    --from_route perp --to_route spot
```

--------------------------------

### Verify Lighter Agent Kit Installation

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/README.md

Runs a health check script to verify the installation of the Lighter Agent Kit. This command should be run from the install directory.

```bash
python3 scripts/health.py
```

--------------------------------

### Get Market Info with Lighter Agent Kit

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

Retrieves detailed market metadata such as fees, decimals, and minimum order sizes for a specified market.

```bash
python3 scripts/query.py market info --symbol ETH
```

```json
{
  "code": 200,
  "order_books": [
    {
      "symbol": "ETH",
      "market_id": 0,
      "market_type": "perp",
      "base_asset_id": 1,
      "quote_asset_id": 3,
      "status": "active",
      "taker_fee": "0.00045",
      "maker_fee": "0.00010",
      "liquidation_fee": "0.00500",
      "min_base_amount": "0.0001",
      "min_quote_amount": "10",
      "supported_size_decimals": 4,
      "supported_price_decimals": 2
    }
  ]
}
```

--------------------------------

### Get Market Statistics

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/SKILL.md

Retrieves market overview data including prices, 24h volumes, and daily trades. Use `--symbol` to get data for a specific market.

```bash
market stats [--symbol X]
```

--------------------------------

### Query Account Limits

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

Get trading tier and limits for the authenticated account. This command requires authentication.

```bash
python3 scripts/query.py account limits
```

--------------------------------

### Get System Status

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/SKILL.md

Retrieves the zkLighter system status, including network ID and timestamp. No credentials are required.

```bash
system status
```

--------------------------------

### Get Portfolio Performance

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/SKILL.md

Fetches PnL (Profit and Loss) chart data over a specified time range. Requires private credentials and configuration of resolution and count back.

```bash
portfolio performance --resolution 1h --count_back 24
```

--------------------------------

### Export Lighter API Credentials as Environment Variables

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/README.md

Exports Lighter API credentials as environment variables for CI or manual setup. These variables take precedence over the credentials file. For testnet, set the LIGHTER_HOST variable.

```bash
export LIGHTER_API_PRIVATE_KEY=<private key>
export LIGHTER_ACCOUNT_INDEX=<account index>
export LIGHTER_API_KEY_INDEX=<key index>
```

--------------------------------

### Get Market Stats with Lighter Agent Kit

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

Retrieves market overview data including current prices, 24-hour volumes, and trade counts. Can fetch stats for a specific market or all markets.

```bash
# Get stats for a specific market
python3 scripts/query.py market stats --symbol BTC
```

```json
{
  "code": 200,
  "stats": [
    {
      "symbol": "BTC",
      "market_id": 1,
      "price": "67500.00",
      "volume_24h": "125000000.00",
      "trades_24h": 15234
    }
  ]
}
```

```bash
# Get all market stats (unfiltered)
python3 scripts/query.py market stats
```

--------------------------------

### Get Account Information

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/SKILL.md

Retrieves account details including balances, positions, and assets. Defaults to the LIGHTER_ACCOUNT_INDEX environment variable. Use `--by l1_address` to look up by L1 address. Pass `--include_zero_positions` for PnL and funding analytics.

```bash
account info [--account_index N] [--by l1_address --value 0x…] [--include_zero_positions]
```

--------------------------------

### Get Market Information

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/SKILL.md

Fetches detailed market metadata such as fees, decimals, and minimum trade sizes. Always filter results as unfiltered data can be extensive.

```bash
market info [--market_type perp\|spot] [--symbol X]
```

--------------------------------

### Get Account Trading Limits

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/SKILL.md

Retrieves information about trading limits and tier status for the authenticated account. Requires private credentials.

```bash
account limits
```

--------------------------------

### Get Order History

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/SKILL.md

Fetches the history of filled or canceled orders. A market filter is optional. Requires private credentials.

```bash
orders history [--symbol X] [--market_index N] [--limit 20]
```

--------------------------------

### Get Market Order Book

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/SKILL.md

Retrieves the top-of-book bids and asks for a specified market. The limit parameter controls the number of entries per side.

```bash
market book <symbol> [--limit 20]
```

--------------------------------

### Get Market Candles

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/SKILL.md

Retrieves OHLCV (Open, High, Low, Close, Volume) candle data for a market. Supports various resolutions and historical lookbacks.

```bash
market candles <symbol> --resolution 1h --count_back 24
```

--------------------------------

### Get Market Funding Rates

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/SKILL.md

Fetches funding rates across different venues for a market. It's recommended to always filter by symbol or exchange due to the large amount of unfiltered data.

```bash
market funding [--symbol X] [--market_index N] [--exchange X]
```

--------------------------------

### Query Portfolio Performance

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

Get PnL history over a time range for the authenticated account. Specify resolution and count_back for the desired time period. Requires authentication.

```bash
python3 scripts/query.py portfolio performance --resolution 1h --count_back 24
```

--------------------------------

### Reset Paper Trading Environment

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

Resets the paper trading state, allowing for a fresh start. Can be reset with existing parameters or new collateral and tier values.

```bash
# Reset with same collateral and tier
python3 scripts/paper.py reset
```

```bash
# Reset with new parameters
python3 scripts/paper.py reset --collateral 25000 --tier premium_5
```

--------------------------------

### Execute Lighter Agent Kit Scripts

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/README.md

Run the query, trade, or paper scripts directly from the command line. Ensure you are in the `lighter-agent-kit` directory. Paper trading requires initialization before the first order.

```bash
cd ~/.agents/skills/lighter-agent-kit

python3 scripts/query.py market book BTC --limit 10
python3 scripts/trade.py order limit BTC --side long --amount 0.01 --price 60000
python3 scripts/paper.py init
python3 scripts/paper.py order market BTC --side long --amount 0.1
```

--------------------------------

### Initialize Paper Trading Account

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

Initializes a paper trading account. Use defaults for $10,000 collateral and premium tier, or specify custom collateral and tier.

```bash
# Initialize with defaults ($10,000 collateral, premium tier)
python3 scripts/paper.py init
```

```bash
# Initialize with custom collateral and tier
python3 scripts/paper.py init --collateral 50000 --tier premium_3
```

--------------------------------

### Set Leverage

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

Configure leverage and margin mode for a perpetual market. Default margin mode is cross.

```bash
python3 scripts/trade.py position leverage BTC --leverage 10
```

```bash
python3 scripts/trade.py position leverage ETH --leverage 5 --margin_mode isolated
```

--------------------------------

### Query Account Info by Index

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

Look up account balances, positions, and assets by account index. Defaults to the LIGHTER_ACCOUNT_INDEX environment variable if not specified.

```bash
python3 scripts/query.py account info --account_index 41
```

--------------------------------

### Configure Lighter API Keys

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/README.md

Configures Lighter API credentials using a helper script. This script prompts for your L1 address, resolves the account index, reads your API private key, and securely stores credentials. Re-run to rotate keys or switch accounts.

```bash
./lighter-config
```

--------------------------------

### Get Paper Trading Liquidation Price

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

Estimates the liquidation price for a given position in the paper trading account. Requires the symbol of the asset.

```bash
python3 scripts/paper.py liquidation_price ETH
```

--------------------------------

### Switch Between Live and Paper Trading Scripts

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/SKILL.md

Swap the 'trade.py' and 'paper.py' scripts to switch between live and paper trading environments. The paper trading environment mirrors the live trading API and arguments but does not broadcast trades.

```bash
python3 scripts/trade.py order market BTC --side long --amount 0.1
```

```bash
python3 scripts/paper.py order market BTC --side long --amount 0.1
```

--------------------------------

### Configure API Keys for Lighter Agent Kit

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

Configures API keys for authenticated operations using an interactive helper or environment variables. Includes options for testnet and verification.

```bash
# Interactive configuration (prompts for L1 address and API key)
./lighter-config
```

```bash
# Or set environment variables directly
export LIGHTER_API_PRIVATE_KEY=<80-char-hex-private-key>
export LIGHTER_ACCOUNT_INDEX=<account-index>
export LIGHTER_API_KEY_INDEX=<key-index>
```

```bash
# Use testnet for testing
export LIGHTER_HOST=https://testnet.zklighter.elliot.ai
```

```bash
# Verify credential configuration
python3 scripts/query.py auth status
```

```json
{
  "status": "ok",
  "auth_capable": true,
  "host": "https://mainnet.zklighter.elliot.ai",
  "account_index": 722851,
  "api_key_index": 123,
  "sources": {
    "LIGHTER_API_PRIVATE_KEY": "credentials_file",
    "LIGHTER_ACCOUNT_INDEX": "credentials_file",
    "LIGHTER_API_KEY_INDEX": "credentials_file",
    "LIGHTER_HOST": "default"
  },
  "credentials_file": {
    "path": "/Users/you/.lighter/lighter-agent-kit/credentials",
    "present": true,
    "mode_secure": true
  },
  "missing": []
}
```

--------------------------------

### Query Market Trades

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

Get recent trade history for a specific market. The --limit flag controls the number of trades returned.

```bash
python3 scripts/query.py market trades ETH --limit 20
```

--------------------------------

### Init / Reset Command Response

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/references/schemas-paper.md

Response schema for the `init` and `reset` commands, indicating the status, collateral, tier, fees, and state path.

```APIDOC
## `init` / `reset`

```json
{
  "status": "ok",
  "collateral": 10000,
  "tier": "premium",
  "taker_fee_bps": 2.8,
  "maker_fee_bps": 0.4,
  "state_path": "/Users/you/.lighter/lighter-agent-kit/paper-state.json"
}
```

`reset` with no flags reuses the previous `collateral` and `tier`.
```

--------------------------------

### Set Lighter Agent Kit Credentials via Environment Variables

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/references/env-vars.md

Use these export commands to set the required environment variables for Lighter Agent Kit authentication. Ensure these are set before launching your agent.

```bash
export LIGHTER_API_PRIVATE_KEY=...
export LIGHTER_ACCOUNT_INDEX=...
export LIGHTER_API_KEY_INDEX=...
```

--------------------------------

### Account Info API

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/references/schemas-read.md

Retrieves detailed information about user accounts, including balances, positions, and assets. Can be filtered by address to get master and sub-accounts.

```APIDOC
## GET /api/accounts

### Description
Retrieves account information. If `l1_address` is provided, it returns accounts associated with that address. By default, it returns currently open positions. Use `--include_zero_positions` to get all historical positions.

### Method
GET

### Endpoint
/api/accounts

### Query Parameters
- **l1_address** (string) - Optional - The L1 address to filter accounts by.
- **include_zero_positions** (boolean) - Optional - If true, includes all historical positions, not just currently open ones.

### Response
#### Success Response (200)
- **code** (integer) - API response code.
- **total** (integer) - Total number of accounts returned.
- **accounts** (array) - An array of account objects.
  - **index** (integer) - Account index.
  - **l1_address** (string) - L1 address of the account.
  - **account_type** (integer) - Type of the account.
  - **status** (integer) - Status of the account.
  - **collateral** (string) - Collateral amount.
  - **available_balance** (string) - Available balance.
  - **total_order_count** (integer) - Total number of orders.
  - **pending_order_count** (integer) - Number of pending orders.
  - **positions** (array) - Array of open positions.
    - **market_id** (integer) - Market ID.
    - **symbol** (string) - Trading symbol.
    - **sign** (integer) - Position sign (1 for long, -1 for short).
    - **position** (string) - Position size.
    - **avg_entry_price** (string) - Average entry price.
    - **position_value** (string) - Value of the position.
    - **unrealized_pnl** (string) - Unrealized profit and loss.
    - **realized_pnl** (string) - Realized profit and loss.
    - **liquidation_price** (string) - Liquidation price.
    - **margin_mode** (integer) - Margin mode (0 for cross, 1 for isolated).
    - **allocated_margin** (string) - Allocated margin.
    - **initial_margin_fraction** (string) - Initial margin fraction.
  - **assets** (array) - Array of assets held by the account.
    - **symbol** (string) - Asset symbol.
    - **asset_id** (integer) - Asset ID.
    - **balance** (string) - Asset balance.
    - **locked_balance** (string) - Locked balance.

#### Response Example
```json
{
  "code": 200,
  "total": 1,
  "accounts": [
    {
      "index": 41,
      "l1_address": "0x...",
      "account_type": 0,
      "status": 0,
      "collateral": "0.000000",
      "available_balance": "0.000000",
      "total_order_count": 0,
      "pending_order_count": 0,
      "positions": [
        {
          "market_id": 0,
          "symbol": "ETH",
          "sign": 1,
          "position": "0.0000",
          "avg_entry_price": "0.00",
          "position_value": "0.000000",
          "unrealized_pnl": "0.000000",
          "realized_pnl": "0.000000",
          "liquidation_price": "0",
          "margin_mode": 0,
          "allocated_margin": "0.000000",
          "initial_margin_fraction": "5.00"
        }
      ],
      "assets": [
        {"symbol": "ETH", "asset_id": 1, "balance": "3.00000000", "locked_balance": "0.00000000"}
      ]
    }
  ]
}
```
```

--------------------------------

### Get Market Trades

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/SKILL.md

Fetches recent trade fills for a specific market. The limit parameter can be used to control the number of trades returned, with a maximum of 100.

```bash
market trades <symbol> [--limit 20]
```

--------------------------------

### List Open Orders

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

List currently open orders for a specific market. This command requires authentication.

```bash
python3 scripts/query.py orders open --symbol BTC
```

--------------------------------

### Query Lighter Agent Kit Authentication Status

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/references/env-vars.md

Execute this command to inspect your current Lighter Agent Kit configuration, including authentication status and the source of your credentials (environment variables or credentials file).

```bash
python3 scripts/query.py auth status
```

--------------------------------

### Fetch Market Order Book with Lighter Agent Kit

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

Fetches the top-of-book bids and asks for a specific market. Use bare tickers for perpetual markets and pairs for spot markets.

```bash
# Perp market order book
python3 scripts/query.py market book BTC --limit 10
```

--------------------------------

### Query Order History

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

Get filled, canceled, or expired order history for a specific symbol. Use --limit to control the number of results. Requires authentication.

```bash
python3 scripts/query.py orders history --symbol ETH --limit 50
```

--------------------------------

### Check System Status with Lighter Agent Kit

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

Checks the zkLighter network health and connectivity. Requires no specific arguments.

```bash
python3 scripts/query.py system status
```

```json
{
  "code": 200,
  "network_id": 1,
  "timestamp": 1776654321000
}
```

--------------------------------

### List Markets with Lighter Agent Kit

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

Retrieves a catalog of all available markets, including perpetual and spot markets. Supports filtering by market type and searching for specific markets.

```bash
# List all markets
python3 scripts/query.py market list
```

```json
{
  "code": 200,
  "markets": [
    {"symbol": "ETH", "market_index": 0, "market_type": "perp"},
    {"symbol": "BTC", "market_index": 1, "market_type": "perp"},
    {"symbol": "ETH/USDC", "market_index": 2048, "market_type": "spot"}
  ]
}
```

```bash
# Filter by market type
python3 scripts/query.py market list --market_type perp
```

```bash
# Search for specific markets
python3 scripts/query.py market list --search SOL
```

--------------------------------

### Preview Close All Positions with Cancel All

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/references/schemas-write.md

This preview response includes a note indicating that all resting orders would be cancelled before the closing batch is sent when using the `--with_cancel_all` flag.

```json
{
  "status": "ok",
  "preview": true,
  "note": "--with_cancel_all would cancel all resting orders before sending the close batch",
  "would_close": [
    {
      "symbol": "BTC",
      "market_id": 1,
      "current_side": "long",
      "closing_side": "short",
      "amount": "0.00050"
    }
  ]
}
```

--------------------------------

### Get Paper Trading Account Status

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

Retrieves a summary of the paper trading account, including equity, PnL, and position counts. Use the --no-refresh flag to skip mark price refresh for a faster response.

```bash
# Get paper account summary
python3 scripts/paper.py status
```

```bash
# Skip mark price refresh for faster response
python3 scripts/paper.py status --no-refresh
```

--------------------------------

### Initialize and Reset Paper Trading

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/README.md

Initialize paper trading state for a new session or reset it to a clean state. State is persisted in `~/.lighter/lighter-agent-kit/paper-state.json`.

```bash
python3 scripts/paper.py init
```

```bash
python3 scripts/paper.py reset
```

--------------------------------

### Query Account Info by L1 Address

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

Look up account balances, positions, and assets by L1 address. Use --by l1_address and --value to specify the address.

```bash
python3 scripts/query.py account info --by l1_address --value 0x1234...
```

--------------------------------

### Transfer Between Routes

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

Move assets between your own perpetual and spot collateral buckets.

```bash
python3 scripts/trade.py funds transfer --asset usdc --amount 250 --from_route perp --to_route spot
```

--------------------------------

### List Account API Keys

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/SKILL.md

Lists API keys associated with an account. Omit `--api_key_index` to list all keys for the account.

```bash
account apikeys [--account_index N] [--api_key_index N]
```

--------------------------------

### Market Info Schema

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/references/schemas-read.md

Schema for the 'market info' command, listing available markets with their details. Use this to understand market parameters like fees, minimum amounts, and precision.

```json
{
  "code": 200,
  "order_books": [
    {
      "symbol": "ETH",
      "market_id": 0,
      "market_type": "perp",            // "perp" or "spot"
      "base_asset_id": 1,
      "quote_asset_id": 3,
      "status": "active",
      "taker_fee": "0.00045",
      "maker_fee": "0.00010",
      "liquidation_fee": "0.00500",
      "min_base_amount": "0.0001",
      "min_quote_amount": "10",
      "order_quote_limit": "1000000",
      "supported_size_decimals": 4,     // amount precision
      "supported_price_decimals": 2,    // price precision
      "supported_quote_decimals": 6
    }
  ]
}
```

--------------------------------

### Preview Close All Positions

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/references/schemas-write.md

Use this JSON structure to preview the closing of all open positions without broadcasting any transactions. It shows which positions would be affected.

```json
{
  "status": "ok",
  "preview": true,
  "would_close": [
    {
      "symbol": "BTC",
      "market_id": 1,
      "current_side": "long",
      "closing_side": "short",
      "amount": "0.00050"
    }
  ]
}
```

--------------------------------

### Close All Positions

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

Flatten all open positions with reduce-only market orders. Always preview first using `--preview`. Use `--with_cancel_all` to also remove TP/SL brackets.

```bash
python3 scripts/trade.py order close_all --preview
```

```bash
python3 scripts/trade.py order close_all --slippage 0.02
```

```bash
python3 scripts/trade.py order close_all --with_cancel_all --preview
```

--------------------------------

### Init/Reset Response Schema

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/references/schemas-paper.md

Schema for the response of the `init` or `reset` commands. It includes status, collateral, tier, fee rates, and the state file path. `reset` reuses collateral and tier by default.

```json
{
  "status": "ok",
  "collateral": 10000,
  "tier": "premium",
  "taker_fee_bps": 2.8,
  "maker_fee_bps": 0.4,
  "state_path": "/Users/you/.lighter/lighter-agent-kit/paper-state.json"
}
```

--------------------------------

### paper.py - Local Paper Trading Simulation

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/README.md

The paper.py script enables local, risk-free simulation of trading strategies using paper trading accounts. It supports initialization, order placement, and state management.

```APIDOC
## POST /scripts/paper.py

### Description
This script simulates trading operations locally without using real funds.

### Method
POST (via script execution)

### Endpoint
`python3 scripts/paper.py <command> [args]`

### Commands
- `init`: Initializes the paper trading state. Must be run once per new state file before the first order.
- `reset`: Resets the paper trading state file (`~/.lighter/lighter-agent-kit/paper-state.json`).
- `order limit <symbol> --side S --amount N --price N`: Places a limit order in the paper trading environment.
- `order market <symbol> --side S --amount N`: Places a market order in the paper trading environment.

### Parameters
- `symbol` (string): The trading symbol (e.g., BTC).
- `side` (string): Order side (`buy`, `sell`, `long`, `short`).
- `amount` (number): The quantity of the asset to trade.
- `price` (number): The price for limit orders.

### Request Example
```bash
python3 scripts/paper.py init
python3 scripts/paper.py order market BTC --side long --amount 0.1
```

### Response
- **JSON object**: Contains the result of the paper trading operation or an error message `{"error": "..."}`.
```

--------------------------------

### Place Market Order

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/README.md

Execute a market order with a default 1% slippage budget. The `--side` parameter accepts 'buy', 'sell', 'long', or 'short'.

```bash
python3 scripts/trade.py order market <symbol> --side S --amount N
```

--------------------------------

### Check Authentication Status

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/SKILL.md

Performs a local precheck of authentication credentials. Returns `auth_capable` and the source for each credential. Run this before making authenticated calls.

```bash
auth status
```

--------------------------------

### Place Limit Order

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

Place a limit order on perpetual or spot markets. Prices and amounts are in human units. Use `--post_only` to ensure the order is not immediately matched. Use `--reduce_only` to close an existing position.

```bash
python3 scripts/trade.py order limit BTC --side long --amount 0.01 --price 65000
```

```bash
python3 scripts/trade.py order limit ETH --side short --amount 0.5 --price 2300 --post_only
```

```bash
python3 scripts/trade.py order limit BTC --side short --amount 0.01 --price 70000 --reduce_only
```

```bash
python3 scripts/trade.py order limit ETH/USDC --side buy --amount 1.0 --price 2200
```

--------------------------------

### Query Account Information

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/README.md

Retrieve public account details like info and API keys using an optional `--account_index`. Authenticated reads include limits, performance, and order history.

```bash
python3 scripts/query.py account info [--account_index N]
```

```bash
python3 scripts/query.py account apikeys [--account_index N]
```

```bash
python3 scripts/query.py account limits
```

```bash
python3 scripts/query.py portfolio performance --resolution 1h
```

```bash
python3 scripts/query.py orders open --symbol X
```

```bash
python3 scripts/query.py orders history
```

--------------------------------

### List Markets with Search

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/SKILL.md

Discovers market tickers when a user provides a vague search term. Use this to find specific market symbols like 'BRENTOIL', 'XAU', or 'XAG' before executing other commands. Supports filtering by market type.

```bash
python3 scripts/query.py market list --search <substring> [--market_type perp|spot]
```

--------------------------------

### trade.py - Live Trading Operations

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/README.md

The trade.py script handles signed write operations against the live Lighter trading platform, including order placement, modification, cancellation, and position management.

```APIDOC
## POST /scripts/trade.py

### Description
This script executes signed trading operations on the live Lighter exchange.

### Method
POST (via script execution)

### Endpoint
`python3 scripts/trade.py <command> [args]`

### Commands
#### Order Management
- `order limit <symbol> --side S --amount N --price N`: Places a limit order. Supports `--reduce_only` and `--post_only`.
- `order market <symbol> --side S --amount N`: Places a market order with a default 1% slippage budget.
- `order modify <symbol> --order_index COI --price N --amount N`: Modifies an existing order identified by `client_order_index` (COI).
- `order cancel <symbol> --order_index COI`: Cancels a specific order using its COI.
- `order cancel_all`: Cancels all open orders across all markets.
- `order close_all [--slippage N] [--with_cancel_all] [--preview]`: Flattens all open positions. Options include setting slippage, canceling all orders, and previewing the action.

#### Position Management
- `position leverage <symbol> --leverage N`: Sets the leverage for a given symbol. Supports `--margin_mode cross|isolated`.
- `position margin <symbol> --amount N --direction add|remove`: Adjusts the margin for isolated margin positions.

#### Funds Management
- `funds withdraw --asset A --amount N`: Initiates a withdrawal for a specified asset and amount. Supports `--route perp|spot`.
- `funds transfer --asset A --amount N --from_route X --to_route Y`: Transfers funds between perp and spot collateral accounts.

### Parameters
- `symbol` (string): The trading symbol (e.g., BTC).
- `side` (string): Order side (`buy`, `sell`, `long`, `short`).
- `amount` (number): The quantity of the asset to trade.
- `price` (number): The price for limit orders.
- `order_index` (string): The `client_order_index` (COI) of an order for modification or cancellation.
- `leverage` (number): The leverage value.
- `margin_mode` (string): `cross` or `isolated` for leverage settings.
- `direction` (string): `add` or `remove` for margin adjustments.
- `asset` (string): The asset identifier (e.g., BTC, USDT).
- `from_route` (string): Source account for transfers (e.g., `perp`, `spot`).
- `to_route` (string): Destination account for transfers (e.g., `perp`, `spot`).
- `slippage` (number): Slippage budget for `close_all`.

### Request Example
```bash
python3 scripts/trade.py order limit BTC --side buy --amount 0.01 --price 60000
python3 scripts/trade.py position leverage BTC --leverage 10 --margin_mode isolated
```

### Response
- **JSON object**: Contains details of the executed operation, including a `client_order_index` for new orders, or an error message `{"error": "..."}`.
```

--------------------------------

### Order Close All - Preview

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/references/schemas-write.md

Preview the effect of closing all open positions without broadcasting any transactions. This shows which positions would be closed and with what details.

```APIDOC
## POST /api/v1/order/close_all

### Description
Flattens every open position with per-market reduce-only market orders. Returns a summary envelope instead of the standard `{tx_hash, tx}` shape, because one call can submit multiple signed txs in a single `sendTxBatch` request.

### Method
POST

### Endpoint
/api/v1/order/close_all

### Parameters
#### Query Parameters
- **with_cancel_all** (boolean) - Optional - If set, all resting orders will be cancelled before sending the close batch.

### Request Example
```json
{
  "preview": true
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the operation (e.g., "ok").
- **preview** (boolean) - True if the response is a preview.
- **would_close** (array) - An array of objects, each detailing a position that would be closed.
  - **symbol** (string) - The trading symbol (e.g., "BTC").
  - **market_id** (integer) - The unique identifier for the market.
  - **current_side** (string) - The current side of the position (e.g., "long").
  - **closing_side** (string) - The side of the closing order (e.g., "short").
  - **amount** (string) - The amount to be closed.
- **note** (string) - Optional. Provides additional information, especially when `--with_cancel_all` is used in preview mode.

#### Response Example (Preview)
```json
{
  "status": "ok",
  "preview": true,
  "would_close": [
    {
      "symbol": "BTC",
      "market_id": 1,
      "current_side": "long",
      "closing_side": "short",
      "amount": "0.00050"
    }
  ]
}
```

#### Response Example (Preview with --with_cancel_all)
```json
{
  "status": "ok",
  "preview": true,
  "note": "--with_cancel_all would cancel all resting orders before sending the close batch",
  "would_close": [
    {
      "symbol": "BTC",
      "market_id": 1,
      "current_side": "long",
      "closing_side": "short",
      "amount": "0.00050"
    }
  ]
}
```
```

--------------------------------

### query.py - Market and Account Data Reads

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/README.md

The query.py script is used for fetching market data, public account information, and authenticated account details.

```APIDOC
## GET /scripts/query.py

### Description
This script retrieves various market and account data from the Lighter platform.

### Method
GET (via script execution)

### Endpoint
`python3 scripts/query.py <command> [args]`

### Commands
#### Market Data
- `market list`: Lists available symbols.
- `market stats [--symbol X]`: Provides price and 24h volume statistics for a symbol.
- `market info [--symbol X]`: Retrieves fee, decimal, and minimum size information for a symbol.
- `market book <symbol>`: Fetches the order book snapshot for a given symbol.
- `market trades <symbol>`: Retrieves recent trade history for a symbol.
- `market candles <symbol> --resolution 1h`: Gets OHLCV data for a symbol with specified resolution (e.g., 1m, 5m, 1h, 1d).
- `market funding --symbol X`: Fetches the funding rate for a symbol.

#### Account Data
- `account info [--account_index N]`: Retrieves public account information. If `--account_index` is provided, it's a public read; otherwise, it may require authentication.
- `account apikeys [--account_index N]`: Lists public API keys for an account. If `--account_index` is provided, it's a public read.
- `account limits`: Retrieves user's tier and trading limits (Authenticated).
- `portfolio performance --resolution 1h`: Fetches PnL series data (Authenticated).
- `orders open --symbol X`: Lists open orders for a symbol (Authenticated).
- `orders history`: Retrieves past order history (Authenticated).

#### Authentication
- `auth status`: Checks the status of local credentials.

### Parameters
- `symbol` (string): The trading symbol (e.g., BTC).
- `resolution` (string): The time resolution for candle data (e.g., 1h, 1d).
- `account_index` (integer): The index of the account to query.
- `limit` (integer): Maximum number of results to return (e.g., for `market book`).

### Request Example
```bash
python3 scripts/query.py market book BTC --limit 10
python3 scripts/query.py account limits
```

### Response
- **JSON object**: Contains the requested data or an error message `{"error": "..."}`.

### Response Example
```json
{
  "symbol": "BTC",
  "bids": [
    {"price": 60000.00, "amount": 0.5},
    {"price": 59999.50, "amount": 1.2}
  ],
  "asks": [
    {"price": 60000.50, "amount": 0.8},
    {"price": 60001.00, "amount": 1.0}
  ]
}
```
```

--------------------------------

### Precision Echoback for Order Commands

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/references/schemas-write.md

Order limit, order market, and order modify commands echo the actual values sent to the exchange after rounding to market precision. Use `effective_amount` and `effective_price` to confirm order details on the book.

```json
{
  "status": "submitted",
  "tx_hash": "...",
  "client_order_index": 12345,
  "effective_amount": "0.0057",
  "effective_price": "4050.57",
  "tx": { ... }
}
```

--------------------------------

### List Markets

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/SKILL.md

Fetches a compact catalog of markets, useful for symbol to market index lookups. Supports filtering by market type and searching.

```bash
market list [--market_type perp\|spot] [--search X]
```

--------------------------------

### Query Account Info with Zero Positions

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

Include zero positions in the account information query for lifetime PnL analysis.

```bash
python3 scripts/query.py account info --include_zero_positions
```

--------------------------------

### Transfer ETH using trade.py

Source: https://context7.com/elliottech/lighter-agent-kit/llms.txt

Transfers a specified amount of ETH between two routes (e.g., spot to perp). Ensure the 'trade.py' script is available and configured.

```bash
python3 scripts/trade.py funds transfer --asset eth --amount 1.0 --from_route spot --to_route perp
```

--------------------------------

### Query Market Data

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/SKILL.md

Executes read commands using the query.py script. Use this for fetching market statistics, order books, trades, and other non-transactional data. Paths are relative to the skill's directory.

```bash
python3 scripts/query.py <group> <action> ARGS
```

--------------------------------

### Query Market Data

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/README.md

Fetch market data such as order books, trades, candles, and funding rates. Some commands support optional account index for public reads.

```bash
python3 scripts/query.py market book BTC --limit 10
```

```bash
python3 scripts/query.py market list
```

```bash
python3 scripts/query.py market stats --symbol X
```

```bash
python3 scripts/query.py market info --symbol X
```

```bash
python3 scripts/query.py market book <symbol>
```

```bash
python3 scripts/query.py market trades <symbol>
```

```bash
python3 scripts/query.py market candles <symbol> --resolution 1h
```

```bash
python3 scripts/query.py market funding --symbol X
```

--------------------------------

### Manage Position Leverage

Source: https://github.com/elliottech/lighter-agent-kit/blob/main/README.md

Set leverage for a symbol, supporting 'cross' or 'isolated' margin modes.

```bash
python3 scripts/trade.py position leverage <symbol> --leverage N
```