OKX Agent Trade Kit

OKX Agent Trade Kit — 두 개의 독립적인 패키지로 구성된 AI 기반 트레이딩 툴킷(toolkit)입니다:

패키지	설명
okx-trade-mcp	Claude / Cursor 및 모든 MCP 호환 AI 클라이언트를 위한 MCP 서버
okx-trade-cli	터미널에서 OKX를 조작하기 위한 CLI

OKX Agent Trade Kit는 Model Context Protocol (MCP)을 통해 AI 어시스턴트를 사용자의 OKX 계정에 직접 연결합니다. AI와 거래소 UI 사이를 전환할 필요 없이, 원하는 내용을 설명하기만 하면 됩니다. 그러면 AI가 적절한 도구(tools)를 호출하여 실행합니다.

이 툴킷은 API 키가 사용자의 기기에만 저장되는 **로컬 프로세스 (local process)**로 실행됩니다. 클라우드 서비스는 없으며, 데이터가 기기를 벗어나지 않습니다.

기능	설명
11개 모듈(17개 서브 모듈)에 걸친 163개 도구	전체 트레이딩 라이프사이클: 시장 데이터(market data) → 주문(orders) → 알고리즘 주문(algo orders) → 계정 관리(account management) → 수익 창출(earn) → 트레이딩 봇(trading bots) → 이벤트 계약(event contracts) → 뉴스(news) → 스마트 머니 신호(smart money signals)
알고리즘 주문 내장	조건부 주문, OCO 익절/손절(take-profit/stop-loss), 트레일링 스탑(trailing stop)
안전 제어	--read-only 플래그, 모듈별 필터링, 내장 속도 제한기(rate limiter)
인프라 불필요	로컬 stdio 프로세스, 서버나 데이터베이스 불필요
MCP 표준	Claude Desktop, Cursor, openCxxW 및 모든 MCP 호환 클라이언트와 작동
에이전트 스킬(Agent Skills) 포함	AI 에이전트 프레임워크를 위한 사전 구축된 스킬 파일 — 시장 데이터, 트레이딩, 포트폴리오, 봇, 수익 창출을 다루는 즉시 사용 가능한 지침(instructions) 제공
오픈 소스	MIT 라이선스, API 키는 절대 기기를 떠나지 않음

모듈 (Module)	도구 (Tools)	설명 (Description)	문서 (Docs)
market	19	티커 (Ticker), 오더북 (orderbook), 캔들 (candles) (+이력), 인덱스 티커 (index ticker), 인덱스 캔들 (index candles), 가격 제한 (price limit), 펀딩 레이트 (funding rate), 마크 가격 (mark price), 미결제약정 (open interest), 스톡 토큰 (stock tokens), 기술적 지표 (70개 이상의 지표: MA/EMA/RSI/MACD/BB/ATR/KDJ/BTCRAINBOW/AHR999 등 — 인증 불필요), 지표 리스트, 시장 필터 (가격/변동률/시가총액/거래량/펀딩레이트/미결제약정 기준 스크리닝), 미결제약정 (OI) 이력, 미결제약정 (OI) 변동 필터	→
spot	13	주문 생성/취소/수정, 일괄 주문 (batch orders), 체결 (fills) (+아카이브), 주문 이력 (order history) (+아카이브), 조건부 주문 (conditional orders), OCO	→
swap	17	무기한 선물 거래 (Perpetual trading), 일괄 주문 (batch orders), 포지션 (positions), 레버리지 (leverage), 조건부 주문 (conditional orders), OCO, 트레일링 스톱 (trailing stop)	→
futures	18	인도형 계약 거래 (Delivery contract trading), 포지션 (positions), 체결 (fills), 주문 이력 (order history), 수정/종료/레버리지 (amend/close/leverage), 일괄 주문 (batch orders), 알고리즘 주문 (algo orders) (TP/SL, OCO, 트레일링 스톱)	→
option	10	옵션 거래: 생성/취소/수정/일괄 취소, 주문 이력, 포지션 (Greeks 포함), 체결, 옵션 체인 (option chain), 내재 변동성 (IV) + Greeks	→
account	14	잔고 (Balance), 청구서 (bills) (+아카이브), 포지션 (positions), 포지션 이력 (positions history), 수수료율 (fee rates), 설정 (config), 포지션 모드 (position mode), 최대 출금액 (max withdrawal), 최대 가용 규모 (max avail size), 감사 로그 (audit log)	→
event	9	이벤트 계약 거래: 브라우징, 시리즈, 이벤트, 마켓 (조회); 주문 생성, 수정, 취소, 체결 (프라이빗). 의미론적 결과 값 (Semantic outcome values): UP/YES/DOWN/NO	→
earn	24	Simple Earn: 잔고, 구매, 상환, 대출 이율 (lending rate), 정기 상품 조회, 정기 주문 (10개). 온체인 스테이킹/DeFi (6개). 이중 통화 예금 (Dual Currency Deposit/双币赢) (6개). 플래시 언 (Flash Earn) (1개). 하위 모듈: earn.savings, earn.onchain, earn.dcd, earn.flash. all에 포함됨.	→
bot	10	트레이딩 봇: 그리드 (Grid) (5개) 및 DCA — 현물 및 계약 (Spot & Contract) (5개).

하위 모듈: bot.grid, bot.dca |
→ |
news |
7 | 암호화폐 뉴스 (Crypto news): 최신 뉴스, 코인별 필터링, 전체 텍스트 검색, 기사 상세 정보, 뉴스 출처, 코인 심리 (스냅샷 + 트렌드) |
→ |
smartmoney |
10 | 스마트 머니 분석 (Smart money analytics): 리더보드 순위, 트레이더 성과 / 포지션 / 포지션 히스토리 / 주문 히스토리, 상위 코인 시그널, 단일 자산 시그널 (코인별 / 트레이더별), 시그널 히스토리 (코인별 / 트레이더별) — 모두 읽기 전용이며, AI 에이전트의 모호성 해소 (disambiguation)를 위해 진입 모드별로 구분됨 |

사전 요구 사항 (Prerequisites): Node.js >= 18

# 1. 설치 (Install)
npm install -g @okx_ai/okx-trade-mcp @okx_ai/okx-trade-cli
# 2. OKX API 인증 정보 설정 (대화형 위저드)
...

대안: 한 줄 설치 스크립트 — Node.js 확인, 설치 및 클라이언트 감지를 자동으로 처리합니다. 라이브 트레이딩, 다중 프로필 또는 기타 클라이언트를 사용하려면 설정(configuration) →를 참조하세요.

okx-trade-mcp # 기본값: 현물 (spot), 스왑 (swap), 계정 (account)
okx-trade-mcp --modules market # 시장 데이터 전용 (인증 불필요)
okx-trade-mcp --modules spot,account # 현물 트레이딩 + 계정
...

시작 시나리오 (Startup scenarios) → — VS Code · Windsurf →

okx market ticker BTC-USDT
okx spot place --instId BTC-USDT --side buy --ordType market --sz 100
okx account balance

명명 규칙 참고 — CLI 하위 명령(subcommands)은 공백을 사용합니다 (okx swap algo place). AI 에이전트는 언더스코어(_)로 연결된 MCP 도구 이름(swap_place_algo_order) 아래에서 동일한 기능을 확인합니다. MCP 식별자를 하이픈(-)으로 연결된 CLI 명령으로 변환하지 마세요 — okx swap place-algo는 유효하지 않습니다. CLI 참조 · CLI vs MCP 도구 이름(CLI vs MCP tool names)을 참조하세요.

AI 에이전트 프레임워크를 위한 사전 구축된 스킬 파일(Pre-built skill files)이 skills/ 디렉토리에 포함되어 있습니다. 각 스킬은 에이전트에게 특정 작업 카테고리에 대해 언제 활성화하고 어떻게 okx CLI를 사용하는지 알려줍니다.

스킬 (Skill)	설명 (Description)	인증 (Auth)
okx-cex-market	시장 데이터: 가격, 캔들 (Candles), 오더북 (Order books), 펀딩 레이트 (Funding rates), 기술적 지표 (Technical indicators)	아니요
okx-cex-trade	주문 관리: 현물 (Spot), 스왑 (Swap), 선물 (Futures), 옵션 (Options), 알고리즘 주문 (Algo orders)	예
okx-cex-portfolio	계정: 잔고 (Balances), 포지션 (Positions), 손익 (P&L), 이체 (Transfers)	예
okx-cex-bot	트레이딩 봇: 그리드 (Grid) 및 DCA (현물 및 계약)	예
okx-cex-earn	Earn: Simple Earn, 온체인 스테이킹 (On-chain staking), 이중 투자 (Dual Investment), AutoEarn	예
okx-cex-smartmoney	Smart Money: 트레이더 리더보드 (Trader leaderboard), 컨센서스 시그널 (Consensus signals), 포지션 분석 (Position analysis)	예

도구 호출 (Tool call) 또는 CLI 명령이 실패하는 경우, 이슈 (Issue)를 생성하고 전체 에러 출력 내용을 포함해 주세요.

MCP — 사용 중인 AI 클라이언트에서 표시되는 구조화된 에러 블록을 복사하세요:

{
"tool": "swap_place_order",
"error": true,
...

CLI — 전체 stderr 출력을 붙여넣으세요:

Error: Order quantity invalid
TraceId: abc123def456
Hint: Check order size against instrument minSz.
...

일반적인 문제는 **FAQ →**를 참조하세요.

git clone https://github.com/okx/agent-tradekit.git && cd okx-trade-mcp
pnpm install && pnpm build

전체 개발 가이드는 CONTRIBUTING.md를 참조하세요.

packages/
├── core/ # 공유 클라이언트 및 도구 (shared client & tools)
├── mcp/ # MCP 서버 (MCP Server)
...

문서 (Document)	설명 (Description)
Architecture	시스템 설계 및 모듈 개요
...