증권사 API 용어 설명
증권사 API를 이용한 자동매매 프로그램을 만들려고 해. API에 등장하는 모든 용어에 대해 한국어, 영어와 내용을 설명해줘.
o3 pro 요청
3m 18s 동안 이성 처리 완료
아래 내용은 “증권사 API”에서 거의 반드시 마주치게 되는 핵심 용어를 인증 → 계좌 → 시장데이터 → 주문 → 파생상품 → 위험관리
→ 통신∙형식 → 기타 의 8단계로 분류하여 정리한 것입니다.
“모든” 용어라 주장하기엔 API마다 미묘한 차이가 있으므로, 실제 구현 전에는 반드시 해당 증권사의 공식 문서를 교차 검증하시길 권합니다.
| 분류 | 한국어 용어¹ | 영어 원어 | 설명 (회의적 시각 포함) |
|---|---|---|---|
| 1. 인증·보안 (Auth & Security) | |||
| API 키 | API Key | 서버가 누구 인지 대충 판단할 때 쓰는 문자열. 사람이 노출하면 끝장입니다. | |
| 비밀 키 | Secret Key | 서명(HMAC 등)을 만들 때 함께 쓰이는 짝꿍 키. 평문 저장? 말도 안 됩니다. | |
| 액세스 토큰 | Access Token | OAuth 기반 API가 “로그인 상태”를 증명할 때 쓰는 짧은 수명 문자열. 만료 시간을 꼭 | |
| 확인해야 합니다. | |||
| 리프레시 토큰 | Refresh Token | 액세스 토큰 갱신용. 길게 살아남지만 탈취 시 피해도 길어집니다. | |
| 논스 | Nonce | “한 번만 쓰는 숫자”. 재전송 공격을 막겠다고 붙여 두지만, 서버가 제대로 검증 안 하면 허사입니다. | |
| 타임스탬프 | Timestamp | 요청 시각을 밀리초 단위로 넣으라는데, 서버-클라이언트 시계 오차가 크면 어떻게 할 건가요? NTP 동기 필수. | |
| 서명 | Signature | Secret Key 로 해시 만든 값. 문서마다 정렬 규칙이 달라 삽질 포인트 1순위. | |
| 레이트 리밋 | Rate Limit | “분당 60회” 같은 호출 제한. 초과하면 HTTP 429. 우회? 결국 차단당합니다. | |
| 2. 계좌·포트폴리오 | |||
| 계좌 ID | Account ID | 브로커가 부여한 숫자 또는 문자열. 실계좌·모의계좌가 따로일 수도 있습니다. | |
| 계좌 유형 | Account Type | 현금(Cash), 마진(Margin) 등. 마진이면 이자·위험 관리가 갑절로 복잡해집니다. | |
| 잔고 | Balance | 통화별 가용 금액. “체결 대금 미정산분”은 포함? 브로커마다 다릅니다. | |
| 순자산 | Equity | Balance + 미실현 P/L. 가격 지연 데이터로 계산하면 눈속임 숫자입니다. | |
| 매수 가능 금액 | Buying Power | 레버리지 포함 여력. 실제 주문 가능 수량과 100 % 일치 안 하는 경우 많습니다. | |
| 레버리지 | Leverage | 2×, 5× 같은 배율. 적절히 쓰면 효율, 과하면 청산. | |
| 3. 시장 데이터 (Market Data) | |||
| 종목/심벌 | Symbol (Ticker) | “AAPL”, “005930”. 거래소마다 표기가 달라 중복 위험 있습니다. | |
| 거래소 | Exchange | “NYSE”, “KRX”, “NASDAQ”. 일부 API는 코드 체계가 사내 전용이라 혼동 주범. | |
| 호가 | Quote | Bid/Ask/Last. 밀리초마다 변하는데 API는 초 단위로 틱 줄 때도 있습니다. | |
| 매도호가 | Ask | “팔고 싶은 최소가”. Level 2 데이터 없으면 1단계(bbo)만 가져옵니다. | |
| 매수호가 | Bid | “사고 싶은 최대가”. | |
| 스프레드 | Spread | Ask – Bid. 유동성 부족하면 폭이 벌어져 자동매매 체결률 악화. | |
| 체결가 | Last Price | 가장 최근 거래가격. “0” 또는 null 이면 장이 닫힌 겁니다. | |
| 틱 | Tick | 최소 호가 단위 혹은 1건 체결. 브로커마다 표현이 달라 전처리 필요. | |
| 캔들 | Candle/Bar (OHLCV) | Open-High-Low-Close-Volume 묶음. 분봉, 시봉, 일봉 등. 서버 TZ 혼선에 주의. | |
| 레벨2 | Level 2 | 호가 스택(Depth). 지원 안 하는 API도 많습니다. | |
| VWAP | Volume-Weighted Average Price | 체결량 가중 평균. 실시간 계산 여부 확인 필요. | |
| 4. 주문 (Order) | |||
| 주문 ID | Order ID | 증권사 내부 고유값. 일부는 UUID, 일부는 숫자. | |
| 클라이언트 주문 ID | Client Order ID | 사용자가 붙여 보내는 식별자. 중복 시 오류 발생 여부 확인 필수. | |
| 주문 방향 | Side | Buy(매수)/Sell(매도). 공매도는 별도 Flag? 문서 확인하세요. | |
| 수량 | Quantity | 주식은 주(share), 선물은 계약(contract). 소수 허용 여부? ETF 1/1,000단위? | |
| 가격 | Price | 지정가 주문가. 시장가면 null 또는 0. | |
| 주문 유형 | Order Type | Market, Limit, Stop, Stop Limit, Trailing Stop, OCO, Bracket 등. API마다 지원 범위가 다릅니다. | |
| 시간 조건 | Time-in-Force | GTC, IOC, FOK 등. 한·미 증시는 해석이 조금씩 달라 애매합니다. | |
| 주문 상태 | Status | New, Partially Filled, Filled, Canceled, Rejected, Expired. 약간씩 명칭이 달라 매핑 필요. | |
| 체결 | Fill / Execution | 주문이 약정된 건. 부분 체결된 뒤 취소하면 수량 불일치 주의. | |
| 슬리피지 | Slippage | 목표가−실체결가 차이. 자동매매 성과를 좀먹는 주범. | |
| 5. 파생상품·선물 | |||
| 계약 | Contract | 선물·옵션 한 단위. 계약 규모 확인(예: BTC 1 건 = 100 USD)? | |
| 만기 | Expiry | “2025-09-W4” 등. 포맷이 증권사마다 제멋대로입니다. | |
| 행사가 | Strike | 옵션의 권리행사 가격. | |
| 콜/풋 | Call / Put | 옵션 종류. 약어 “C/P”만 쓰기도 하니 파싱 시 주의. | |
| 펀딩 율 | Funding Rate | 무기한 선물 교환 이자. 실시간 변동, API 지연 시 리스크. | |
| 기준 가격 | Mark Price | 강제 청산 계산 기준. 거래소 시장가격과 다를 수 있어 함정. | |
| 6. 위험관리 (Risk Management) | |||
| 손절가 | Stop-Loss | 가격 트리거. 서버-클라이언트 어디서 실행? Broker side가 안전. | |
| 익절가 | Take-Profit | 목표가 트리거. 마찬가지로 서버 실행 여부 확인. | |
| 최대 손실 한도 | Max Drawdown | 전략 중단 기준. API가 제공? 대부분은 로컬 로직 필요. | |
| 유지 증거금 | Maintenance Margin | 밑으로 떨어지면 강제 청산. 계산식이 계약별로 다릅니다. | |
| 청산 | Liquidation | 강제 포지션 종료. API가 미리 경고 주는지? 없다면 자체 모니터링. | |
| VaR | Value-at-Risk | 위험 예측 지표. 브로커 API에서 직접 주는 경우는 드뭅니다. | |
| 7. 통신·형식 (Protocol & Format) | |||
| 엔드포인트 | Endpoint | “/v2/orders” 같은 URL. 버전이 바뀌면 호환성 깨집니다. | |
| 요청 | Request | HTTP Message = Method + Header + Body. REST만 있는 게 아니라 WebSocket도 있습니다. | |
| 응답 | Response | 상태 코드와 JSON/CSV 본문. 예상 스키마와 다르면 바로 예외 처리. | |
| 헤더 | Header | 인증 값, 콘텐츠 형식 등. 대소문자 구분? RFC 2616 참고. | |
| 본문 | Body | 보통 JSON. 키 이름이 snake_case 인지 camelCase 인지 혼재하기도 합니다. | |
| HTTP 메서드 | GET, POST, PUT, DELETE | 일부 API는 “취소”를 POST로 보내고 DELETE 미지원—문서 꼼꼼히. | |
| 상태 코드 | Status Code | 200, 400, 401, 403, 404, 429, 500. 같은 400이라도 Error Code 상세 분기 필수. | |
| 오류 코드 | Error Code | 브로커 사전 정의 숫자/문자열. 문서 외의 ‘숨겨진’ 코드가 튀어 나올 때가 있습니다. | |
| 페이징 | Pagination | limit/offset or cursor. 대량 데이터 수집 시 속도 병목. | |
| 커서 | Cursor | 다음 페이지 토큰. 만료 시간? 명시 안 된 경우 많습니다. | |
| 웹소켓 | WebSocket | 실시간 스트림. 핑/퐁 주기 미확인 시 연결 끊김. | |
| 하트비트 | Heartbeat | 서버가 “살아 있다” 확인용. 누락되면 재연결 트리거. | |
| 8. 기타 | |||
| 샌드박스 | Sandbox Environment | 실거래 이전 테스트 서버. 약식 데이터라 현실 체결 환경과 차이 남. | |
| 프로덕션 | Production Environment | 실제 돈이 오가는 서버. 릴리즈 전 더블체크. | |
| SDK | SDK | 공식·서드파티 라이브러리. 버전 관리 느슨하면 직접 REST 호출이 낫습니다. | |
| 웹훅 | Webhook | 서버→클라이언트 알람. 방화벽/인증 처리 안 하면 먹통. | |
| 콜백 URL | Callback URL | OAuth Redirect URI. HTTPS 안 쓰면 토큰 탈취 위험. | |
| 아이덤포턴시 키 | Idempotency Key | 동일 요청 중복 실행 방지. 지원 안 하면 재시도 로직 주의. | |
| 지연 시간 | Latency | API round-trip 시간. 알고리즘 성과에 직격탄. |
¹대부분 애초에 영어를 그대로 쓰지만, 국내 문서에서 관용적으로 쓰이는 한글 표현을 병기했습니다.
어떻게 활용하실 건가요? (단계별 의문 제기)
-
용어 분석 – 위 표로 팀 내부 용어 정의를 통일하십시오. 설명이 같아도 명칭만 다르면 버그의 씨앗입니다.
-
브로커별 매핑 – 실제 API Field 명을 표준 용어에 매핑해 “어댑터” 레이어를 두는 것이 안전합니다. 각 증권사가
qty,quantity,orderQty식으로 제멋대로 쓰거든요. -
예외/오류 설계 – 문서에 없는 오류 코드가 튀어나올 것을 전제로, 실패 처리 체계를 먼저 만드십시오. “해보니 된다”는 태도는 자동매매에서 폭탄입니다.
-
보안 점검 – API Key 노출, 시계 동기화(NTP), Secret Key 평문 저장 금지 같은 기본부터 확인하시겠습니까?
-
실전 테스트 – Sandbox → 소액 실계좌 → 규모 확장 순으로 진행하십시오. 미체결·부분 체결 시 corner case 가 터지지 않는지 눈으로 확인해야 합니다.
자동매매는 “코드 몇 줄”보다 문서와 위험 관리 가 성공을 결정합니다. 항상 “이 정의가 브로커마다 동일한가?”를 의심하시고, 의심이 풀릴 때까지 실제 호가·체결 데이터로 검증하시기 바랍니다.
궁금한 점이 더 있으시면 언제든 추가로 말씀해 주십시오.