시작하기
처음 API를 접하는 분도 괜찮아요.
개발환경 세팅 → API 키 발급 → 첫 호출까지, 세 단계를 순서대로 따라오면 첫 응답을 직접 확인할 수 있어요.
개발환경 세팅
API를 호출하려면 코드를 실행할 환경이 필요해요. 이 가이드는 가장 진입장벽이 낮고 자료가 많은 Python + VS Code 조합을 기준으로 설명해요. 이미 개발 환경이 갖춰져 있다면 2단계 토큰 발급으로 건너뛰세요.
1-1Python 설치
python.org에서 최신 버전 다운로드를 해주세요. 설치 시 반드시 "Add Python to PATH" 체크박스를 선택하세요. 이 옵션이 없으면 터미널에서 python 명령이 동작하지 않아요.
자주 하는 실수: "Add Python to PATH" 미체크 시 python: command not found 오류가 나요. 이미 설치했다면 제거 후 재설치가 필요해요.
설치 완료 후 아래 명령으로 정상 설치됐는지 확인하세요.
python --version # Python 3.11.x ← 이렇게 나오면 성공 pip --version # pip 23.x.x from ... ← pip도 함께 확인
1-2VS Code 설치 및 Python 확장 추가
코드 편집기는 어떤 것이든 괜찮지만, VS Code는 무료이고 Python 자동완성·오류 감지 기능이 뛰어나 추천해요.
VS Code 다운로드code.visualstudio.com 추천 에디터VS Code 설치 후 Python 확장을 추가해야 자동완성이 동작해요.
- VS Code 설치 완료
- Extensions에서 Python (Microsoft) 설치
- Ctrl+Shift+P → "Python: Select Interpreter"로 설치한 Python 버전 선택
1-3필수 라이브러리 설치
LS증권 OPEN API 호출에 필요한 Python 라이브러리를 설치하고 터미널(VS Code 내 터미널 포함)에서 아래 명령을 실행하세요.
# HTTP 요청용 pip install requests # WebSocket 실시간 데이터용 pip install websocket-client # (선택) 데이터 가공용 pip install pandas
설치 후 Successfully installed requests-x.x.x 메시지가 나오면 완료돼요.
1-4개발환경 최종 확인
아래 코드를 실행해 라이브러리가 정상 설치됐는지 확인하세요. VS Code에서 새 파일을 만들고 check_env.py로 저장 후 실행하세요.
import requests, websocket, sys print(f"Python : {sys.version}") print(f"requests: {requests.__version__}") print(f"ws-client: {websocket.__version__}") print("✅ 개발환경 준비 완료!")
인증토큰 발급
이용안내에서 발급받은 APP_KEY와 APP_SECRET을 사용해 Access Token을 발급하세요. 모든 API 호출 시 이 토큰을 헤더에 포함해야해요.
2-1APP_KEY · APP_SECRET 확인
이용안내에서 신청한 뒤, 고객센터 → 매매시스템 → API → 사용등록/해지 화면에서 계좌번호·계좌비밀번호로 조회하면 발급된 앱키·시크릿키를 언제든 확인할 수 있어요.
앱키와 시크릿키는 유출 및 도용되지 않도록 관리하여야 하며, 유출이나 도용된 경우 OPEN API 신청페이지에서 '사용해지'후 재등록해 주세요. 이 경우 기존 발금된 토큰은 만료돼요.
2-2Access Token 발급 코드
아래 코드에서 YOUR_APP_KEY와 YOUR_APP_SECRET을 실제 값으로 교체한 뒤 실행하세요.
import requests # ① 발급받은 키를 여기에 입력하세요. APP_KEY = "YOUR_APP_KEY" APP_SECRET = "YOUR_APP_SECRET" # ② 토큰 발급 요청 url = "https://openapi.ls-sec.co.kr:8080/oauth2/token" data = { "grant_type": "client_credentials", "appkey": APP_KEY, "appsecretkey": APP_SECRET, "scope": "oob", } res = requests.post(url, data=data) # ③ 토큰 확인 token = res.json()["access_token"] print(f"✅ Token: {token[:30]}...")
curl -X POST "https://openapi.ls-sec.co.kr:8080/oauth2/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials" \ -d "appkey=YOUR_APP_KEY" \ -d "appsecretkey=YOUR_APP_SECRET" \ -d "scope=oob"
const body = new URLSearchParams({ grant_type: "client_credentials", appkey: "YOUR_APP_KEY", appsecretkey: "YOUR_APP_SECRET", scope: "oob", }); const res = await fetch("https://openapi.ls-sec.co.kr:8080/oauth2/token", { method: "POST", body, }); const { access_token } = await res.json(); console.log("✅ Token:", access_token.slice(0, 30));
성공 시 아래와 같은 응답이 반환돼요.
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 86400 // 24시간
}첫 API 호출 — 시세 조회·주문·잔고
이제 실제 API호출이 가능해요. 가장 기본이 되는 세 가지 시세 조회 / 주문 / 잔고 확인 순서로 진행하세요.
3-1주식 현재가 조회
삼성전자(005930)의 현재가를 조회하세요. GET 방식으로 호출하며, 헤더에 발급한 토큰을 포함해요.
import requests TOKEN = "YOUR_ACCESS_TOKEN" # 2단계에서 발급 STOCK = "005930" # 삼성전자 headers = { "Authorization": f"Bearer {TOKEN}", "tr_id": "STKCURR" } params = {"shcode": STOCK} res = requests.get( "https://openapi.ls-sec.co.kr:8080/stock/market-data", headers=headers, params=params ) data = res.json() print(f"종목명 : {data['hname']}") print(f"현재가 : {data['price']:,}원") print(f"등락률 : {data['chgrate']}%")
3-2주식 매수 주문
실제 자금이 사용되므로 처음에는 반드시 모의투자 토큰으로 테스트하세요. tr_id 값이 실전/모의를 구분해요.
주의: 실전투자 토큰으로 호출하면 실제 주문이 체결됩니다. 반드시 CSPAT00101 (모의) / CSPAT00601 (실전) tr_id를 구분하세요.
import requests, json TOKEN = "YOUR_ACCESS_TOKEN" ACCTNO = "YOUR_ACCOUNT_NO" # 계좌번호 headers = { "Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json", "tr_id": "CSPAT00101" # 모의투자 매수 } body = { "CANO": ACCTNO, "shcode": "005930", # 삼성전자 "qty": "1", # 수량 "price": "0", # 시장가 (0) "hogagb": "03" # 03: 시장가 } res = requests.post( "https://openapi.ls-sec.co.kr:8080/stock/order", headers=headers, data=json.dumps(body) ) print(res.json())
3-3잔고 조회
주문 후 보유 종목과 평가금액을 확인하세요.
import requests TOKEN = "YOUR_ACCESS_TOKEN" ACCTNO = "YOUR_ACCOUNT_NO" headers = { "Authorization": f"Bearer {TOKEN}", "tr_id": "CSPAQ12300" } params = {"CANO": ACCTNO} res = requests.get( "https://openapi.ls-sec.co.kr:8080/stock/balance", headers=headers, params=params ) holdings = res.json().get("output1", []) for item in holdings: print(f"{item['hname']:10} {int(item['qty']):>5}주 평가: {int(item['evamt']):>12,}원")
3-4WebSocket 연결 및 구독 등록
Websocket으로 연결해 실시간 뉴스(NWS)를 구독하세요. 구독 등록 메시지를 전송하면 신규 뉴스가 푸시로 수신돼요.
import websocket, json TOKEN = "YOUR_ACCESS_TOKEN" ws = websocket.create_connection("wss://openapi.ls-sec.co.kr:9443/websocket") # 실시간 뉴스(NWS) 구독 등록 sub = { "header": {"token": TOKEN, "tr_type": "3"}, "body": {"tr_cd": "NWS", "tr_key": "NWS001"} } ws.send(json.dumps(sub)) while True: print(ws.recv())
