토스증권 Open API 시작하기 1~5편 정리, Python 자동매매 입문 로드맵
토스증권 Open API 시리즈를 5편까지 작성하면서 처음 목표는 꽤 단순했습니다.
API 문서를 읽고, Python 코드로 직접 호출해보고, 반복되는 부분을 SDK처럼 묶어보자.
그런데 막상 하나씩 구현해보니 생각보다 중요한 포인트가 많았습니다. 인증 토큰을 어떻게 관리할지, 계좌 정보는 언제 조회해야 하는지, 주문을 넣은 뒤에는 무엇을 확인해야 하는지, 그리고 자동매매 코드에서 가장 위험한 부분은 어디인지가 계속 따라왔습니다.
이 글은 Tistory에 먼저 올린 토스증권 Open API 시작하기 1~5편을 GitHub Pages용으로 다시 정리한 글입니다. 전체 흐름을 먼저 보고 싶은 분이라면 이 글을 먼저 읽고, 필요한 편부터 따라가면 좋습니다.
1. API 호출보다 인증 구조가 먼저였다
1편에서는 토스증권 Open API를 사용하기 위한 기본 흐름을 정리했습니다.
처음 API를 다룰 때는 endpoint나 request body부터 보고 싶어집니다. 하지만 실제로는 그보다 먼저 인증 구조를 이해해야 합니다. 토스증권 Open API도 client_id, client_secret을 이용해 Access Token을 발급받고, 이후 요청마다 토큰을 넣는 흐름으로 동작합니다.
여기서 중요한 건 “요청 한 번 성공”이 아닙니다.
토큰 발급, 토큰 저장, 만료 전 갱신, 실패 시 재시도 흐름을 처음부터 분리해두는 것이 이후 자동매매 코드의 출발점입니다.
자동매매 프로그램은 장중에 오래 실행될 수 있습니다. 토큰 만료나 네트워크 오류가 중간에 생길 수 있으니, 인증 코드는 예제 파일 안에 대충 붙여두기보다 별도 계층으로 빼는 편이 좋았습니다.
2. 계좌 조회는 주문의 사전 점검이다
2편에서는 계좌 조회와 계좌 순번 처리를 다뤘습니다.
주문 API를 호출하려면 종목코드와 수량만 있으면 되는 것이 아닙니다. 실제 주문은 특정 계좌를 대상으로 들어가기 때문에 계좌 정보가 필요합니다. 토스증권 Open API에서는 주문 요청에 X-Tossinvest-Account 헤더가 들어갑니다.
처음에는 계좌 순번을 직접 적어도 될 것처럼 보였습니다. 하지만 자동매매 프로그램에서는 이 값을 코드에 박아두는 방식이 불안했습니다.
from tossinvestsdk import TossClient
client = TossClient()
accounts = client.account.list()
portfolio = client.account.portfolio()
buying_power = client.account.buying_power_kr()
계좌 조회는 단순한 부가 기능이 아닙니다. 주문 전 매수 가능 금액, 보유 수량, 미체결 주문을 확인하기 위한 기반입니다.
3. 주문은 넣는 것보다 끝까지 확인하는 것이 중요했다
3편과 4편에서는 주문 생성, 주문 조회, 정정, 취소 흐름을 구현했습니다.
처음 주문 API를 보면 “매수 주문을 어떻게 넣는가”에 시선이 갑니다. 하지만 실제로 구현하다 보면 더 중요한 건 주문 이후입니다.
| 확인할 것 | 이유 |
|---|---|
| 주문 접수 여부 | 요청 성공과 접수 성공은 다를 수 있음 |
| 체결 여부 | 접수 후 미체결 상태가 남을 수 있음 |
| 일부 체결 | 수량 전체가 바로 체결되지 않을 수 있음 |
| 취소/정정 결과 | 주문 ID와 상태 추적이 필요함 |
| 중복 주문 | 응답 지연 때 가장 조심해야 하는 부분 |
자동매매에서는 주문 요청이 성공했다고 해서 매매가 끝난 것이 아닙니다.
order = client.order.buy_market(
symbol="005930",
quantity=1,
)
filled = client.order.wait_until_filled(
order.order_id,
timeout=30,
interval=0.5,
)
특히 실거래에서는 중복 주문이 가장 무섭습니다. 네트워크가 느려졌거나 응답을 놓쳤을 때 같은 주문을 다시 넣으면, 의도보다 많은 수량이 체결될 수 있습니다. 그래서 안정적인 clientOrderId, 미체결 주문 조회, 체결 대기 로직이 자동매매 코드에서 꽤 중요한 축이 됩니다.
4. 5편에서 자동매매다운 첫 조건문을 만들었다
5편에서는 조금 더 자동매매다운 코드로 넘어갔습니다.
목표는 단순했습니다.
삼성전자가 60,000원 이하이면 1주 매수한다.
전략이라고 부르기엔 작아 보이지만, 자동매매의 시작은 대부분 이런 조건문입니다.
from decimal import Decimal
from tossinvestsdk import TossClient
client = TossClient()
price = client.market.price("005930").get("005930")
if price.last_price <= Decimal("60000"):
order = client.order.buy_market(
symbol="005930",
quantity=1,
)
다만 이 코드는 한 번만 가격을 확인합니다. 실제로는 원하는 가격이 올 때까지 반복해서 현재가를 확인해야 하고, 주문이 들어간 뒤에는 체결 여부도 봐야 합니다.
그래서 가격 조건을 기다리는 기능을 wait_until_price() 같은 형태로 분리했습니다.
price = client.strategy.wait_until_price(
symbol="005930",
target_price=60000,
operator="<=",
timeout=3600,
interval=1,
)
여기서 중요한 변화는 코드가 짧아진 것보다 책임이 분리되었다는 점입니다.
market: 현재가 조회strategy: 조건 대기order: 주문 생성과 체결 확인account: 주문 전 계좌 상태 확인
5. 1~5편 흐름 요약
| 편 | 주제 | 자동매매에서의 의미 |
|---|---|---|
| 1편 | 인증과 Access Token | API 요청의 출발점 |
| 2편 | 계좌 조회와 계좌 헤더 | 실제 주문 대상 계좌 확인 |
| 3편 | 주문 생성과 체결 조회 | 매수/매도 실행의 기본 |
| 4편 | 주문 정정과 취소 | 미체결 주문 관리 |
| 5편 | 현재가 조건 매수 | 자동매매 전략의 첫 조건문 |
이 흐름을 만들면서 느낀 건, 자동매매는 화려한 전략보다 기본기가 먼저라는 점입니다.
현재가를 읽는 코드가 불안하면 전략도 불안합니다. 주문 체결을 확인하지 않으면 수익률 계산도 흔들립니다. 상태 저장이 없으면 프로그램을 재시작했을 때 어디서부터 이어가야 할지 알 수 없습니다.
6. 실거래 전에 반드시 남겨야 하는 안전장치
블로그에서는 코드가 짧아 보이도록 예제를 줄여서 보여줄 때가 많습니다. 하지만 실제 매매프로그램에서는 아래 조건을 빼면 안 됩니다.
실주문 전에는 매수 가능 금액, 미체결 주문, 주문 수량, 장 시간, 체결 여부를 확인해야 합니다.
특히 새 전략은 처음부터 실주문으로 돌리지 않습니다.
현재 프로젝트 기준으로는 새 주문형 전략은 기본값을 dry_run=True로 두는 방향을 사용합니다. Dry-run에서는 실제 주문을 넣지 않고, 실시간 데이터와 동일한 흐름으로 신호, 가상 체결, 수수료, 포지션, 손익, 로그를 확인합니다.
config = KoreanBluechipDayTradingConfig(
universe_symbols=("005930", "000660"),
trading_capital="1000000",
dry_run=True,
)
실주문은 mock 테스트와 소액 검증을 거친 뒤, 사용자가 명시적으로 dry_run=False를 설정한 경우에만 허용하는 쪽이 안전합니다.
7. 다음 단계
1~5편까지는 REST API 중심의 기초 체력을 만드는 과정이었습니다.
이후에는 현재가 한 번 조회하는 수준에서 벗어나, 캔들 데이터와 실시간 WebSocket 데이터를 붙이게 됩니다. 여기서부터는 단순 조건문보다 상태 관리가 훨씬 중요해집니다.
개인적으로는 이 시리즈의 핵심이 “자동으로 돈 버는 코드”가 아니라, 실수해도 계좌에 큰 문제가 생기지 않도록 프로그램을 차근차근 안전하게 만드는 과정이라고 생각합니다.
자동매매는 결국 코드가 돈과 직접 연결되는 영역입니다. 그래서 화려한 전략보다, 작은 주문 하나를 안전하게 넣고 끝까지 확인하는 습관이 먼저입니다.
Tistory에 올라간 기존 글
- 토스증권 Open API 시작하기 1편
- 토스증권 Open API 시작하기 2편
- 토스증권 Open API 시작하기 3편
- 토스증권 Open API 시작하기 4편
- 토스증권 Open API 시작하기 5편
Leave a comment