elliottech/lighter-agent-kit

Lighter Agent Kit

동일한 명령어로 Lighter 또는 Robinhood Chain 배포에서 거래하세요.

스크립트는 이 스킬의 scripts/ 디렉토리에 있습니다. 읽기 명령은 query.py, 쓰기 명령은 trade.py를 사용합니다. 모든 명령은 구조화된 JSON을 표준 출력으로 출력합니다. 오류는 항상 {"error": "..."} 형식의 JSON으로 반환됩니다.

명령어는 Lighter UI와 동일한 <그룹> <동작> 구문을 사용합니다(예: market stats, order limit, orders open).

응답 스키마와 자세한 내용은 references/ 폴더를 참조하세요.

설치

이 폴더를 표준 Claude Code 스킬 위치 중 하나에 복사하세요:

• 개인 (모든 프로젝트): ~/.claude/skills/lighter-agent-kit/
• 프로젝트 레벨 (이 저장소만): .claude/skills/lighter-agent-kit/

첫 호출 시 lighter-sdk와 그 전이적 종속성이 <스킬>/.vendor/pyX.Y/에 설치됩니다. 모든 버전은 requirements.lock에 고정되어 있습니다. 지원 대상은 Apple Silicon Mac과 Linux x86_64/arm64입니다. 인텔 맥은 이 키트에서 지원되지 않습니다.

선택한 Lighter 호스트(mainnet.zklighter.elliot.ai, testnet.zklighter.elliot.ai, api.rh.lighter.xyz, api.rh-testnet.lighter.xyz), pypi.org / files.pythonhosted.org, github.com으로의 네트워크 아웃바운드가 필요합니다(pip은 고정된 lighter-sdk 빌드를 GitHub에서 클론합니다). Claude.ai 샌드박스의 기본 아웃바운드 허용 목록에는 github.com이 포함되어 있지 않습니다. 첫 실행 전에 이를 확장해야 합니다.

읽기 명령은 자격 증명 없이 작동합니다. 쓰기 명령과 계정-비공개 읽기는 먼저 환경 변수를 확인한 다음 개인 자격 증명 파일을 확인합니다. references/env-vars.md를 참조하세요.

사용자 요청 처리 방법

1. 심볼 규칙: 선물-베어, 현물-페어. 선물 시장은 베어 티커(BTC, ETH, SOL, LIT)를 사용하고, 현물 시장은 견적 통화가 포함된 페어(ETH/USDC on Lighter, AAPL/USDG on Robinhood Lighter)를 사용합니다. /의 존재가 유일한 판별자입니다. 심볼이 확인된 명령에는 --market_type 플래그가 필요하지 않습니다. 숫자 market_index도 탈출구로 허용됩니다.
2. 심볼 확인은 자동입니다. 마켓 심볼은 실시간 오더북 API에서 확인되며 호스트별로 5분 동안 디스크에 캐시되므로 query.py, trade.py, paper.py가 호출 간에 동일한 마켓 맵을 공유합니다. 자산은 선택한 배포에 대해 확인됩니다. collateral은 모호하지 않은 경우 견적 자산을 별칭으로 사용합니다. 사용자가 자신 있게 매핑할 수 없는 항목(예: "브렌트유", "금", "은")을 언급하는 경우에만 먼저 python3 scripts/query.py market list --search <하위문자열> [--market_type perp|spot]를 실행하여 찾으십시오. 이는 일반적으로 BRENTOIL, XAU, XAG와 같은 티커 스타일 심볼로 나타납니다.
3. 매매 방향은 두 가지 형식을 모두 허용합니다. --side buy|sell|long|short — 선물과 현물 모두 허용됩니다. 내부적으로 정규 형식(선물은 long/short, 현물은 buy/sell)으로 정규화됩니다.
4. 고유한 읽기에서는 소스에서 필터링하세요. market funding, market stats, market info는 --symbol / --market_index / --exchange를 허용합니다. 한 행만 필요한 경우 항상 전달하세요.
5. 일치하는 스크립트 실행: 읽기는 python3 scripts/query.py <그룹> <동작> 인수, 쓰기는 python3 scripts/trade.py <그룹> <동작> 인수. 경로는 이 스킬의 디렉토리를 기준으로 합니다.
6. JSON을 파싱하고 명확하게 표시하세요.
7. 계정 범위 명령어 및 LIGHTER_ACCOUNT_INDEX. 두 가지 경우:
   • 공개 읽기 (account info, account apikeys)는 --account_index를 허용하며 생략 시 LIGHTER_ACCOUNT_INDEX를 기본값으로 사용합니다.
   • 인증된 읽기 (account limits, portfolio performance, orders open, orders history)는 자기 자신 전용이며 --account_index 대신 LIGHTER_ACCOUNT_INDEX를 사용합니다. 인증 토큰이 해당 계정에 바인딩되어 있기 때문입니다.

진단(선택 사항): 호출이 import lighter 스타일 오류로 실패하면 python3 scripts/bootstrap.py를 실행하여 SDK가 올바르게 벤더링되었는지 확인하세요. status: ok 필드가 있는 응답을 반환해야 합니다. 정상 세션에서는 이 작업을 실행할 필요가 없습니다.

---

읽기 명령 (query.py)

공개 읽기 — 자격 증명 필요 없음

명령어	목적
system status	zkLighter 시스템 상태(네트워크 ID, 타임스탬프).
market list [--market_type perp|spot] [--search X]	간결한 {symbol, market_index, market_type} 카탈로그. 심볼 → 인덱스 조회에 사용.
market stats [--symbol X]	시장 개요: 가격, 24시간 거래량, 일일 거래 횟수. 한 행을 얻으려면 --symbol을 전달하세요.
market info [--market_type perp|spot] [--symbol X]	전체 시장 메타데이터(수수료, 소수점, 최소 크기). 항상 필터링하세요. 필터링하지 않으면 약 150행입니다.
market book <symbol> [--limit 20]	최우선 매수/매도 호가. <symbol>은 선물 티커(BTC), 현물 페어(ETH/USDC) 또는 숫자 market_index입니다. --limit은 측당입니다.
market trades <symbol> [--limit 20]	한 시장의 최근 체결 내역. --limit 최대 100.
market candles <symbol> --resolution 1h --count_back 24	OHLCV 캔들. 해상도: 1m, 5m, 15m, 30m, 1h, 4h, 1d. o/h/l/c(가격), v(기준량), V(견적량), t(버킷 시작, ms), i(마지막 거래 ID) 반환.
market funding [--symbol X] [--market_index N] [--exchange X]	거래소 간 펀딩 비율. 필터링하지 않으면 약 300행. 항상 --symbol 또는 --exchange를 전달하세요.
account info [--account_index N] [--by l1_address --value 0x…] [--include_zero_positions]	계정 조회: 잔액, 포지션, 자산. 기본값은 LIGHTER_ACCOUNT_INDEX입니다. 대신 L1 주소로 조회하려면 --by l1_address --value …를 사용하세요. positions[]는 기본적으로 현재 열린 포지션으로 필터링됩니다. Lighter는 계정이 한 번이라도 접촉한 시장당 하나의 행을 유지하므로 원시 목록이 매우 클 수 있고 대부분 평평합니다. 시장별 평생 realized_pnl / total_funding_paid_out이 필요한 경우(PnL 분석, 펀딩 감사, 세금 보고) --include_zero_positions를 전달하세요.
account apikeys [--account_index N] [--api_key_index N]	계정의 API 키를 나열합니다. 모든 키를 나열하려면 --api_key_index를 생략하세요(기본값 255).
auth status	로컬 전용 자격 증명 사전 확인. auth_capable + 자격 증명당 출처를 반환합니다. 인증된 호출 전에 한 번 실행하세요.

계정-비공개 읽기 — LIGHTER_API_PRIVATE_KEY + LIGHTER_ACCOUNT_INDEX + LIGHTER_API_KEY_INDEX 필요

이 엔드포인트는 호출할 때마다 구성된 자격 증명에서 수명이 짧은 인증 토큰을 생성합니다. 인증 토큰은 LIGHTER_ACCOUNT_INDEX에 바인딩되므로 아래 네 명령어는 모두 자기 자신 전용입니다. --account_index를 허용하지 않으며, 개인 키가 토큰에 서명한 계정과 다른 계정을 쿼리할 방법이 없습니다.

명령어	목적
account limits	거래 한도 및 등급 정보.
portfolio performance --resolution 1h --count_back 24	시간 범위에 따른 PnL 차트.
orders open (--symbol X | --market_index N)	한 시장의 미체결 주문. --symbol(선물 티커 또는 현물 페어) 또는 --market_index 중 하나를 전달하세요.
orders history [--symbol X] [--market_index N] [--limit 20]	체결/취소된 주문 내역. 시장 필터는 선택 사항입니다.

플랫폼 참고: claude.ai의 샌드박스 bash 환경에서는 env var를 export할 지속적인 셸이 없으며, 채팅에 API 개인 키를 붙여넣는 것은 허용되지 않습니다. 위 네 명령어는 사실상 Claude Code / Cursor / 데스크톱 전용입니다. claude.ai에서는 공개 읽기로 대체하거나 계정-비공개 보기를 위해 사용자를 Lighter 웹/모바일 UI로 안내하세요.

건전성 확인: python3 scripts/health.py는 SDK를 건드리지 않고 {"status": "ok", "version": "..."}를 반환합니다. 스킬이 전혀 로드되는지 확인하는 데 유용합니다.

전체 응답 형태는 references/schemas-read.md를 참조하세요.

---

쓰기 명령 (trade.py)

모든 쓰기 명령에는 자격 증명이 필요합니다. 가격과 수량은 인간 단위입니다(예: --price 4050.5 --amount 0.1). 스크립트는 시장 메타데이터를 가져와 자동으로 정수 틱/로트로 스케일링합니다. 응답은 effective_amount / effective_price를 에코하므로 반올림 후 실제로 무엇이 적용되었는지 확인할 수 있습니다.

매매 방향은 두 가지 형식을 모두 허용합니다: --side buy|sell|long|short. 선물 및 현물 시장 모두에서 허용됩니다. 내부적으로 정규 형식(선물은 long/short, 현물은 buy/sell)으로 정규화됩니다.

심볼 규칙: 위치 인수 <symbol>은 선물 티커(BTC, ETH), 현물 페어(ETH/USDC, LIT/USDC) 또는 숫자 market_index(1)입니다. 현물 심볼의 /는 판별자입니다. --market_type 플래그가 필요하지 않습니다.

현물 거래: 모든 주문 명령어는 현물 시장에서 투명하게 작동합니다. ETH/USDC와 같은 현물 페어를 전달하기만 하면 됩니다. 현물 시장을 찾으려면 query.py market list --market_type spot을 사용하세요. 현물 시장에서 --reduce_only와 position leverage / position margin 명령어는 아무 작업도 수행하지 않습니다. 현물에는 레버리지 포지션이 없습니다.

명령어	주요 인수
order limit <symbol> --side <side> --amount N --price N [--reduce_only] [--post_only]	선물 또는 현물의 지정가 주문.
order market <symbol> --side <side> --amount N [--slippage N] [--reduce_only]	선물 또는 현물의 시장가 주문. 기본 슬리피지 0.01 (1%).
order modify <symbol> --order_index COI --price N --amount N	COI는 order limit이 반환한 client_order_index입니다.
order cancel <symbol> --order_index COI	단일 미체결 주문 취소.
order cancel_all	모든 시장의 모든 미체결 주문을 취소합니다(인수 없음).
order close_all [--slippage N] [--with_cancel_all] [--preview]	고위험. 모든 열린 포지션을 축소 전용 시장가 주문으로 청산합니다. 모든 시장에서 동시에 PnL을 실현합니다. 실제 호출 전에 항상 --preview를 먼저 실행하고 명시적인 사용자 승인을 받으십시오. "정리" 또는 "리셋"과 같은 문구에서 의도를 자동으로 추론하지 마십시오. --with_cancel_all은 TP/SL 브래킷도 제거합니다. --preview와 결합하면 응답에 cancel-all이 먼저 실행된다는 메모가 포함되지만 would_close[]는 여전히 포지션만 나열합니다.
position leverage <symbol> --leverage N [--margin_mode cross|isolated]	레버리지 설정. 기본값 cross.
position margin <symbol> --amount N --direction add|remove	금액은 배포 담보(USDC 또는 USDG)입니다. 격리 포지션에서만 유효합니다.
account mode --mode classic|unified	고위험. 계정 전체의 증거금 동작을 변경합니다. query.py account info를 검사하고 먼저 명시적인 사용자 승인을 받으십시오.
account collateral --asset A --mode enabled|disabled	고위험. 통합 모드에서 자격이 있는 자산이 담보에 기여하는지 여부를 변경합니다. 계정을 검사하고 먼저 명시적인 사용자 승인을 받으십시오.
funds withdraw --asset A --amount N [--route perp|spot]	기본 경로 perp. 모든 배포 자산 심볼 또는 숫자 자산 ID를 허용합니다. collateral은 모호하지 않은 경우 견적 자산을 별칭으로 사용합니다. 이는 출금 요청을 생성합니다. 자금이 보류/클레임 흐름으로 이동하여 지갑에 즉시 나타나지 않을 수 있습니다.
funds transfer --asset A --amount N --from_route perp|spot --to_route perp|spot	자체 현물 및 선물 버킷 간에 모든 배포 자산을 이동합니다. L1 서명, 계정 간 라우팅이 없습니다.

order limit 및 order market은 client_order_index를 반환합니다. 이를 저장하십시오. 나중에 order modify / order cancel을 위한 핸들입니다.

예시 — 현물 매수를 위해 배포 담보를 선물에서 현물로 이체:

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

예시 — Robinhood Lighter에서 SPY 담보 활성화:

python3 scripts/query.py account info
python3 scripts/trade.py account mode --mode unified
python3 scripts/query.py account info  # account_trading_mode가 1이 될 때까지 대기
python3 scripts/trade.py account collateral --asset SPY --mode enabled
python3 scripts/query.py account info

위 두 쓰기 명령어는 별도의 명시적인 사용자 승인이 필요합니다. account collateral --mode enabled는 선택한 배포가 담보 자격을 부여하지 않은 자산과 Classic 모드 계정을 거부합니다.

모든 명령어는 --help를 지원합니다. 응답 봉투, 정밀도 에코백 및 오류 코드 테이블은 references/schemas-write.md를 참조하세요.

---

페이퍼 트레이딩 (paper.py)

자격 증명 없이, 브로드캐스트 없이, 위험 없이 실제 Lighter 오더북 스냅샷에 대해 거래를 시뮬레이션합니다. 모든 상태는 로컬입니다.

공유 하위 집합 명령어는 trade.py와 동일한 <그룹> <동작> 형태를 사용하므로 스크립트 이름을 바꾸면 엔진이 바뀝니다. 페이퍼 전용 수명 주기 명령어는 평평하게 유지됩니다.

명령어

페이퍼 전용 (평평):

명령어	목적
init [--collateral N] [--tier T]	페이퍼 계정 생성. 기본값: --collateral 10000 --tier premium.
reset [--collateral N] [--tier T]	상태 초기화. 인수 없음 형식은 이전 담보 및 등급을 재사용합니다.
set_tier --tier T	기존 계정의 수수료 등급 변경(캐시된 시장 구성을 업데이트).
status [--no-refresh]	계정 요약: 담보, PnL, 포지션/거래 수. 모든 열린 포지션의 마크 가격을 자동으로 새로 고칩니다. 건너뛰려면 --no-refresh를 전달하세요.
positions [--symbol X] [--no-refresh]	열린 포지션. --symbol이 없으면 모두 나열합니다. 마크 가격을 자동으로 새로 고칩니다.
trades [--symbol X] [--limit 50]	거래 내역, 최신순.
health [--no-refresh]	계정 건전성: TAV, 증거금 요구 사항, 레버리지. 마크 가격을 자동으로 새로 고칩니다.
liquidation_price <symbol> [--no-refresh]	포지션의 예상 청산 가격. 마크 가격을 자동으로 새로 고칩니다.
refresh <symbol>	한 시장의 오더북 스냅샷을 강제로 새로 고칩니다. 거래 전에 시장을 미리 워밍업하거나 모든 읽기에서 --no-refresh를 전달하지 않고 현재 마크 데이터를 원할 때 유용합니다.

공유 하위 집합 (trade.py 형태 미러링):

명령어	목적
order market <symbol> --side buy|sell|long|short --amount N	라이브 북 스냅샷에 대한 테이커 시장가 주문.
order ioc <symbol> --side buy|sell|long|short --amount N --price N	지정가가 있는 테이커 IOC 주문.

교체 규칙: trade.py ↔ paper.py를 교체하여 실제 거래와 시뮬레이션을 전환합니다:

# 라이브 시장가 주문 (실제 자금 필요)
python3 scripts/trade.py order market BTC --side long --amount 0.5

# 동일한 주문 시뮬레이션 (위험 없음)
python3 scripts/paper.py order market BTC --side long --amount 0.5