koreasecurities

README

krsec

한국 증권사 REST API 통합 게이트웨이. 증권사마다 다른 인증, 파라미터, 응답 구조를 broker.Broker 인터페이스 하나로 통일합니다.

지원 증권사

증권사	상태
한국투자증권 (KIS)	✅
키움증권	✅
LS증권	예정

설치

go install github.com/smallfish06/krsec/cmd/krsec@latest

바이너리: Releases

설정

cp config.example.yaml config.yaml

server:
  port: 8080

accounts:
  - name: "main"
    broker: kis
    sandbox: true
    app_key: "YOUR_APP_KEY"
    app_secret: "YOUR_APP_SECRET"
    account_id: "12345678-01"

실행

krsec -config config.yaml

API

Method	Path	설명
POST	/kis/<documented-uapi-path>	KIS 문서 스펙에 등록된 정적 엔드포인트 호출 (/uapi prefix 제외 경로)
POST	/kiwoom/{path...}	Kiwoom 엔드포인트 호출 (/api 경로 + api_id를 구현/문서 스냅샷 기반 generated 매핑(비웹소켓 REST))
GET	/quotes/{market}/{symbol}	현재가
GET	/quotes/{market}/{symbol}/ohlcv	일봉
GET	/instruments/{market}/{symbol}	종목 정보
GET	/accounts/{id}/balance	잔고
GET	/accounts/{id}/positions	포지션
GET	/accounts/summary	멀티계좌 통합 잔고
POST	/accounts/{account_id}/orders	주문
GET	/accounts/{account_id}/orders/{id}	주문 상태
GET	/accounts/{account_id}/orders/{id}/fills	체결내역
PUT	/accounts/{account_id}/orders/{id}	주문 정정
DELETE	/accounts/{account_id}/orders/{id}	주문 취소
GET	/swagger/	Swagger UI

curl http://localhost:8080/quotes/KRX/005930

{"ok": true, "data": {"symbol": "005930", "price": 70000, ...}, "broker": "KIS"}

curl -X POST http://localhost:8080/kis/overseas-price/v1/quotations/price \
  -H "Content-Type: application/json" \
  -d '{
    "tr_id": "HHDFS00000300",
    "params": {
      "AUTH": "",
      "EXCD": "NAS",
      "SYMB": "AAPL"
    }
  }'

라이브러리로 사용

import (
    "github.com/smallfish06/krsec/pkg/broker"
    apiserver "github.com/smallfish06/krsec/pkg/server"
)

srv := apiserver.New(apiserver.Options{
    Port: 8080,
    Accounts: []apiserver.Account{{ID: "acc-1", Name: "Main", Broker: "custom"}},
    Brokers:  map[string]broker.Broker{"acc-1": myBroker},
})
srv.Run()

문서 스펙 generated 타입은 pkg/*/specs에서 바로 사용할 수 있습니다.

import (
    "context"
    "net/http"

    "github.com/smallfish06/krsec/pkg/kis"
    kisspecs "github.com/smallfish06/krsec/pkg/kis/specs"
)

req := &kisspecs.KISOverseasPriceV1QuotationsPriceRequest{
    AUTH: "",
    EXCD: "NAS",
    SYMB: "AAPL",
}

resp, err := adapter.CallEndpoint(
    context.Background(),
    http.MethodGet,
    "/uapi/overseas-price/v1/quotations/price",
    "HHDFS00000300",
    req,
)
_ = resp // typed documented response object
_ = err

구조

cmd/krsec/        서버
pkg/broker/           공개 인터페이스
pkg/server/           임베드 가능한 HTTP 서버
pkg/kis/specs/        KIS documented endpoint generated 타입/스펙
pkg/kiwoom/specs/     Kiwoom documented endpoint generated 타입/스펙
internal/kis/         KIS 클라이언트 + 어댑터
internal/kiwoom/      키움 클라이언트 + 어댑터
internal/server/      HTTP 핸들러
examples/             사용 예시

범위

REST API만 지원합니다. WebSocket(실시간 시세, 실시간 체결 등)은 지원 범위에 포함되지 않습니다.

개발

make test      # 테스트
make build     # 빌드
make lint      # lint
make mock      # mock 재생성
make kis-spec-check    # KIS generated spec/type 동기화 확인
make kis-spec-refresh  # KIS 포털 snapshot 갱신 + generated 파일 재생성
make kiwoom-spec-check   # Kiwoom generated spec/type 동기화 확인
make kiwoom-spec-refresh # Kiwoom 포털 snapshot 갱신 + generated 파일 재생성

KIS spec 관리

• KIS 문서 스펙은 pkg/kis/specs/documented_endpoints.json snapshot으로 버전 관리합니다.
• 런타임은 웹사이트를 조회하지 않고, snapshot에서 생성된 코드만 사용합니다.
• CI는 make kis-spec-check로 generated 파일 drift를 차단합니다.

Kiwoom spec 관리

• Kiwoom 문서 스펙은 pkg/kiwoom/specs/documented_endpoints.json snapshot으로 버전 관리합니다.
• 런타임은 웹사이트를 조회하지 않고, snapshot에서 생성된 코드만 사용합니다.
• CI는 make kiwoom-spec-check로 generated 파일 drift를 차단합니다.

License

Apache 2.0

Documentation

Overview

Package koreasecurities provides a unified gateway for Korean securities broker APIs.

This module abstracts away the differences between Korean broker REST APIs (KIS, Kiwoom, LS, etc.) behind a single github.com/smallfish06/krsec/pkg/broker.Broker interface.

Most users will import one of the sub-packages:

• github.com/smallfish06/krsec/pkg/broker — common interface and types
• github.com/smallfish06/krsec/pkg/server — embeddable HTTP server

Or run the standalone server:

krsec -config config.yaml