krx-rs

KRX(한국거래소) Open API를 위한 현대적이고 타입 안전한 Rust 클라이언트 라이브러리입니다.

API 인증키를 발급 받아야합니다. 시작하기 참고.

데이터 제공 범위 안내

중요: KRX Open API는 **2010년 이후부터 조회일 기준 전일(T-1)**까지의 데이터만 제공합니다. 라이브러리를 통해 당일 데이터를 조회할 수 없으니 이용에 참고 부탁드립니다.

특징

• 🦀 타입 안전성: Rust의 강력한 타입 시스템을 활용한 안전한 API
• ⚡ 비동기 지원: Tokio 기반의 완전한 비동기 지원
• 🏗️ 빌더 패턴: 직관적이고 유연한 API 구성
• 📊 Polars 통합: DataFrame으로 즉시 사용 가능한 데이터 제공
• 🎯 명확한 오류 처리: 상세한 오류 타입과 컨텍스트 제공
• 📝 구조화된 로깅: tracing을 통한 모니터링 및 디버깅 지원

설치

Cargo.toml에 다음을 추가하세요:

[dependencies]
krx-rs = "0.1.0"

빠른 시작

use krx_rs::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new("your_auth_key");
    
    // 특정 날짜의 데이터 조회
    let data_by_date = client
        .stock()
        .kospi_daily()
        .date("20240105")
        .fetch()
        .await?;
    println!("20240105 데이터:\\n{}", data_by_date);

    // 가장 최신(전일) 데이터 조회
    let latest_data = client
        .stock()
        .kospi_daily()
        .latest()
        .fetch()
        .await?;
    println!("가장 최신 데이터:\\n{}", latest_data);
        
    Ok(())
}

주요 API

주식 (Stock)

// KOSPI 일별 시세
let kospi_daily = client.stock().kospi_daily().today().fetch().await?;

// KOSDAQ 종목 기본정보
let kosdaq_info = client.stock().kosdaq_base_info().fetch().await?;

지수 (Index)

// KRX 지수
let krx_index = client.index().krx_daily().date("20240105").fetch().await?;

// KOSPI 지수
let kospi_index = client.index().kospi_daily().today().fetch().await?;

채권 (Bond)

// 국채 전문시장
let treasury = client.bond().kts_daily().today().fetch().await?;

ETP (ETF/ETN/ELW)

// ETF 일별 시세
let etf = client.etp().etf_daily().date("20240105").fetch().await?;

파생상품 (Derivatives)

// 선물 일별 시세
let futures = client.derivative().futures_daily().today().fetch().await?;

일반상품 (General)

// 유가 정보
let oil = client.general().oil_daily().today().fetch().await?;

ESG

// SRI 채권 정보
let sri_bonds = client.esg().sri_bond_info().fetch().await?;

고급 기능

로깅 설정

use krx_rs::{Client, logging::LoggingConfig};

let logging_config = LoggingConfig {
    level: "debug".to_string(),
    json_format: false,
    filter_sensitive: true,
    file_path: Some("krx.log".to_string()),
};

let client = Client::builder()
    .auth_key("your_auth_key")
    .logging(logging_config)
    .build()?;

사용자 정의 설정

use std::time::Duration;

let client = Client::builder()
    .auth_key("your_auth_key")
    .timeout(Duration::from_secs(60))
    .user_agent("MyApp/1.0")
    .build()?;

데이터 처리

모든 API 응답은 Polars DataFrame으로 반환됩니다:

let df = client.stock().kospi_daily().today().fetch().await?;

// DataFrame 작업
let filtered = df.lazy()
    .filter(col("등락률").gt(lit(2.0)))
    .select([col("종목명"), col("종가"), col("등락률")])
    .sort("등락률", SortOptions::default().with_order_descending(true))
    .collect()?;

예제

더 많은 예제는 examples 디렉토리를 참조하세요:

• simple_fetch.rs - 기본 데이터 조회
• with_logging.rs - 로깅 설정 예제

API 문서

전체 API 문서는 docs.rs에서 확인할 수 있습니다.

요구사항

• Rust 1.75.0 이상
• KRX Open API 인증키 (신청하기)

라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

기여

기여를 환영합니다! 이슈나 풀 리퀘스트를 자유롭게 제출해주세요.

참고

이 라이브러리는 KRX(한국거래소)와 공식적으로 제휴하거나 승인받은 것이 아닙니다.