@2oolkit/kiwoom-cli 0.1.0

package/skill/references/market-data.md

@@ -0,0 +1,78 @@
+# Market Data Reference
+
+All market-data commands accept `-o, --output <table|json>`. Use `json` for parsing.
+
+## Current price & quotes
+
+```bash
+kiwoom-cli market price 005930        # ka10007 — name, price, change, OHLC, top-of-book
+kiwoom-cli stock info 005930          # ka10001 — fundamentals + price (PER/EPS/ROE/PBR/BPS)
+kiwoom-cli market orderbook 005930    # ka10004 — 10-level bid/ask ladder
+kiwoom-cli market after-hours 005930  # ka10087 — after-hours single price
+```
+
+### Reading prices
+Quote/chart price fields carry a **direction sign** relative to the previous close:
+`-353750` means the price is **353,750**, trading *below* the prior close. The CLI displays the
+magnitude (`353,750`) and reports `change` / `changeRate` separately. In JSON the raw signed string
+is preserved — strip a leading `+`/`-` to get the value.
+
+`pred_pre_sig` / `pre_sig` codes: `1`=상한, `2`=상승, `3`=보합, `4`=하한, `5`=하락.
+
+## Order book (`market orderbook`)
+
+10 levels each side. JSON `-o json` returns the raw ka10004 payload with the irregular field
+naming (level 1 = `sel_fpr_*` / `buy_fpr_*`, levels 2–10 = `sel_Nth_pre_*` / `buy_Nth_pre_*`).
+The table view renders an aligned ladder (asks top, bids bottom) plus total ask/bid quantities.
+
+## Trades & strength
+
+```bash
+kiwoom-cli market trades 005930              # ka10003 — recent tick executions
+kiwoom-cli market strength 005930            # ka10046 — intraday 체결강도 series
+kiwoom-cli market strength 005930 --daily    # ka10047 — daily 체결강도 series
+kiwoom-cli market daily 005930 -d 20260622   # ka10086 — daily price history (+investor flows)
+kiwoom-cli market inst-foreign 005930 -s 20260601 -e 20260622   # ka10045
+```
+
+## Charts
+
+| Timeframe | Command | TR | Scope option |
+|---|---|---|---|
+| Tick | `chart tick <code> -s <n>` | ka10079 | ticks 1/3/5/10/30 |
+| Minute | `chart min <code> -i <n>` | ka10080 | minutes 1/3/5/10/15/30/45/60 |
+| Daily | `chart day <code> -d <YYYYMMDD>` | ka10081 | base date |
+| Weekly | `chart week <code>` | ka10082 | base date |
+| Monthly | `chart month <code>` | ka10083 | base date |
+| Yearly | `chart year <code>` | ka10094 | base date |
+
+Common: `-n <count>` caps displayed rows (default 50); `--raw` returns unadjusted prices
+(`upd_stkpc_tp=0`). Charts are returned latest-first. Item time fields: `cntr_tm`
+(tick/minute, YYYYMMDDHHMMSS) or `dt` (period, YYYYMMDD).
+
+```bash
+kiwoom-cli chart min 005930 -i 5 -n 30 -o json
+kiwoom-cli chart day 005930 -n 60
+```
+
+## Rankings
+
+```bash
+kiwoom-cli ranking fluctuation -s 1   # ka10027 — 1=상승률,2=상승폭,3=하락률,4=하락폭,5=보합
+kiwoom-cli ranking volume -s 1        # ka10030 — 1=거래량,2=거래회전율,3=거래대금
+kiwoom-cli ranking amount             # ka10032 — top trade value
+kiwoom-cli ranking surge -s 1         # ka10023 — volume surge
+kiwoom-cli ranking prev-volume        # ka10031 — prior-day volume
+```
+Flags: `-m 000=all/001=KOSPI/101=KOSDAQ`, `-x 1=KRX/2=NXT/3=unified`.
+
+## Sectors / industry
+
+```bash
+kiwoom-cli sector codes               # ka10101 — list valid industry codes (inds_cd)
+kiwoom-cli sector all                 # ka20003 — every sector index
+kiwoom-cli sector price -m 0 -c 001   # ka20001 — one index (001=종합 KOSPI)
+kiwoom-cli sector stocks -c 001       # ka20002 — constituents
+kiwoom-cli sector daily -c 001        # ka20009 — daily index history
+```
+`-m 0=KOSPI/1=KOSDAQ/2=KOSPI200`. Common codes: `001`=종합(KOSPI), `101`=종합(KOSDAQ).

package/skill/references/trading.md

@@ -0,0 +1,99 @@
+# Trading Reference
+
+> ⚠️ On the `real` environment these commands place **live orders with real money**.
+> Switch to the simulation server first: `kiwoom-cli config set --env mock`.
+> Every CLI order prompts for confirmation unless you pass `-y/--yes`.
+
+## Place orders
+
+```bash
+# Limit buy 1 share of 005930 at 70,000 KRW
+kiwoom-cli order buy 005930 1 -p 70000
+
+# Market sell 1 share (omit -p for a market order)
+kiwoom-cli order sell 005930 1
+
+# Explicit order type
+kiwoom-cli order buy 005930 1 -p 70000 -t 0      # 0 = limit
+kiwoom-cli order buy 005930 1 -t 3               # 3 = market
+```
+
+### Order type codes (`-t` / `trde_tp`)
+
+| Code | Meaning | | Code | Meaning |
+|---|---|---|---|---|
+| `0` | 보통 (limit) | | `20` | 보통 FOK |
+| `3` | 시장가 (market) | | `23` | 시장가 FOK |
+| `5` | 조건부지정가 | | `26` | 최유리 FOK |
+| `6` | 최유리지정가 | | `28` | 스톱지정가 (stop-limit) |
+| `7` | 최우선지정가 | | `29` | 중간가 |
+| `10` | 보통 IOC | | `30` | 중간가 IOC |
+| `13` | 시장가 IOC | | `31` | 중간가 FOK |
+| `16` | 최유리 IOC | | `61/62/81` | pre/after/post off-hours |
+
+- Market types (`3`, `13`, `23`) must **not** include `-p`; the price is sent empty.
+- Limit-style types require `-p`.
+- If `-t` is omitted: a `-p` implies limit (`0`), no `-p` implies market (`3`).
+
+## Modify & cancel
+
+```bash
+# Modify a resting order to new qty/price
+kiwoom-cli order modify 0000139 005930 1 71000
+
+# Cancel all remaining of an order
+kiwoom-cli order cancel 0000139 005930
+
+# Cancel a partial quantity
+kiwoom-cli order cancel 0000139 005930 -q 1
+```
+The `<orderNo>` is the order number returned when the order was placed (or from
+`kiwoom-cli account open-orders`). The exchange (`-x`) must match the original order.
+
+## Exchange routing (`-x` / `dmst_stex_tp`)
+
+| Value | Meaning |
+|---|---|
+| `KRX` | Korea Exchange (default) |
+| `NXT` | Nextrade ATS |
+| `SOR` | Smart Order Routing (best execution across KRX + NXT) |
+
+## Credit (margin) orders
+
+Add `--credit` to route to the credit order TRs (`/api/dostk/crdordr`):
+
+```bash
+kiwoom-cli order buy 005930 1 -p 70000 --credit
+kiwoom-cli order sell 005930 1 -p 72000 --credit --credit-deal 33 --loan-date 20260102
+```
+- `--credit-deal` (신용거래구분): `33`=융자, `99`=융자합 (sell only).
+- `--loan-date` (대출일, YYYYMMDD): required when repaying a specific loan tranche.
+
+## Confirmation flow
+
+Each order prints a summary, e.g.:
+```
+BUY 005930  qty 1  @ 70000  type 0(보통(지정가/limit))  [KRX]  on REAL  ⚠ REAL MONEY
+Proceed? (y/N):
+```
+Answer `y` to submit, anything else to abort. Pass `-y/--yes` to skip the prompt in scripts.
+
+## MCP order tools
+
+`place_order`, `modify_order`, `cancel_order` accept the same parameters plus a **`confirm`**
+boolean. Without `confirm: true` they return a preview and submit nothing — so an AI agent
+cannot place a live order by accident.
+
+```jsonc
+// place_order args
+{ "side": "buy", "code": "005930", "qty": "1", "price": "70000", "confirm": false }  // preview
+{ "side": "buy", "code": "005930", "qty": "1", "price": "70000", "confirm": true }   // submits
+```
+
+## After ordering
+
+Confirm fills with the real-time open-orders / executions TRs:
+```bash
+kiwoom-cli account open-orders
+kiwoom-cli account executions
+```