Lighter trading

1. Prepare a test account

Activate your wallet at Lighter Testnet and request test funds. Open Tools → API Keys, note your account index, and register a dedicated unused API key. Slots 0–3 are reserved; avoid Robinhood’s reserved slot 157 too. Review wallet signatures yourself.

Save only the API signing key in a private local configuration file. Do not send your wallet seed, wallet private key or API signing key to Apiary. Connecting a website wallet does not configure your local agent.

{
  "network": "testnet",
  "accountIndex": 123,
  "apiKeyIndex": 4,
  "apiPrivateKey": "YOUR_LOCAL_API_SIGNING_KEY",
  "maxOrderUsd": 25
}

Replace 123 with your real account index. Keep this file out of version control and run chmod 600 /path/to/private-lighter-config.json.

2. Connect the local agent

For agents running the Apiary repository’s local MCP server, install the pinned official signing SDK. Node 22+, Python 3.9+ and an SDK-supported platform are required. The remote MCP provides discovery; it does not store your trading key.

python3 -m venv .lighter-venv
.lighter-venv/bin/python -m pip install lighter-sdk==1.1.6
APIARY_URL=https://www.apiary.world \
LIGHTER_CONFIG=/absolute/path/to/private-lighter-config.json \
npm run mcp

lighter_markets

Discover markets, precision and minimum order sizes.

lighter_orderbook

Inspect live bid/ask prices before setting a price bound.

lighter_account

Read the configured account’s balances and positions.

lighter_place_order

Sign and submit an explicit market or limit order locally.

lighter_cancel_order

Cancel using the original client order index.

lighter_transaction

Reconcile a transaction hash after submission or timeout.

lighter_orders

Inspect active orders or history and actual filled quantity.

3. Verify the trade, not just submission

Discover the actual market ID first; IDs differ by network and may change on testnet. Use an explicit decimal size and worst acceptable fill price. Market orders are immediate-or-cancel; the local agent’s limit orders expire after ten minutes. Its default per-order cap is 25 USD-denominated quote units.

1. Place a small non-crossing post-only limit order, confirm it is active, then cancel it and check its cancelled history.
2. Place a small market order above the minimum, check the transaction and confirm its filled quantity in order history.
3. Close only the test position with a reduce-only order. Confirm the close fill, zero remaining position and no open test orders.

An accepted transaction is not a filled trade. After a timeout, query the original hash and client order index. Never blindly create a replacement order.

Direct HTTP integration

curl 'https://www.apiary.world/api/gateway/svc_lighter/markets?network=testnet'

Other agents can use Lighter’s official SDK to sign locally, then POST {network, txType, txInfo} to /api/gateway/svc_lighter/submit. Only signed create/cancel types 14 and 15 are allowed. Send the signed JSON string unchanged. Read orders with POST /orders and a short-lived locally signed auth token in the request body, never the URL. See the listing for all endpoint fields.

Fees, retries and boundaries

There is no Apiary gateway fee for this integration. Lighter’s trading fees and collateral rules still apply. This relay cannot transfer or withdraw funds, replace keys or submit batches. Trading itself can lose funds on mainnet.

The local agent journals signed operations before submission and returns the same receipt on an identical client-index retry. Do not delete its journal to retry an unknown outcome. Use a dedicated key per runner; local locks do not coordinate different machines.

Supported networks: testnet, rh-testnet, mainnet, rh-mainnet. Keys and accounts are network-specific. Mainnet writes require a deliberate local LIGHTER_ALLOW_MAINNET_TRADING=true opt-in; leave it disabled for testing.