Real-Time 1-Minute Rising Stock Scanner & Trading System Using Korea Investment Open API

# Project Title **Real-Time 1-Minute Rising Stock Scanner & Trading System Using Korea Investment & Securities Open API** # 1. Project Overview The purpose of this project is to develop a **Windows-based real-time stock monitoring and trading application** using the **Korea Investment & Securities KIS Open API**. The program must detect stocks that are rising strongly within the **current 1-minute interval**, rank them in real time, track stocks whose upward movement continues for up to three consecutive minutes, display charts, and allow the selected stock to be traded directly from the same dashboard. This is **not a standard daily percentage-gain ranking system**. Most brokerage platforms rank stocks based on the percentage change from the previous day’s closing price. This program is different. Its main purpose is to determine: **Which stocks are rising the fastest right now, during the current 1-minute period.** The core processing flow is: **Real-time market data → 1-minute reference price → Real-time percentage calculation → Top 10 ranking → Continued-rise tracking → Chart selection → Order integration** # 2. Korea Investment & Securities Open API The program must use the **official Korea Investment & Securities Open API** as the primary source for: * Real-time market data * Current stock prices * Stock information * Account information * Balance information * Holdings * Buy orders * Sell orders * Market orders * Limit orders * Order correction * Order cancellation * Trade execution information * Other supported brokerage functions Real-time market data should use the **KIS WebSocket real-time feed whenever available**. The developer should not unnecessarily recreate functions that Korea Investment & Securities already provides reliably. The program should use the official KIS API methods, data structures, and order processes whenever possible. The purpose of this approach is to reduce: * Errors * Development complexity * Order-processing problems * Maintenance difficulty * Differences between the custom program and the brokerage account The custom development should focus primarily on the unique real-time stock-detection functionality described in this specification. # 3. Windows 10 Standalone Application The final program must run on **Windows 10**. The user must **not** be required to install: * Python * Python libraries * Development tools * Command-line tools * IDE software * Separate programming environments The developer may use Python or another programming language internally. However, the completed program must be delivered as a **standalone Windows application**, such as: * `.exe` * Windows installer All required runtimes and libraries must be bundled with the program. The user should be able to install or launch the application directly. # 4. Automatic Operation The program should begin real-time monitoring automatically when it is launched. There should be no requirement for the user to manually start the scanner every time. Once valid market data is available, the system should automatically: 1. Receive real-time data. 2. Establish the current 1-minute reference price. 3. Calculate current 1-minute percentage movement. 4. Rank stocks. 5. Update the dashboard continuously. # 5. Market Selection At the top of the dashboard, the following buttons must be provided: **Domestic / Overseas / All** ### Domestic Only eligible Korean stocks are monitored. ### Overseas Only eligible overseas stocks supported through the KIS API are monitored. ### All Eligible domestic and overseas stocks are monitored together using the same ranking logic where technically supported. # 6. Supported Trading Hours The application must **not be restricted to regular market hours only**. The program should operate during every session in which Korea Investment & Securities provides the required real-time market data and/or order functionality. This may include: * Pre-market * Regular market * After-hours market * Other supported trading sessions The same basic 1-minute monitoring logic should continue whenever valid real-time market data is available. If real-time data is not available, the program must not create artificial prices or simulated data. The application should remain in a waiting or disconnected state until valid data becomes available again. # 7. Real-Time 1-Minute Reference Price This is the most important feature of the program. At the beginning of every 1-minute interval, the current stock price becomes the new **0% reference price**. Example: At: **10:30:00** Samsung Electronics price: **100,000 KRW** The program sets: **100,000 KRW = 0.00%** If the price becomes: **100,100 KRW** the program calculates: **+0.10%** If the price becomes: **100,500 KRW** the program calculates: **+0.50%** This percentage is based only on the price at the beginning of the current minute. It is **not based on the previous day’s closing price**. # 8. Automatic 1-Minute Reset The calculation continues throughout the current minute. Example: **10:30:00 – 10:30:59** At exactly: **10:31:00** the previous calculation must be reset. The current price at 10:31:00 becomes the new: **0% reference price** for the next minute. The same process repeats continuously: **10:31:00 → 10:32:00 → 10:33:00 → etc.** # 9. Real-Time Top 10 Ranking The system must calculate the stocks with the strongest positive movement during the current 1-minute period. Only the **Top 10 stocks** are displayed. Example: 1. Samsung Electronics +0.82% 2. SK Hynix +0.71% 3. Hanmi Semiconductor +0.64% 4. Stock D +0.58% 5. Stock E +0.52% The ranking must update continuously. If SK Hynix increases from: **+0.71% → +0.90%** it must immediately move from Rank 2 to Rank 1. The ranking should reflect the latest real-time state. # 10. Real-Time Ranking Updates The program must not wait until the end of each minute to update the ranking. The list should change continuously as valid real-time prices are received. Stocks may: * Move up * Move down * Enter the Top 10 * Leave the Top 10 The order displayed on the screen should update accordingly. # 11. Eligibility for Continued-Rise Tracking Only stocks that have entered the **Real-Time Top 10** may enter the continued-rise tracking system. A stock that has never entered the Top 10 should not independently appear in the 1 Minute Ago, 2 Minutes Ago, or 3 Minutes Ago columns. # 12. Continued-Rise Columns The dashboard should display the following four monitoring columns from left to right: **3 Minutes Ago | 2 Minutes Ago | 1 Minute Ago | Real-Time** These columns are used to identify stocks whose upward movement continues. # 13. Meaning of “1 Minute Ago” The **1 Minute Ago** column is not simply a historical list. It does not mean: “A stock that happened to be rising one minute ago.” Instead, it means: A stock entered the Real-Time Top 10 and then **continued its upward movement into the following minute**. Only stocks maintaining the required upward behavior should remain in this column. # 14. Meaning of “2 Minutes Ago” A stock that remains in the continued-rise process for another minute can progress from: **1 Minute Ago → 2 Minutes Ago** The stock must continue to satisfy the upward-movement requirement. # 15. Meaning of “3 Minutes Ago” A stock that continues its upward movement for another period can progress from: **2 Minutes Ago → 3 Minutes Ago** Tracking stops here. There is no: * 4 Minutes Ago * 5 Minutes Ago * Longer tracking column The program only tracks up to three stages. # 16. Decline Detection A stock should not immediately disappear from a continued-rise column because of a very short downward price movement. Temporary market noise must be considered. When a decline is detected: **Do not remove the stock immediately.** Instead, start a **5-second confirmation period**. # 17. Five-Second Grace Period The logic must be: **Decline detected → Wait 5 seconds** If the stock recovers and returns to the required upward condition within those 5 seconds: **Keep the stock in the current column.** If the stock is still declining after 5 seconds: **Remove the stock from the current continued-rise column.** Therefore: **Recovery within 5 seconds = Keep** **Still declining after 5 seconds = Remove** # 18. Dashboard Structure The main screen should be designed as a **single-screen trading dashboard**. The user should not need to continuously scroll to access the primary functions. The main columns from left to right must be: **3 Minutes Ago | 2 Minutes Ago | 1 Minute Ago | Real-Time | Order Panel | Watchlist | Holdings** # 19. Top Dashboard Area The top area should contain: **Domestic / Overseas / All** market-selection buttons. It should also display: * Current time * API connection status * Time remaining until the next 1-minute reset Example: **Current Time: 10:30:42** **KIS API: Connected** **Next Reset: 00:18** # 20. Stock Ranking Boxes Every stock in the: * Real-Time * 1 Minute Ago * 2 Minutes Ago * 3 Minutes Ago columns should be displayed as an individual clickable box. Each stock box should show at minimum: * Rank * Stock name * Current price * Current percentage movement Example: **1 | Samsung Electronics | 78,500 KRW | +1.24%** # 21. Stock Box Selection The entire stock box should be clickable. When the user clicks a stock: * The stock becomes the selected stock. * The corresponding chart changes to that stock. * The Order Panel changes to that stock. The selected stock box should visually change so the user can clearly identify it. Possible selection indicators include: * Different background * Highlighted border * Different glow * Other clear visual state # 22. Chart Display At the top of each of these four columns: * Real-Time * 1 Minute Ago * 2 Minutes Ago * 3 Minutes Ago there should be a small chart area. The chart should be a **candlestick chart**. The final program should not use arbitrary line graphics as a substitute for the actual chart. # 23. Default Chart Behavior If the user has not manually selected a stock, the chart should automatically display the current **Rank 1 stock** in that column. If Rank 1 changes, the chart should automatically change to the new Rank 1 stock. # 24. Manual Chart Selection If the user clicks another stock box, the chart must immediately display that stock. The selected box should remain visually highlighted. # 25. Order Panel Integration Every stock box in all four ranking sections must be connected directly to the Order Panel. Example: The user clicks SK Hynix in the **2 Minutes Ago** column. Immediately: * The SK Hynix chart is selected. * SK Hynix becomes the active stock in the Order Panel. This behavior must apply to **every numbered stock box**, not only the Real-Time column. # 26. Order Panel The Order Panel should follow the Korea Investment & Securities trading interface and official Open API order structure as closely as practical. The developer should avoid creating an unnecessarily different order process. The Order Panel should include the functions supported and required for normal trading, including: * Buy * Sell * Market order * Limit order * Quantity * Order price * Order confirmation * Order correction * Order cancellation # 27. Order Confirmation Before an actual order is transmitted, the user should be able to review the order information. This is particularly important for: * Stock * Buy/Sell direction * Quantity * Price * Order type Actual order processing must use the official KIS API. # 28. Watchlist Each ranking box should include a separate **heart button**. The heart button must be independent from the main stock-box click. Clicking the stock box: **Chart selection + Order selection** Clicking the heart: **Add/remove Watchlist** # 29. Watchlist Persistence Where technically supported by the Korea Investment system, the Watchlist should be integrated with the brokerage account rather than being only locally stored by the application. The objective is for the Watchlist to remain available independently of whether this application is currently running. If this specific function is not supported by the KIS API, the developer must inform the client before implementing an alternative local solution. The developer must not silently substitute a different method. # 30. Holdings / Purchase List Actual purchased and executed stocks must appear in the **Holdings / Purchase List**. Each holding should be displayed in a stock-box style similar to the rest of the application. At minimum, the holding box should show: * Stock name * Current price * Percentage change * Purchase amount * Quantity held The overall structure should resemble the Korea Investment holdings/balance interface where practical. # 31. Immediate Holdings Update When an actual order is executed, the Holdings list must update automatically. The user should not need to manually refresh the account. Executed purchases and sales should be reflected as soon as the KIS API provides the updated execution/account information. # 32. Order History Order History should not occupy a large permanent section of the main dashboard. It should be implemented as a compact interface, such as: * Expand/Collapse * Small button * Secondary panel * Popup * Compact list The primary dashboard space should remain focused on the live scanner and trading interface. # 33. API Connection Status The program must clearly show the current KIS API/WebSocket connection status. Example: **Connected** or **Disconnected** # 34. Connection Loss Handling If the real-time connection is lost: * Do not continue calculating rankings from stale data. * Do not create fake data. * Display the disconnected status. * Attempt automatic reconnection where appropriate. Once valid real-time data returns, processing may resume. # 35. No Artificial Market Data The program must never create or insert fake stock prices simply to keep the interface moving. If the market data is unavailable: **The correct behavior is to wait.** This applies to all supported markets and trading sessions. # 36. Use KIS Functions Whenever Possible Functions unrelated to the unique stock-scanning logic should use Korea Investment & Securities systems whenever technically possible. Examples include: * Orders * Account * Balance * Holdings * Execution information * Current price * Order correction * Order cancellation * Supported stock information This is specifically intended to minimize bugs. # 37. Functions That Must Be Custom-Developed The following are the major custom functions required for this project: * Real-time 1-minute percentage calculation * Automatic 1-minute reset * Real-time Top 10 ranking * Dynamic rank reordering * Continued-rise tracking * 1 Minute Ago classification * 2 Minutes Ago classification * 3 Minutes Ago classification * 5-second decline confirmation * Clickable stock boxes * Selected-stock highlighting * Chart linkage * Order Panel linkage * Integrated dashboard UI # 38. Important Notes for the Developer The following requirements are important and must be understood before accepting the project. ### A. Do Not Change the Project Direction Without Approval The developer must not independently change the fundamental operation of the program. If the developer believes another technical method would be better, they may propose it. However, the developer must receive approval **before changing the agreed behavior**. ### B. Do Not Replace Requested Functions With Different Functions A technically working function is not automatically acceptable if it performs a different task from the requested function. Example: A normal daily stock-gain ranking is **not an acceptable replacement** for the required current 1-minute rising-stock ranking. ### C. Do Not Add Unrequested Major Features The developer should not make the program unnecessarily complicated by adding unrelated: * Indicators * AI models * Trading strategies * Automated trading systems * Additional charts * Analytics unless they are separately approved. The objective is to build the specified program accurately. ### D. Follow the Approved Dashboard Structure The main dashboard layout and basic interaction logic should follow the provided specification and reference image. The developer may improve spacing, technical implementation, responsiveness, or minor visual details. However, important functions or sections must not be removed, repositioned into a completely different workflow, or replaced without approval. ### E. KIS API Limitations Must Be Reported If any requested function cannot be implemented exactly because of a Korea Investment Open API limitation, the developer must inform the client clearly. The developer should explain: 1. What API limitation exists. 2. Which requested function is affected. 3. What alternative implementation is possible. 4. Whether that alternative changes the intended behavior. Approval should be obtained before implementing a materially different alternative. ### F. No Hidden Simulation Real-time functionality must use actual valid API data. The developer must not demonstrate the final program using simulated values while presenting it as actual KIS real-time operation. Simulation may be used temporarily during development, but it must be clearly identified as simulation. ### G. Real Account Functionality The program is intended to operate using the user's Korea Investment account and official API connection. Actual order functions must be tested carefully. The developer must avoid uncontrolled or unintended real-money orders during testing. Testing methods should be coordinated with the client where real account execution is involved. ### H. Error Handling The final program must handle common operational failures properly, including: * API authentication failure * WebSocket disconnect * Network interruption * Invalid order response * Rejected order * Missing market data * API rate or request errors * Program restart The application should not simply freeze or silently fail. ### I. Clear Error Messages When a problem occurs, the program should show understandable status information. For example: **KIS Connection Failed** **WebSocket Reconnecting** **Order Rejected** **Market Data Unavailable** The user should not be required to inspect Python console logs to understand normal operating errors. ### J. Windows 10 Requirement Is Mandatory The final deliverable must work on Windows 10 without requiring the client to install Python. Providing only Python source code, scripts, `.bat` files, or development instructions is **not considered final delivery**. Source code should still be delivered, but there must also be a usable packaged Windows program. ### K. Source Code Must Be Delivered The final project delivery should include the complete source code used to build the application. The client must not receive only an executable with no project source. ### L. Configuration Information Any required configuration, such as: * KIS App Key * App Secret * Account information * API environment settings should be entered through a reasonable configuration method. Sensitive credentials should not be permanently hard-coded into source files. ### M. Do Not Expose Credentials KIS API keys, secrets, account identifiers, or other sensitive credentials must not be: * Published * Uploaded to public repositories * Included in screenshots unnecessarily * Shared with third parties ### N. Code Should Be Maintainable The source code should be structured so another competent developer can understand and maintain it later. The project must not deliberately depend on the original developer continuing to operate the program. ### O. Completion Means Actual Operation A screen design alone is not completion. A video showing only the UI is not final completion. The completed application must perform the actual agreed functions using the KIS API. # 39. Required Final Deliverables The final delivery must include at minimum: * Complete source code * Windows 10 executable or installer * Required dependency packaging * Configuration instructions * KIS API connection functionality * Real-time WebSocket integration * Working dashboard * Real-time 1-minute ranking * Continued-rise tracking * Chart functionality * Order functionality * Watchlist functionality or approved alternative * Holdings functionality * Error handling * Basic installation/use instructions # 40. Development Budget The total fixed project budget is: **USD $400** Payment will be divided into three milestones. ### Milestone 1 — $100 Paid after the project begins and the agreed initial development stage has been completed. ### Milestone 2 — $100 Paid after the core program functionality has progressed enough that the client can verify the working functions through a development video. The video must demonstrate actual progress relevant to this specification. ### Milestone 3 — $200 Paid after final completion when: * The complete program has been delivered. * The agreed functions have been implemented. * The program operates normally. * Major errors have been corrected. * Windows 10 packaged execution is available. * The delivered program matches the agreed project specification. # 41. Performance Bonus / Tip If the completed application performs exceptionally well, is stable, accurately follows the specification, and demonstrates a high level of quality, the client may provide an additional **tip or bonus**. This is separate from the fixed $400 project budget and is discretionary. # 42. Development Schedule and Progress The developer should provide a realistic development period before beginning the project. The client is not requesting rushed development at the expense of quality. However, the project must also not remain unfinished indefinitely. If substantial delays occur, the developer should clearly explain: * The reason * Current development status * Remaining work * Revised expected completion time # 43. Contract Termination Conditions The client may terminate the contract before final completion if it becomes reasonably clear that the project cannot be completed according to the agreed specification. Examples include: * Repeated major errors * Failure to implement essential functions * Excessive unexplained delays * Abandonment of development * Development in a substantially different direction from the specification * Delivery of a program that cannot actually be used * Repeated failure to correct agreed defects * Replacement of requested functionality with unrelated functionality without approval # 44. Unauthorized Change of Development Direction This condition is particularly important. The developer is not being hired simply to create any stock program they personally consider appropriate. The developer is being hired to implement the program described in this specification. If the developer independently develops a substantially different program without obtaining prior approval and then asks the client to accept it, the client may reject that implementation. If the developer cannot or does not wish to follow the specification, they should not accept the project. # 45. Technical Suggestions Are Welcome The developer is allowed and encouraged to make technical recommendations. If a better or more stable method exists, the developer may explain it. However: **Proposal first → Client approval → Implementation** The developer should not: **Change first → Explain later** when the change materially affects an agreed function. # 46. Milestone and Termination Principle Payment should correspond to work actually completed under the agreed milestones. If the project is terminated before completion, unfinished future milestones should not automatically be considered completed. Any dispute should be evaluated based on: * The written specification * Completed milestone scope * Actual delivered work * Demonstrated functionality rather than merely the amount of time the developer has spent. # 47. Developer Application Requirement **Please read this entire specification before applying.** Do not apply based only on the project title. The developer should apply only if they believe they can implement the required functionality. The ideal developer should have experience with several of the following: * Python * Real-time APIs * WebSocket * REST APIs * Financial market data * Stock trading applications * Desktop application development * Windows application packaging * Trading order APIs * Asynchronous/event-driven programming Previous experience with: **Korea Investment & Securities Open API** is strongly preferred. If the developer has not used the KIS API before, they should review the official API documentation and determine whether they can complete this project **before accepting the contract**. # 48. Final Project Goal The final goal is not to create a complicated general-purpose trading platform. The goal is to create a **simple, fast, stable real-time stock-monitoring and trading tool** centered around one specific function: **Identify the stocks that are rising the fastest during the current 1-minute interval, track which of those stocks continue rising for the next several minutes, and allow the user to immediately inspect and trade those stocks from the same screen.** Accuracy of implementation, stability, and compliance with this specification are more important than adding unnecessary features. **Only developers who have carefully read this specification, understand the required behavior, and believe they can implement it should apply.**