KIS Open API Continuous Automated Stock Trading Program

# KIS Open API Continuous Automated Stock Trading Program ## Version 1 – Complete Development Specification ### One User-Selected Stock at a Time ## Introduction – Why the Initial Budget Is $300 I would like to explain why I am starting this project with a $300 budget. I have previously worked with several developers who claimed to have experience with automated trading systems, but in some cases I did not receive a properly functioning result. Some projects ended in disputes, while others reached or passed the contract deadline without producing a usable program. For this project, I am looking for a developer who has actually built automated trading software before and can reuse and modify source code, architecture, or trading modules from systems they personally developed in the past and have the right to reuse. The previous system does not have to be for Korean stocks. Experience with automated trading systems for U.S. stocks, other stock markets, futures, forex, or cryptocurrency is also relevant. A developer who has genuinely built this type of system should already understand the core structure of real-time market-data processing, trading-condition detection, order submission, fill confirmation, position management, and repeated buy/sell execution. The broker API may be different, but much of the underlying automated-trading structure is similar. Therefore, a developer who already has their own previously developed source code and working architecture should be able to adapt and modify that work for the KIS Open API and the trading rules described in this project. The initial development budget is **$300**. **If the developer successfully completes the program according to the agreed specification and delivers a properly working Version 1, I will pay an additional $100 tip.** Therefore, successful completion of Version 1 will result in a total payment of **$400**. This project is also not intended to end with Version 1. If the program works properly, I plan to continue modifying and improving it based on actual use. Future updates, maintenance, and additional features will be paid separately. I would prefer to find a developer who can use their previous automated-trading development experience and source code to complete this program efficiently and who can continue working with me as the program develops. --- # 1. Project Purpose The purpose of this project is to develop a Windows automated stock trading program for Korean stocks using the Korea Investment & Securities KIS Open API. The user selects one stock to trade. The program monitors the selected stock in real time. When one of the configured buy conditions is satisfied, the program submits a buy order. The program must not assume that the stock has been purchased simply because an order was submitted. The actual fill must first be confirmed. After the actual buy fill is confirmed, the program begins monitoring the configured sell conditions. When a sell condition is satisfied, the program submits a sell order. Only after the sell has been confirmed and the actual holding quantity is confirmed as zero should the program return to monitoring for another buy opportunity. The basic operating flow is: Monitoring → Buy Condition Satisfied → Buy Order → Actual Fill Confirmation → Holding → Sell Condition Monitoring → Sell Order → Actual Sell Fill Confirmation → Re-Entry Waiting → Monitoring Again This process should continue until the configured end time. The program is not permanently restricted to one specific stock. When automatic trading is stopped, the user should be able to change the target stock. Version 1 does not need to automatically trade multiple stocks simultaneously. **The program only needs to automatically trade one user-selected stock at a time.** --- # 2. Operating Environment The program should be developed as a local Windows desktop application. Requirements: Windows 10/11 Python-based development PySide6 / Qt or an equivalent stable desktop GUI framework A normal executable `.exe` for the user No browser required No external web server required Korean-language user interface After normal installation and configuration, the user should be able to start the program by double-clicking the executable. The user should not need to open a Python development environment in order to operate the program. --- # 3. KIS Open API Integration The program must use both: KIS REST API KIS WebSocket REST API should be used where appropriate for functions such as: Account information Holdings Orders Outstanding orders Order-status queries Token management Other required account and order functions WebSocket should be used for real-time functions such as: Real-time trade prices Real-time market data Required real-time order-book data Real-time execution notifications where supported The program must handle: API authentication Access-token management WebSocket authentication WebSocket heartbeat Connection-loss detection Automatic reconnection Automatic resubscription after reconnection If the real-time data connection is lost, the program must not continue automatic trading using old or stale prices. New automatic orders must remain paused until the required connections and trading state have been safely restored. --- # 4. API Keys and Account Information API Key, API Secret, account information, and similar credentials must not be hard-coded directly into the source code. The user should be able to enter the required information through the program settings. Credentials should be stored locally using an appropriate secure method. Sensitive information should not be unnecessarily exposed in: Logs Screenshots Demonstration videos Source-code examples Error messages --- # 5. Development and Trading Environment The final purpose of this program is real trading. However, the developer should first verify the complete automated-trading process in the KIS paper-trading environment. Live trading should only be enabled after the required functions have been successfully tested and the user approves moving to the live environment. The program should be structured so that switching between the appropriate KIS environments does not require rebuilding the trading engine. --- # 6. Stock Selection The target stock must not be hard-coded into the program. The user should be able to select a Korean KOSPI/KOSDAQ stock using the stock name or stock code. The screen should display at least: Stock name Stock code Current price Basic current market information Real-time data connection status Only the currently selected stock needs to be automatically traded at one time. --- # 7. Korean Stock Tick-Size Handling The main trading conditions in this program use **tick units rather than percentages**. The program must correctly apply the KRX/KOSPI/KOSDAQ tick-size rules applicable at the time of delivery. All applicable price bands and boundary prices must be handled correctly. Where applicable, the tick module should support the relevant 1 / 5 / 10 / 50 / 100 / 500 / 1,000 KRW tick-size bands according to the current market rules. The same tick-calculation logic must be used consistently for: Buy conditions Sell conditions Trailing calculations Limit-order prices Displayed trigger prices The user should be able to configure values such as: 2 ticks 5 ticks 10 ticks Where practical, the program should display both the tick value and the corresponding actual KRW price. Example: Basic Sell: -2 ticks Actual Trigger Price: XXXX KRW If the reference price crosses into another tick-size range, the calculation must remain correct. --- # 8. Real-Time Trading Data Actual buy and sell decisions must be based on **real-time trade/tick data**. The program should not depend only on completed 1-minute candles for trading decisions. The program should calculate the real-time information required by the trading rules, including: Current trade price Previous trade price Trade time Recent trade volume where useful Number of ticks moved Number of ticks moved within N seconds Upward movement speed Downward movement speed Continuous upward movement Continuous downward movement Time without price movement Recent high Recent low Highest price after purchase The 1-minute chart is mainly used for visual reference and for calculating the 20-period moving average. The chart must not interfere with or delay the real-time trading engine. --- # 9. Separation of Trading Engine and UI The market-data/trading engine and the graphical user interface should be implemented so that one does not block the other. For example, even if the chart becomes temporarily slow or the UI is being refreshed, the following must continue operating correctly: Real-time market-data processing Buy-condition calculation Sell-condition calculation Order-state processing Execution-notification processing Emergency functions Separate threads, asynchronous processing, or another safe architecture may be used for this purpose. --- # 10. Trading Time Settings The user should be able to configure: Automatic trading start time Automatic trading end time There should also be an option to prevent new buys during the first N minutes after the market opens. The user should be able to configure a time before market close after which no new buy entries are allowed. If a position is still being held at the configured end or liquidation time, the user should be able to choose how it is handled. For example: Stop new buys but continue managing the current position using the normal sell conditions or Liquidate the current position at the configured time --- # 11. Buy Condition 1 – 20-Period Moving Average Pullback and Recovery This is one of the main buy methods. The 5-period moving average is not required. Only the 20-period moving average is used. On the 1-minute chart, the 20-period moving average is calculated from the most recent twenty 1-minute candles. The 20-period moving average is not itself a direct buy signal. It is used as a trend filter. The general logic is: The 20-period moving average is rising. The current price is above the 20-period moving average. The price rises and then pulls back toward the 20-period moving average. The downward movement slows or stops. The price begins rising again. The recovery is confirmed using real-time tick movement. Buy. The program must not buy simply because the price touches the 20-period moving average. Actual upward recovery must first be confirmed. Where practical, values such as proximity to the 20MA, required recovery ticks, time, and other relevant confirmation values should be configurable rather than permanently fixed in the source code. --- # 12. Buy Condition 2 – Independent Rapid-Rise Buy The Rapid-Rise Buy condition operates independently from the 20-period moving-average condition. Therefore, a Rapid-Rise Buy can occur even when the 20MA pullback condition is not satisfied. The user should be able to configure a condition such as: N upward ticks within N seconds Examples: 5 ticks within 5 seconds 6 ticks within 5 seconds These values are examples only and are not fixed. Where needed, the following confirmation values should also be configurable: Minimum movement Minimum consecutive upward ticks Price-movement speed Upward-movement persistence The program must not simply compare the starting price with the ending price. The price movement between those two points also matters. A small normal pullback may occur during a valid upward move. However, a meaningful stagnation period or repeated narrow sideways movement should cause the setup to be rejected or cancelled. --- # 13. Buy Condition 3 – Rebound After a Rapid Drop This is a separate buy method. The program should not buy while the price is still rapidly falling. The objective is not to predict the exact bottom. The basic sequence is: Rapid decline detected A new low is formed Downward movement slows or stops Price begins rising again The configured number of upward ticks occurs within the configured time Continued rebound is confirmed Buy Example: 10-tick rapid decline Low formed Decline stops 4-tick rebound within 5 seconds Upward movement continues Buy The required rapid-drop amount, rebound ticks, time, and confirmation values should be adjustable by the user where necessary. --- # 14. Sideways-Market Buy Filter The program should not buy simply because the price rises by one or two ticks. For example: +2 ticks -2 ticks +2 ticks -1 tick +1 tick This may represent sideways movement rather than a genuine upward move. If this type of movement repeatedly occurs inside a narrow price range, the program should avoid opening a new position. Version 1 does not require an unnecessarily complicated market-classification system. However, a practical basic filter is required to reduce repeated unnecessary buys during obvious short-term sideways conditions. --- # 15. Stagnation During a Buy Setup If an upward buy setup is developing and the price remains unchanged for the configured period, the current buy setup should be cancelled. Example: +1 tick +2 ticks +3 ticks No price movement for 2 seconds Cancel the current buy setup Do not buy The stagnation time must be adjustable by the user. The important point is that a meaningful stop during an upward setup should not continue to be treated as strong continuous upward momentum. --- # 16. Re-Entry After Buy-Setup Stagnation If the previous buy setup was cancelled because of stagnation, the program should not immediately reuse the same setup. The previous signal should be discarded. The general process is: Stagnation occurs Current buy setup is cancelled New entries are temporarily blocked The program monitors normal tick movement Normal movement continues for the configured normalization period Buy-condition monitoring starts again from the beginning For example, the normalization period may initially be approximately one minute. The user should be able to change this value. --- # 17. Market / Limit Order Selection The main screen should provide a simple one-click selection between: MARKET LIMIT Only one order type should be active at a time. The currently selected order type must be clearly visible. Unless a separate emergency rule is specifically configured, the selected order mode should apply to subsequent automated buy and sell orders. --- # 18. Limit-Order Price Settings Limit orders should support a practical configurable price basis. For example: Best bid / best ask or Current price ± N ticks The user should be able to configure a timeout for unfilled limit orders. The normal default behavior after the timeout should be to cancel the remaining unfilled quantity. Automatic repricing may be provided as an optional function and may be OFF by default. The program must never assume that a submitted limit order has been filled until actual execution is confirmed. --- # 19. Basic Sell The Basic Sell condition is used to protect against a decline after purchase. It should have its own separate settings. Example: Buy price: 1,000 KRW Basic Sell: -2 ticks Price falls 2 ticks or more from the buy reference Sell condition occurs The -2 tick value is a **sell trigger condition**. It does not mean that the program must execute only at exactly that price. For example, if the price suddenly falls 5 or 10 ticks and passes the configured trigger, the sell condition has already been satisfied and the program should immediately perform the appropriate sell logic. --- # 20. Adaptive Post-Rise Trailing Sell After the price rises following a purchase, different trailing distances should be used depending on how far the price has risen. The same fixed pullback distance should not be used for every situation. Example initial structure: If the price rises +1 to +4 ticks from the buy price: → Sell after a 3-tick drop from the highest price If the price rises +5 to +9 ticks: → Sell after a 4-tick drop from the highest price If the price rises +10 to +14 ticks: → Sell after a 5-tick drop from the highest price These numbers are starting examples and must be user-adjustable. The ranges should not overlap. Additional ranges should be possible later. The program must continuously update the highest price reached after purchase. Example: Buy New high Higher new high Another higher new high Each new high updates the trailing reference. The active allowed pullback is determined by the current rise from the buy price. --- # 21. Stagnation Sell There should be a separate sell condition for price stagnation while a position is being held. Example: Price rises after the buy The price remains unchanged for the configured 2 seconds Sell condition occurs The stagnation duration must be adjustable. The Stagnation Sell function should have its own ON/OFF control. --- # 22. Rapid-Drop Sell If a sudden price decline passes an active sell threshold in one movement, the sell condition must still trigger immediately. Example: Current trailing rule: sell after 4 ticks down from the highest price The price suddenly drops 10 ticks The 4-tick threshold has already been crossed Trigger the sell immediately The same principle applies to the Basic Sell rule. Even if multiple sell conditions become true at the same time, only one actual sell order should be submitted. --- # 23. Separate Sell Settings The main sell conditions should be separated into: Basic Sell Settings Adaptive Post-Rise Sell Settings Stagnation Sell Settings The main screen does not need to display every detailed number. It may simply show statuses such as: ON OFF Configured The detailed values can be changed through small separate settings windows. --- # 24. Buy Order Fill Confirmation A buy signal does not mean that the user already owns the shares. The correct sequence should be: Buy signal Submit buy order Identify the broker order number Track the order Confirm actual executed quantity Update the actual position Only then enter the Holding state While the previous buy order remains unresolved, additional buy signals must not create new buy orders. --- # 25. Sell Order Fill Confirmation The same principle applies to selling. Submitting a sell order does not automatically mean the position has been closed. The program must: Submit the sell order Track the order Confirm actual sold quantity Check the remaining holding quantity Confirm that the actual holding quantity is zero Only then move to the FLAT or Re-Entry state --- # 26. Partial Fill Handling Partial fills must be handled correctly. The program should separately track: Requested order quantity Cumulative filled quantity Remaining unfilled quantity Average execution price Example: Buy order: 100 shares 40 shares filled 60 shares remain unfilled Timeout occurs Cancel the remaining 60 shares The program must not assume that the process is finished immediately after requesting cancellation. It must check whether any additional shares were filled while the cancellation was being processed. Only the final confirmed executed quantity should be treated as the actual position. If a sell condition occurs, only the final confirmed actual holding quantity may be sold. --- # 27. Unfilled Order Handling An unfilled order must not leave the program in an undefined state. The program should be able to distinguish normal order states such as: Pending Partially Filled Filled Cancellation Pending Cancelled Rejected Reconciling / Status Unknown A new conflicting order must not be submitted while the previous order remains unresolved. --- # 28. Duplicate Order Prevention Duplicate orders must be prevented. One buy signal must not send repeated buy orders simply because multiple WebSocket updates are received. One sell condition must not send repeated sell orders. Internal trading signals should be associated with actual broker order identifiers. If a REST response and a WebSocket execution notification both report the same order or fill, the same event must not be processed twice. If a REST order response is delayed or times out, the program must not immediately assume that the order failed and submit another identical order. The actual order state should first be checked with KIS before another action is taken. --- # 29. Separation of Signal State and Order State Trading-signal state and actual broker order state should be managed separately. For example, signal states may include: WATCHING SETUP FORMING ARMED CANCELLED BY STAGNATION RE-ENTRY WAITING Order and position states may include: IDLE BUY PENDING BUY PARTIAL HOLDING SELL PENDING SELL PARTIAL CANCEL PENDING RECONCILING FLAT PAUSED / ERROR These exact names do not have to be used. The important requirement is that **a new order must not be submitted while the previous order remains unresolved.** --- # 30. WebSocket Reconnection and Application Restart Recovery This is an important requirement. If the WebSocket connection is lost or the program closes unexpectedly, the program must not rely only on previously stored local state when it starts again. After reconnection or application restart, the program should query KIS for: Actual current holdings Current outstanding orders Same-day orders Same-day executions/fills The actual brokerage account state should be treated as the final source of truth. The local database is supporting information. Automatic trading should remain paused while the program reconciles the broker state with the local state. Only after the actual state has been confirmed should automatic trading resume safely. Any differences and recovery actions should be recorded in the logs. --- # 31. Continuous Automatic Trading and Re-Entry After the sell is completely filled and the actual holding quantity is confirmed as zero, the program should return to buy-condition monitoring. General flow: Monitoring Buy Actual fill confirmed Holding Sell Complete liquidation confirmed Re-entry waiting Monitoring again The user should be able to configure the waiting time after a completed sell. The program should wait for a newly formed buy setup rather than simply reusing the previous signal. The Buy → Sell → Monitor → Buy → Sell cycle should continue automatically until the configured end time. --- # 32. Risk and Safety Limits Because this is a real automated trading program, basic configurable safety limits should be available. Examples include: Maximum daily loss Maximum number of trades Order quantity Session profit/loss limit Only one position in the currently selected stock should be allowed at one time. If the connection state, current holding quantity, or order state becomes unclear, the program should move to a PAUSED state rather than continuing to trade blindly. --- # 33. Emergency Stop A clearly visible Emergency Stop button is required on the main screen. Emergency Stop should operate independently from the normal trading-strategy logic. When Emergency Stop is activated: Stop new automated trading actions Handle or cancel outstanding orders Handle the current position according to the selected emergency setting The user should be able to choose whether Emergency Stop: Liquidates the current position or Stops automation while keeping the current position If the actual order or position state cannot be confirmed, the program should remain paused and clearly warn the user instead of continuing to trade. --- # 34. Main Screen The main screen should be simple and practical. A large chart should occupy the central area. Only the important settings and information need to be placed at the top or side. Important main-screen items include: Selected stock Stock code Current price Order quantity Start time End time Market / Limit selection Buy-condition settings Basic Sell Settings Adaptive Post-Rise Sell Settings Stagnation Sell Settings Start Stop Emergency Stop Connection status Current program status Current order status Current holding quantity Average buy price Highest price after buy Current active sell trigger Current profit/loss Overall trading results --- # 35. Chart The main chart should use a real-time 1-minute candlestick chart. The 20-period moving average should also be displayed. The chart is mainly for the user to visually confirm how the automated trading program is operating. Actual trading decisions must continue to be based on real-time tick data. Chart updates or UI rendering must not interfere with the real-time trading engine. --- # 36. Buy and Sell Markers The chart should display buy and sell markers based on the **actual execution time and actual execution price**, not only on the original signal time. Buy: Red upward triangle ▲ Sell: Blue downward triangle ▼ The chart should remain as simple and clean as possible. Detailed information should not be displayed as long text directly over the chart. --- # 37. Real-Time Tick Information A small real-time tick or trade-information area should be displayed separately from the main chart. This allows the user to see the actual current short-term price movement without filling the 1-minute candlestick chart with unnecessary information. --- # 38. Trade Information Panel Detailed buy and sell information should be shown in a separate information area outside the chart. Useful information includes: Buy / Sell Time Actual execution price Actual executed quantity Reason for the buy Reason for the sell Highest price after purchase Current or final profit/loss Possible trade reasons include: 20MA Pullback Buy Rapid-Rise Buy Rapid-Drop Rebound Buy Basic Sell Adaptive Post-Rise Sell Stagnation Sell Where practical, clicking a buy or sell marker on the chart may display the detailed information for that trade. --- # 39. Current Program Status The user should be able to immediately understand what the program is currently doing. Examples: Monitoring Buy Setup Forming Buy Order Pending Buy Partially Filled Holding Monitoring Sell Conditions Sell Order Pending Sell Partially Filled Re-Entry Waiting Reconciling Account State Paused Stopped Error --- # 40. Connection and Order Status Important connection and trading-status information should be visible on the screen. Examples: KIS Connected WebSocket Connected Trading Ready Order Pending Order Filled Reconnecting Reconciling Paused Connection Error The exact wording can be adjusted during development. The important point is that the user should be able to immediately see whether the program is currently in a safe state for automatic trading. --- # 41. Profit and Trading Results The main screen should always show the important trading results. At minimum: Current Unrealized P/L Accumulated Realized P/L for the current session Total P/L for the current session Number of completed trades Winning trades Losing trades Win rate Example: Unrealized P/L: +12,500 KRW Realized P/L: +48,000 KRW Total P/L: +60,500 KRW Completed Trades: 8 Wins: 6 Losses: 2 Win Rate: 75% --- # 42. Data Storage SQLite or an equivalent reliable local database should be used. The program should store the necessary information, including: Real-time ticks Buy and sell signals Orders Broker order numbers Executions/fills Partial fills Cancellations State transitions Errors Connection events Profit/loss Trading history Trade records should include information such as: Date and time Stock Buy / Sell Requested quantity Actual executed quantity Actual execution price Buy reason Sell reason Highest price after purchase Final profit/loss Order status --- # 43. Data Export Stored trading information should be exportable to a common format such as: CSV Excel-compatible format A complete historical tick-replay interface is not required in Version 1. However, the storage structure should be designed so that future replay or analysis functions can be added later. The previously discussed separate function for automatically learning from and analyzing historical data for one specific stock is **not included in Version 1**. --- # 44. Error Logging The program should save useful technical error information so that future problems can be identified and corrected. Examples: Authentication failure REST request failure WebSocket disconnection Reconnection attempt Order rejection Order timeout Cancellation failure Internal state mismatch Mismatch between actual brokerage holdings and internal program state Unexpected application error Sensitive credentials such as API Secrets must not be written into these logs. --- # 45. Developer Testing The developer must test the program before delivering it to the user. The user should not be used as the developer's basic debugger. The developer should not repeatedly send broken builds and ask the user to discover ordinary programming errors. At minimum, the developer should personally verify: KIS authentication Real-time tick reception WebSocket reconnection Stock selection Tick-size calculation Market orders Limit orders Buy order → fill confirmation Sell order → fill confirmation Partial fills Cancellation of unfilled quantity Additional fills occurring during cancellation Duplicate-order prevention Application restart while an order or position exists Recovery using the actual brokerage account state 20MA Pullback Buy Independent Rapid-Rise Buy Rapid-Drop Rebound Buy Sideways-market rejection Buy cancellation caused by stagnation Normalization and re-entry after stagnation Basic Sell Adaptive Post-Rise Trailing Sell Stagnation Sell Rapid-Drop Sell Re-entry after a completed trade Emergency Stop Start time / End time Data storage UI operation --- # 46. Final Delivery Final delivery should include: Complete source code Working Windows `.exe` Required configuration files or sample configuration Korean user manual/instructions Database and logs required for verification A normal working demonstration video Testing or verification evidence The complete source code must be provided. The program must be able to run on a normal Windows PC without requiring the developer's private development environment. --- # 47. Version 1 Exclusions To keep Version 1 focused, the following are not required: AI Price Prediction Machine Learning Deep Learning Automatic Stock Recommendation Simultaneous Multi-Stock Automated Trading 41-stock Rapid-Rise Ranking Web Dashboard Cloud Server Mobile Application Overseas Stock Trading Cryptocurrency Trading Futures / Options Trading Complete Historical Tick-Replay Interface Automatic Strategy Optimization Trading strategies invented by the developer that are not included in this specification --- # 48. Version 1 Completion Standard The most important completion requirement for Version 1 is that the complete trading process below works correctly: Connect to KIS Select a trading stock Receive real-time market data Monitor the configured buy conditions Detect a valid buy condition Submit a buy order Confirm the actual fill Correctly update the actual holding quantity Monitor the configured sell conditions Detect a valid sell condition Submit a sell order Confirm the actual sell execution Confirm that the actual holding quantity is zero Record the trade result Apply the configured re-entry condition or waiting time Return to buy-condition monitoring Repeat the Buy → Sell → Re-Buy process The important point is not to display a large number of features on the screen. The most important requirement is that the complete mechanism of: **Real-Time Data → Trading Decision → Actual Order → Actual Fill → Position Management → Sell → Confirmed Liquidation → Re-Entry** works reliably. --- # 49. Development Direction After Version 1 Version 1 is the foundation of the program. After Version 1 works properly, actual trading results can be used to adjust settings such as: 20MA pullback entry conditions Rapid-rise speed Required upward ticks Rapid-drop rebound confirmation Sideways-market filtering Stagnation timing Basic Sell tick distance Adaptive Post-Rise Trailing Sell ranges Re-entry timing Limit-order handling Additional functions can also be added later. These modifications and additional functions will be handled as separate paid updates. The purpose of Version 1 is not to claim that the first trading strategy is already perfect or guaranteed to generate profit. The goal is first to complete a **stable and correctly functioning automated-trading structure**, and then continue improving the buy and sell conditions based on actual use.