Metadata-Version: 2.4
Name: upbit-utils
Version: 0.1.0
Summary: 업비트 API를 쉽게 사용할 수 있도록 도와주는 유틸리티 모듈
Requires-Python: >=3.13
Requires-Dist: click>=8.1
Requires-Dist: pandas>=2.2
Requires-Dist: pyjwt>=2.10
Requires-Dist: requests>=2.32
Description-Content-Type: text/markdown

# UPBIT_UTILS
업비트 API를 쉽게 사용할 수 있도록 도와주는 모듈

사용법:
```
git clone https://gist.github.com/a9eabe0567c2515bab59370a75e8933f.git upbit_utils
```

## CLI 사용법
패키지를 설치하면 `upbit` 명령으로 사용할 수 있습니다.

```bash
uv sync
uv run upbit --help
```

설치된 환경에서는 바로 실행할 수 있습니다. Python API 예시와 대응되는 CLI 명령은 다음과 같습니다.

```bash
# 매매가능한 모든 코인 목록: upbit.coin_list()
upbit --help
upbit coins
upbit coins --krw

# 특정 코인의 분단위 캔들: upbit.price_minute("KRW-BTC")
upbit candle KRW-BTC
upbit candle KRW-BTC --unit 1 --count 200
upbit candle KRW-BTC --unit 5 --count 100

# 특정 기간동안 분단위 캔들: upbit.price_minute_range(...)
upbit candle-range KRW-BTC --start "2025-11-08" --end "2025-11-09"
upbit candle-range KRW-BTC --start "2025-11-08 00:00:00" --end "2025-11-09 00:00:00" --unit 5

# 특정 코인의 현재가: upbit.price_ticker("KRW-BTC")
upbit price KRW-BTC

# 여러 코인의 현재가: upbit.price_ticker("KRW-BTC,KRW-ETH")
upbit price KRW-BTC,KRW-ETH

# 시장의 전체코인 현재가: upbit.price_ticker()
upbit price
```

계좌/주문 명령은 `UPBIT_ACCESS_KEY`, `UPBIT_SECRET_KEY` 환경 변수가 필요합니다.

```bash
# 잔고 조회: upbit.balance()
upbit balance

# 미체결 목록: upbit.order_list()
upbit orders
upbit orders --market KRW-BTC --state wait

# 최근 체결 주문: upbit.order_list(None, state="done")
upbit orders --state done

# 주문: upbit.order("KRW-BTC", 0.01, 120000000, side="bid")
upbit order KRW-BTC 0.01 120000000 --side bid

# 주문취소: upbit.order_cancel(...)
upbit cancel 20233409-2f48-41e2-9340-eb25029c5777

# 모든 코인에 대해 -3% 손절: upbit.loss_cut(loss=-0.03)
upbit losscut --loss -0.03

# 여러 코인에 대해 손절: upbit.loss_cut(markets=["KRW-BTC", "KRW-ETH"], loss=-0.03)
upbit losscut --markets KRW-BTC,KRW-ETH --loss -0.03
```

`order_closed()`에 직접 대응되는 CLI 명령은 아직 없습니다. 체결 완료 주문은 `upbit orders --state done`, 취소 주문은 `upbit orders --state cancel`로 조회합니다.

주문, 취소, 손절 명령은 실행 전 확인 프롬프트가 표시됩니다.

## Quick Start
```python
import upbit_utils as upbit

# 매매가능한 모든 코인 목록
upbit.coin_list()

# 특정 코인의 분단위 캔들 (200개)
upbit.price_minute('KRW-BTC')

# 특정 기간동안 분단위 캔들
upbit.price_minute_range(market='KRW-BTC', start="2025-11-08", end="2025-11-09")

# 특정 코인의 현재가
upbit.price_ticker('KRW-BTC')

# 여러 코인의 현재가
upbit.price_ticker('KRW-BTC,KRW-ETH')

# 시장의 전체코인(market) 현재가
coins = upbit.coin_list()
price_ticker(','.join(coins['market'].values))

# 주문
order('KRW-BTC', 0.01, 120000000, side='bid') 

# 미체결 목록
upbit.order_list()

# 최근 체결 주문(100개)
upbit.order_list(None, state='done')

# 주문취소
upbit.order_cancel('20233409-2f48-41e2-9340-eb25029c5777')

# 종료 주문 목록 
upbit.order_closed()

# 모든 코인에 대해 -3% 손절
upbit.loss_cut(loss=-0.03)

# 여러 코인에 대해 손절
upbit.loss_cut(markets=['KRW-BTC', 'KRW-ETH'], loss=-0.03)
```

## 상세
coin_list() -> pd.DataFrame
>사용가능한 마켓 코드 목록을 조회합니다

price_minute(market="KRW-BTC", unit=1) -> pd.DataFrame
>분단위 가격 데이터를 가져옵니다
* market: 마켓 코드 (ex. "KRW-BTC")
* unit: 분 단위. 가능한 값 : 1, 3, 5, 10, 15, 30, 60, 240
* count: 캔들 개수(200개까지 요청 가능)

price_minute_range(market="KRW-BTC", start='2025-01-15 00:00:00', end='2025-01-15 23:59:59', unit=5) -> pd.DataFrame
>지정한 기간(start~end) 분단위 가격 데이터를 가져옵니다
* market: 마켓 코드 (ex. "KRW-BTC")
* start: 시작 캔들 시각 (ie, "YYYY-MM-DD HH:MM:SS") start, end를 지정하지 않으면 1분봉 1일
* end: 마지막 캔들 시각 (ie, "YYYY-MM-DD HH:MM:SS")
* unit: 분 단위. 가능한 값 : 1, 3, 5, 10, 15, 30, 60, 240

price_ticker(markets="KRW-BTC,KRW-ETH")  -> pd.DataFrame
>요청 당시 종목의 현재가 정보를 반환합니다
* param markets: 마켓 코드

balance() -> pd.DataFrame
> 잔고를 조회합니다

order(market, volume, price, side='ask', ord_type='limit') -> pd.DataFrame
> 주문을 실행합니다
* market: 코인, 예: 'KRW-BTC'
* volume: 거래량
* price: 가격
* side: 매매 'ask'=매도, 'bid'=매수
* ord_type: 주문형태 'limit'=지정가

order_list(market=None)
> 주문(주로 미체결) 리스트 조회합니다
* market: 'KRW-BTC' (비워두면, 모든 코인의 미체결 내역을 조회합니다)
* state: 'wait'=대기(default), 'watch'=예약주문대기, 'done'=전체체결완료, 'cancel'=주문 취소

order_cancel(uid)
> 주문을 취소합니다. 처리 결과를 dict형식으로 반환합니다.
* uid: 비워두면, 모든 미체결 주문을 취소합니다.

order_closed()
> 종료 주문 목록을 조회 합니다. 최대 7일 구간
