OKX CEX 포트폴리오 및 계정 CLI은(는) 무엇을 하나요?
OKX 거래소의 계정 잔고, 포지션, 손익(P&L), 청구서, 수수료 및 자금 이체. API 자격 증명이 필요합니다.
사전 요구 사항
okxCLI 설치:npm install -g @okx_ai/okx-trade-cli- 자격 증명 구성:
또는 환경 변수 설정:okx config initexport OKX_API_KEY=your_key export OKX_SECRET_KEY=your_secret export OKX_PASSPHRASE=your_passphrase - 데모 모드로 테스트:
okx --profile demo account balance
자격 증명 및 프로필 확인
인증된 모든 명령어 전에 이 확인을 실행하세요.
A단계 — 자격 증명 확인
okx config show # 구성 상태 확인 (출력은 마스킹됨)
- 명령어가 오류를 반환하거나 구성이 없는 경우: 모든 작업을 중단하고, 사용자에게
okx config init실행을 안내한 후 설정이 완료될 때까지 기다렸다가 재시도하세요. - 자격 증명이 구성된 경우: B단계로 진행하세요.
B단계 — 프로필 확인 (필수)
--profile은 모든 인증된 명령어에 필수입니다. 프로필을 암시적으로 추가하지 마세요.
| 값 | 모드 | 자금 |
|---|---|---|
live | 실계좌 | 실제 자금 |
demo | 모의계좌 | 시뮬레이션 자금 |
해결 규칙:
- 현재 메시지 의도가 명확한 경우 (예: "실계좌" / "live" →
live; "모의" / "demo" →demo) → 해당 프로필을 사용하고 사용자에게 알림:"--profile live (실계좌) 사용"또는"--profile demo (모의계좌) 사용" - 현재 메시지에 명시적 선언이 없는 경우 → 대화 맥락에서 이전 프로필 확인:
- 발견됨 → 사용하고 사용자에게 알림:
"이전과 동일하게 --profile live (실계좌) 계속 사용" - 발견되지 않음 → 질문:
"실계좌(live) 또는 모의계좌(demo)?"— 답변을 기다린 후 진행
- 발견됨 → 사용하고 사용자에게 알림:
401 인증 오류 처리
명령어가 401 / 인증 오류를 반환하는 경우:
- 즉시 중단 — 동일한 명령어를 재시도하지 마세요
- 사용자에게 알림: "인증 실패(401). API 자격 증명이 유효하지 않거나 만료되었을 수 있습니다."
- 사용자에게 로컬 편집기로 파일을 직접 편집하여 자격 증명을 업데이트하도록 안내:
해당 프로필 아래의~/.okx/config.tomlapi_key,secret_key,passphrase필드를 업데이트하세요. 새 자격 증명을 채팅에 붙여넣지 마십시오. - 사용자가 파일 업데이트를 확인한 후
okx config show를 실행하여 확인 (출력은 마스킹됨) - 그런 다음에만 원래 작업을 다시 시도하세요
모의계좌 vs 실계좌 모드
프로필이 실계좌/모의계좌 전환을 위한 유일한 제어 수단입니다 — 정확히 두 가지 옵션:
--profile | 모드 | 자금 |
|---|---|---|
live | 실계좌 | 실제 자금 |
demo | 모의계좌 | 시뮬레이션 자금 |
okx --profile live account balance # 실계좌
okx --profile demo account balance # 모의계좌 (시뮬레이션 잔고)
규칙:
- 읽기 명령어 (잔고, 포지션, 청구서 등): 어떤 프로필을 사용했는지 항상 명시
- 쓰기 명령어 (
transfer,set-position-mode): 실행 전에 프로필을 반드시 확인해야 함 ("자격 증명 및 프로필 확인" B단계 참조); 특히 이체 시 잘못된 프로필은 잘못된 계정을 의미함 - 명령어 결과마다 반드시
[profile: live]또는[profile: demo]를 응답에 추가 --demo플래그를 사용하지 마십시오 — 대신--profile을 사용하세요
스킬 라우팅
- 시장 데이터 (가격, 차트, 호가, 펀딩 비율) →
okx-cex-market사용 - 계정 잔고, 손익, 포지션, 수수료, 이체 →
okx-cex-portfolio(이 스킬) 사용 - 일반 현물/스왑/선물/알고리즘 주문 →
okx-cex-trade사용 - 그리드 및 DCA 트레이딩 봇 →
okx-cex-bot사용
빠른 시작
# 거래 계정 잔고 (잔고 > 0인 모든 통화)
okx account balance
# USDT 잔고만 확인
okx account balance USDT
# 자금 계정 잔고
okx account asset-balance
# 모든 미체결 포지션
okx account positions
# 청산된 포지션 내역 및 실현 손익
okx account positions-history
# 최근 계정 청구서 (최근 100개)
okx account bills
# 내 거래 수수료 등급
okx account fees --instType SPOT
# 자금 계정(18)에서 거래 계정(6)으로 100 USDT 이체
okx account transfer --ccy USDT --amt 100 --from 18 --to 6
명령어 색인
읽기 명령어
| # | 명령어 | 유형 | 설명 |
|---|---|---|---|
| 1 | okx account balance [ccy] | READ | 거래 계정 자기자본, 사용 가능, 동결 |
| 2 | okx account asset-balance [ccy] | READ | 자금 계정 잔고 |
| 3 | okx account positions | READ | 미체결 계약/스왑 포지션 |
| 4 | okx account positions-history | READ | 청산된 포지션 + 실현 손익 |
| 5 | okx account bills | READ | 계정 원장 (입금, 출금, 거래) |
| 6 | okx account fees --instType <type> | READ | 내 거래 수수료 등급 (메이커/테이커) |
| 7 | okx account config | READ | 계정 레벨, 포지션 모드, UID |
| 8 | okx account max-size --instId <id> --tdMode <mode> | READ | 현재 가격 기준 최대 매수/매도 수량 |
| 9 | okx account max-avail-size --instId <id> --tdMode <mode> | READ | 다음 주문에 사용 가능한 수량 |
| 10 | okx account max-withdrawal [ccy] | READ | 통화별 최대 출금 가능 금액 |
쓰기 명령어
| # | 명령어 | 유형 | 설명 |
|---|---|---|---|
| 11 | okx account set-position-mode <mode> | WRITE | 순방향/헤지 포지션 모드 전환 |
| 12 | okx account transfer | WRITE | 계정 간 자금 이체 |
스킬 간 워크플로우
거래 전 잔고 확인
사용자: "0.1 BTC를 사고 싶은데, USDT가 충분한가요?"
1. okx-cex-portfolio okx account balance USDT → 사용 가능한 자기자본 확인
2. okx-cex-market okx market ticker BTC-USDT → 현재 가격 확인
↓ 사용자 승인
3. okx-cex-trade okx spot place --instId BTC-USDT --side buy --ordType market --sz 0.1
봇 시작 전 잔고 확인
사용자: "1000 USDT로 BTC 그리드 봇을 시작하고 싶습니다"
1. okx-cex-portfolio okx account balance USDT → 사용 가능 자금 ≥ 1000 확인
2. okx-cex-market okx market candles BTC-USDT --bar 4H --limit 50 → 가격 범위 결정
↓ 사용자 승인
3. okx-cex-bot okx bot grid create --instId BTC-USDT --algoOrdType grid \
--minPx 90000 --maxPx 100000 --gridNum 10 --quoteSz 1000
미체결 포지션 및 손익 검토
사용자: "현재 포지션과 성과를 보여주세요"
1. okx-cex-portfolio okx account positions → 미실현 손익이 포함된 미체결 포지션
2. okx-cex-portfolio okx account positions-history → 최근 청산된 포지션
3. okx-cex-market okx market ticker BTC-USDT-SWAP → 현재 가격 대비 진입 가격 확인
이체 및 거래
사용자: "자금 계정에서 500 USDT를 거래 계정으로 옮겨서 BTC를 거래하세요"
1. okx-cex-portfolio okx account asset-balance USDT → 자금 잔고 ≥ 500 확인
↓ 사용자 승인
2. okx-cex-portfolio okx account transfer --ccy USDT --amt 500 --from 18 --to 6
3. okx-cex-portfolio okx account balance USDT → 거래 잔고 업데이트 확인
↓ 거래 준비 완료
4. okx-cex-trade okx spot place ...
진입 전 최대 포지션 크기 확인
사용자: "교차 마진으로 BTC를 얼마나 살 수 있나요?"
1. okx-cex-portfolio okx account balance → 총 자기자본
2. okx-cex-portfolio okx account max-size --instId BTC-USDT-SWAP --tdMode cross → 최대 매수/매도 수량
3. okx-cex-market okx market ticker BTC-USDT-SWAP → 현재 가격 참고
작동 흐름
0단계 — 자격 증명 및 프로필 확인
인증된 모든 명령어 전:
프로필 결정 (필수):
- 옵션:
live(실계좌) 또는demo(모의계좌) — 정확히 이 두 값
- 현재 메시지 의도가 명확한 경우 (예: "실계좌"/"live" → live; "모의"/"demo" → demo) → 사용하고 사용자에게 알림:
"--profile live (실계좌) 사용" - 현재 메시지에 명시적 선언이 없는 경우 → 대화 맥락에서 이전 프로필 확인:
- 발견됨 → 사용하고 사용자에게 알림:
"이전과 동일하게 --profile live (실계좌) 계속 사용" - 발견되지 않음 → 질문:
"실계좌(live) 또는 모의계좌(demo)?"— 답변을 기다림
- 발견됨 → 사용하고 사용자에게 알림:
자격 증명이 구성되지 않은 경우: 사용자에게 okx config init 실행 안내, 모든 거래 작업 중단
모든 명령어 결과 후: [profile: live] 또는 [profile: demo]를 응답에 추가
1단계: 계정 작업 식별
- 잔고 확인 →
okx account balance(거래) 또는okx account asset-balance(자금) - 미체결 포지션 보기 →
okx account positions - 청산된 포지션 + 손익 보기 →
okx account positions-history - 거래 내역 보기 →
okx account bills - 수수료 등급 확인 →
okx account fees - 계정 설정 확인 →
okx account config - 주문 수량 계산 →
okx account max-size또는okx account max-avail-size - 출금 한도 확인 →
okx account max-withdrawal - 자금 이체 →
okx account transfer - 포지션 모드 변경 →
okx account set-position-mode
2단계: 읽기 명령어 즉시 실행 — 프로필 확인(0단계) 후 쓰기 명령어 실행
읽기 명령어 (1–10): 즉시 실행, 확인 불필요.
ccy필터:USDT,BTC,ETH같은 통화 기호 사용- 수수료/포지션
--instType:SPOT,SWAP,FUTURES,OPTION - 청구서
--archive: 기본 기간을 넘어선 오래된 기록에 접근 - 최대 수량
--tdMode:cash(현물),cross, 또는isolated
쓰기 명령어 (11–12): 실행 전 한 번 확인.
set-position-mode: 모드 확인 (net= 단방향,long_short_mode= 헤지 모드); 전환 시 미체결 포지션에 영향을 줄 수 있음transfer:--ccy,--amt,--from,--to확인 (계정 유형:6=거래,18=자금); 먼저 출금 계정 잔고 확인
3단계: 쓰기 후 확인
set-position-mode후:okx account config실행하여posMode업데이트 확인transfer후:okx account balance및okx account asset-balance실행하여 잔고 업데이트 확인
CLI 명령어 참조
계정 잔고 — 거래 계정
okx account balance [ccy] [--json]
| 매개변수 | 필수 | 기본값 | 설명 |
|---|---|---|---|
ccy | 아니오 | - | 단일 통화로 필터 (예: USDT) |
반환 테이블: currency, equity, available, frozen. 잔고 > 0인 통화만 표시.
자산 잔고 — 자금 계정
okx account asset-balance [ccy] [--json]
| 매개변수 | 필수 | 기본값 | 설명 |
|---|---|---|---|
ccy | 아니오 | - | 단일 통화로 필터 |
반환: ccy, bal, availBal, frozenBal. 잔고 > 0인 통화만 표시.
포지션 — 미체결 포지션
okx account positions [--instType <type>] [--instId <id>] [--json]
| 매개변수 | 필수 | 기본값 | 설명 |
|---|---|---|---|
--instType | 아니오 | - | 필터: SWAP, FUTURES, OPTION |
--instId | 아니오 | - | 특정 상품으로 필터 |
반환: instId, instType, side (posSide), pos, avgPx, upl (미실현 손익), lever. 수량 ≠ 0인 포지션만 표시.
포지션 내역 — 청산된 포지션
okx account positions-history [--instType <type>] [--instId <id>] [--limit <n>] [--json]
반환: instId, direction, openAvgPx, closeAvgPx, realizedPnl, uTime.
청구서 — 계정 원장
okx account bills [--archive] [--instType <type>] [--ccy <ccy>] [--limit <n>] [--json]
| 매개변수 | 필수 | 기본값 | 설명 |
|---|---|---|---|
--archive | 아니오 | false | 오래된 기록 접근 (보관 엔드포인트) |
--instType | 아니오 | - | 상품 유형별 필터 |
--ccy | 아니오 | - | 통화별 필터 |
--limit | 아니오 | 100 | 레코드 수 |
반환: billId, instId, type, ccy, balChg, bal, ts.
수수료 — 거래 수수료 등급
okx account fees --instType <type> [--instId <id>] [--json]
| 매개변수 | 필수 | 기본값 | 설명 |
|---|---|---|---|
--instType | 예 | - | SPOT, SWAP, FUTURES, OPTION |
--instId | 아니오 | - | 특정 상품 (선택 사항) |
반환: level, maker, taker, makerU, takerU, ts.
설정 — 계정 구성
okx account config [--json]
반환: uid, acctLv (계정 레벨), posMode (net/long_short_mode), autoLoan, greeksType, level, levelTmp.
최대 수량 — 최대 주문 수량
okx account max-size --instId <id> --tdMode <mode> [--px <price>] [--json]
| 매개변수 | 필수 | 기본값 | 설명 |
|---|---|---|---|
--instId | 예 | - | 상품 ID |
--tdMode | 예 | - | cash (현물), cross, 또는 isolated |
--px | 아니오 | - | 기준 가격 (생략 시 시장 가격 사용) |
반환: instId, maxBuy, maxSell.
최대 사용 가능 수량
okx account max-avail-size --instId <id> --tdMode <mode> [--json]
반환: instId, availBuy, availSell — 다음 주문에 즉시 사용 가능한 수량.
최대 출금
okx account max-withdrawal [ccy] [--json]
반환 테이블: ccy, maxWd, maxWdEx (대출 포함). 필터가 없으면 모든 통화 표시.
포지션 모드 설정
okx account set-position-mode <net|long_short_mode> [--json]
| 값 | 동작 |
|---|---|
net | 단방향 (기본값) — 롱과 숏이 상쇄됨 |
long_short_mode | 헤지 모드 — 롱과 숏이 공존 가능 |
경고: 포지션이 열려 있는 상태에서 모드를 전환하면 예기치 않은 동작이 발생할 수 있습니다. 먼저
okx account positions를 확인하세요.
자금 이체
okx account transfer --ccy <ccy> --amt <n> --from <acctType> --to <acctType> \
[--transferType <type>] [--subAcct <name>] [--json]
| 매개변수 | 필수 | 기본값 | 설명 |
|---|---|---|---|
--ccy | 예 | - | 이체할 통화 (예: USDT) |
--amt | 예 | - | 이체할 금액 |
--from | 예 | - | 출금 계정 유형: 6=거래, 18=자금 |
--to | 예 | - | 입금 계정 유형: 6=거래, 18=자금 |
--transferType | 아니오 | 0 | 0=계정 내, 1=하위 계정으로, 2=하위 계정에서 |
--subAcct | 아니오 | - | 하위 계정 이름 (하위 계정 이체 시 필수) |
반환: transId, ccy, amt.
MCP 도구 참조
| 도구 | 설명 |
|---|---|
account_get_balance | 거래 계정 잔고 |
account_get_asset_balance | 자금 계정 잔고 |
account_get_positions | 미체결 포지션 |
account_get_positions_history | 청산된 포지션 내역 |
account_get_bills | 계정 청구서 |
account_get_fees | 거래 수수료 등급 |
account_get_config | 계정 구성 |
account_get_max_size | 최대 주문 수량 |
account_get_max_avail_size | 최대 사용 가능 수량 |
account_get_max_withdrawal | 최대 출금 금액 |
account_set_position_mode | 포지션 모드 설정 |
account_transfer | 자금 이체 |
참고
- 이 스킬은 OKX 공식 CLI 도구(
@okx_ai/okx-trade-cli)를 사용합니다. - 실계좌 모드에서는 실제 자금이 사용되므로 주의하세요.
- 모든 쓰기 작업은 실행 전 반드시 사용자 확인을 받아야 합니다.