Windows Desktop App: Real-Time Stock Monitor via KIS Open API

# Development of a Real-Time 3-Minute Rising and Falling Stock Monitoring System Using the Korea Investment & Securities (KIS) Open API ## 1. Project Overview The purpose of this project is to develop a Windows application that monitors user-selected stocks in real time using actual market data from the Korea Investment & Securities (KIS) Open API. The program must calculate the percentage increase or decrease of each stock based on actual 3-minute candles and classify stocks according to how long their upward movement continues. **Real-Time → 3 Min → 6 Min → 9 Min → 12 Min → 15+ Min** This is not a stock-ordering or automated trading program. This contract focuses exclusively on watchlist management, real-time market monitoring, 3-minute candle calculations, rising/falling classification, real-time ranking, and candlestick chart display. ## 2. Important Requirements Before Applying Please read this entire specification before applying. Only developers who clearly understand what the client intends to build and have relevant experience should apply. Experience in the following areas is strongly preferred: * KIS Open API * REST API and WebSocket integration * Real-time stock-market data processing * Real-time OHLC and candle generation * Percentage calculations and dynamic rankings * State machines and stage-transition logic * Financial or brokerage applications * Windows desktop application development * Packaging Python applications as standalone Windows executables * Asynchronous and event-driven programming Do not apply if you do not know how to implement basic functions such as 3-minute candle generation, WebSocket data processing, stage transitions, real-time sorting, reconnection, and error recovery, and would need the client to explain the technical implementation. The client is not a developer and is not hiring someone in order to teach that person how to build the program. Questions about genuinely ambiguous requirements or specific KIS API limitations are acceptable. However, a developer who cannot independently determine and implement the fundamental technical design should not accept this project. ## 3. Development Schedule This project must be completed as quickly as reasonably possible. The client previously waited approximately 10 days for another developer, but the work was not properly completed. This caused wasted time, inconvenience, and additional work for the client. For this reason, the client does not want to wait for a long period without seeing actual development results. The applicant must clearly state: * The date on which work can begin * The exact number of days required to complete the entire program * The date on which the first API connection or development evidence can be shown * The date on which the final Windows application can be delivered Work must begin immediately after the contract starts. The developer must provide actual progress evidence at least every one or two days through a video, screenshot, working build, or source-code evidence. A simple message stating “I am working on it” will not be accepted as evidence of progress. The client may terminate the contract immediately if there is no actual progress within the agreed schedule, development has stopped, or it becomes reasonably clear that the developer cannot complete the program. The developer must not promise an unrealistically short schedule that cannot be met. Both fast completion and correct operation are required. ## 4. Final Application Format The completed program must be delivered as a standalone Windows 10 application. The user must not be required to install: * Python * Python libraries * An IDE * Command-line development tools * A separate development environment The final deliverables must include: * Complete source code * A Windows executable or installer * A distribution package containing all required runtimes and libraries * Build instructions * Installation and usage instructions * KIS API configuration instructions * A video showing actual operation * Connection and error-status logging * A maintainable, modular codebase Providing only source code or only an executable will not be considered complete delivery. ## 5. Features Excluded From This Contract The following functions are not included: * Buy and sell orders * Market and limit orders * Order confirmation, modification, or cancellation * Account balance or portfolio holdings * Execution or order history * Automated trading * Trading strategies * AI stock-price prediction * ChatGPT question or answer panels * GPT API integration * Additional indicators or analysis features not approved by the client The developer must not add unnecessary features that make the program more complicated. ## 6. KIS API Connection The main screen must include an `API Connection` button. When clicked, a separate configuration window must open and allow the user to enter: * KIS App Key * KIS App Secret * HTS User ID * Required API environment information * Information required for domestic and overseas market data The configuration window must include a `Save` button. After the information is saved, the program must attempt to connect to the actual KIS API. The normal screen must clearly display the connection status using an indicator light. * Connected: indicator illuminated * Disconnected: indicator turned off * Connecting: separate connecting status * Connection error: red or clear error status * Reconnecting: understandable reconnection message API keys, secrets, IDs, and account information must not be hard-coded into the source code. Sensitive information must not appear in videos, logs, public repositories, or materials shared with third parties. ## 7. Market Selection Only the currently selected market is displayed at the top. The default selection is `Domestic`. Clicking the market button must show: * Domestic * Overseas * All After the user selects an option, the selected market must appear on the button. Overseas and combined-market monitoring must be implemented only to the extent that the KIS API supports the necessary real-time data and concurrent subscriptions. If a KIS API restriction prevents exact implementation, the developer must explain the following before implementing an alternative: 1. The specific API limitation 2. The affected feature 3. Available alternatives 4. Whether the alternative changes the intended behavior The developer must not silently substitute a different implementation without the client’s approval. ## 8. Importing Watchlists When the KIS API connection is established, the application must automatically retrieve all watchlist groups saved in the user’s KIS account. Even when the account contains multiple watchlist groups, all stocks must be combined into one unified list inside the program. If the same stock appears in multiple groups, it must be displayed only once. Sorting: * Korean stocks: Korean alphabetical order * Overseas stocks: English alphabetical order The application must also provide: * Search by stock name * Search by stock code * Add a stock * Exclude a stock * Automatic duplicate removal * Local watchlist storage The locally stored watchlist must remain available even if the KIS watchlist cannot be retrieved. The watchlist and monitoring selections must remain saved after the program is closed and restarted. ## 9. Rising and Falling Monitoring Selection The watchlist area must contain two buttons: * Rise * Fall The selected button must be illuminated to show its active state. When `Rise` is selected, turning on a stock’s heart icon registers it for rising-stock monitoring. When `Fall` is selected, turning on a stock’s heart icon registers it for falling-stock monitoring. The same stock may be registered for both rising and falling monitoring simultaneously. The Rise and Fall heart states must be stored independently. Removing a stock from one monitoring mode must not remove it from the other mode. ## 10. Real-Time Column The Real-Time column must always display every stock whose Rise heart is enabled. The number of stocks must not be limited to a Top 10 list. If the user registers one stock, one stock is displayed. If the user registers 40 stocks, all 40 stocks must be displayed. A stock must remain visible in the Real-Time column even after it enters the 3-minute, 6-minute, 9-minute, 12-minute, or 15+ minute stage. The Real-Time column is the permanent monitoring list for all Rise-selected stocks. A stock is removed from this monitoring list only when its Rise heart is turned off. ## 11. Decline Column The Decline column must display all stocks whose Fall heart is enabled. It must calculate each stock’s real-time decline percentage using the current 3-minute candle’s opening price as the reference. Stocks with the largest decline must be displayed first. Example: * Stock A: -2.00% * Stock B: -1.00% Stock A must appear above Stock B. The Decline column does not use duration stages such as 3, 6, or 9 minutes. A stock remains monitored for declines while its Fall heart remains enabled. ## 12. Market-Aligned 3-Minute Candles All rising and falling determinations must use 3-minute candles. The candles must not begin from the moment the user clicks the Start button. They must be aligned with the actual market’s official 3-minute intervals. Domestic regular-session example: * 09:00:00–09:02:59 * 09:03:00–09:05:59 * 09:06:00–09:08:59 If the program starts at 09:01:20, it must not use the 09:01:20 price as the candle’s opening price. It must obtain the actual opening price of the 3-minute candle that began at 09:00:00 using valid KIS data. Pre-market, regular-market, after-hours, and overseas-market sessions must follow the actual trading hours and candle boundaries supported by KIS. The program must not generate artificial prices or candles when valid data is unavailable. ## 13. Percentage Calculation The following formula must be used: **Change (%) = (Current Price − Current 3-Minute Candle Open) ÷ Current 3-Minute Candle Open × 100** Ranking must be based on percentage movement, not the absolute price difference. Example: * Stock A: KRW 1,000 → KRW 1,010 = +1.00% * Stock B: KRW 100,000 → KRW 100,500 = +0.50% Even though Stock B increased by a larger monetary amount, Stock A must rank higher because its percentage increase is greater. When a new 3-minute candle begins, the new opening price becomes the 0% reference. ## 14. Rising Stages The rising stages are: **Real-Time → 3 Min → 6 Min → 9 Min → 12 Min → 15+ Min** Stage movement is determined by comparing the opening and closing prices of each completed 3-minute candle. A stock may move by only one stage for each completed candle. ### Rising Candle If the closing price is higher than the opening price, the stock moves up one stage. * Real-Time + rising candle → 3 Min * 3 Min + rising candle → 6 Min * 6 Min + rising candle → 9 Min * 9 Min + rising candle → 12 Min * 12 Min + rising candle → 15+ Min * 15+ Min + rising candle → remain in 15+ Min ### Flat Candle If the closing price equals the opening price, the stock remains at its current stage. A stock that does not move must not advance to a higher stage. ### Falling Candle If the closing price is lower than the opening price, the stock moves down one stage. * 15+ Min + falling candle → 12 Min * 12 Min + falling candle → 9 Min * 9 Min + falling candle → 6 Min * 6 Min + falling candle → 3 Min * 3 Min + falling candle → removed from the rising-stage columns After removal from the 3-minute stage, the stock still remains visible in the Real-Time column. A falling stock must not immediately lose every stage. It may move down by only one stage per completed 3-minute candle. The previous 1-minute logic and 5-second decline-confirmation rule are not used. ## 15. Real-Time Ranking The following columns must be dynamically sorted by the current 3-minute percentage increase, from highest to lowest: * Real-Time * 3 Min * 6 Min * 9 Min * 12 Min * 15+ Min Rankings must update immediately while the 3-minute candle is still forming. When a new 3-minute candle begins, percentage calculations must restart using the new opening price. The Decline column must be sorted by the size of the decline, with the largest decline displayed first. ## 16. Charts Each main column must display a genuine candlestick chart. A random line graphic must not be substituted for an actual chart. When the user clicks a stock, the corresponding stock chart must appear immediately. The selected chart must remain displayed for 10 seconds after the most recent click. If another stock is clicked during those 10 seconds, the timer restarts from the new click. If no additional stock is clicked for 10 seconds, the chart automatically changes to the stock currently ranked first in that column. The selected stock may be highlighted using a border, background color, or illuminated state. Minor UI details such as highlighting colors, spacing, and scrolling may be determined by the developer, provided that the agreed functionality is not changed. ## 17. Screen Layout The main columns must appear in the following order from left to right: **Watchlist → Decline → 15+ Min → 12 Min → 9 Min → 6 Min → 3 Min → Real-Time** The Real-Time column must be positioned on the far right. The top area must contain: * API Connection * Current Time * Start * Stop No order panel or ChatGPT panel should be included. Both Korean and English UI versions must be provided. They must have identical functionality and structure. ## 18. Start and Stop API connection and monitoring must operate independently. When the API is connected and the user clicks `Start`, the program begins: * Real-time market monitoring * 3-minute candle calculation * Percentage calculations * Dynamic ranking * Stage determination * Chart updates If the user clicks Start while the API is disconnected, monitoring must not begin. The program must show an `API Connection Required` message. When the user clicks `Stop`, monitoring stops. The following information must be reset: * Current 3-minute candle calculation * 3-minute stage * 6-minute stage * 9-minute stage * 12-minute stage * 15+ minute stage * Current percentage calculations * Automatic chart-selection state The following information must remain saved: * API configuration * Watchlist * Rise heart selections * Fall heart selections When monitoring starts again, registered stocks must be evaluated again beginning from the Real-Time state. ## 19. Disconnection and Error Handling The application must handle: * API authentication failure * WebSocket disconnection * Network interruption * Missing market data * KIS request limits * Invalid responses * Application restart * No market data When the connection is lost, the program must not continue calculations using stale prices. The program must not generate artificial prices merely to keep the interface moving. When disconnected, calculations must stop and the application should attempt reconnection. The user must see understandable status messages such as: * KIS Connection Failed * Reconnecting WebSocket * No Market Data * Check API Credentials * Real-Time Calculation Stopped The program must not require the user to inspect a Python console to understand an ordinary operational problem. ## 20. Development Simulation Temporary simulation data may be used during development. However, the interface and video must clearly state `Simulation Data`. The final program and final test must use actual KIS API market data. Presenting fake or simulated data as actual KIS real-time data constitutes a material breach and grounds for immediate termination. ## 21. Code Structure and Maintainability The codebase must separate the following components: * API authentication and connection * WebSocket market-data processing * Stock and watchlist management * 3-minute candle generation * Percentage calculations * Stage-state management * Dynamic ranking * Charts * User interface * Configuration storage * Error and log management Another competent developer must be able to understand and maintain the source code. The application must not permanently depend on the original developer for ordinary operation. The stock-selection and market-data components should be designed separately so that a ChatGPT analysis program may be integrated in a future project. ## 22. Stage 1 — Complete Program Development The total fixed project price is **USD 300**. At the beginning of the contract, **USD 100** will be funded in the active Upwork milestone. This is not an advance payment to the developer. It is project funding held by Upwork. Stage 1 does not mean delivering only a prototype or UI. The developer must complete the entire agreed program and provide: * The completed Windows application * Complete source code * A video showing actual functionality * Installation and usage instructions * API configuration instructions * Build instructions * Materials that allow the client and ChatGPT to review the source-code structure and implementation A video showing only the interface is not completion evidence. The video must demonstrate: * API connection * Watchlist retrieval * Rise and Fall monitoring registration * Actual 3-minute candle calculation * Real-time percentage ranking * Rising-stage transitions * Start and Stop * Reset behavior * Chart selection * Connection-error handling Stage 1 is completed only after the client reviews the executable, video, and source code and confirms that the full program has been implemented according to the specification. No USD 100 payment will be released upon Stage 1 approval. ## 23. Additional USD 200 Funding After Stage 1 passes, the active milestone will be increased from USD 100 to a total of USD 300, and the client will fund the additional USD 200 through Upwork. The additional USD 200 is not payment for Stage 1. It is additional project funding deposited before the final market test. If the client’s Upwork account does not permit an active milestone increase, both parties must agree in writing to a platform-compliant payment structure before continuing. No payment will be made outside Upwork. ## 24. Stage 2 — One Trading-Day Market Test Stage 2 consists of one full trading-day test using valid, actual KIS market data. “One trading day” does not merely mean that one calendar day has passed. The following functions must be demonstrated and verified under live market conditions: * API connection and reconnection * KIS watchlist integration * Local watchlist addition and exclusion * Simultaneous Rise and Fall monitoring * Market-aligned 3-minute candles * Dynamic rising and falling rankings * 3, 6, 9, 12, and 15+ minute stage transitions * Rising, flat, and falling candle decisions * Start, Stop, and reset behavior * Chart display * Market-data interruption handling * General application stability * Confirmation that hidden simulation data is not being used The developer must complete sufficient testing before claiming that the program is ready for Stage 2. ## 25. Payment Conditions The full **USD 300** will be released as one payment only after both Stage 1 and Stage 2 have passed and the contract is approved as fully completed. There will be no intermediate payment. Stage 1 approval is a condition for funding the additional USD 200, not a condition for releasing the initial USD 100. The developer must not submit an official Upwork payment request before Stage 2 is complete, because an official submission may begin Upwork’s automatic payment-review period. All payments and deliverable submissions must remain within Upwork. ## 26. Completion Criteria The project is complete only when all the following conditions are satisfied: * Every agreed function is implemented * Actual KIS API data is used * The application runs on Windows 10 * Python installation is not required * Complete source code is provided * A Windows executable or installer is provided * A working demonstration video is provided * Installation and usage instructions are provided * The one-trading-day market test is passed * No major functional errors remain * The delivered application materially matches this specification Time spent by the developer does not by itself prove completion. A finished UI alone is not a completed program. Completion will be determined by delivered materials and demonstrated functionality. ## 27. No Unauthorized Changes The developer must not independently change the program’s core operation. The following requirements must not be changed without prior written approval: * Use of 3-minute candles * Alignment with actual market candle times * Rising, flat, and falling determinations * One-stage movement per completed candle * Main column order * Permanent display of all Rise-monitored stocks in Real-Time * Simultaneous Rise and Fall monitoring * Use of actual KIS market data * Delivery of complete source code and a Windows application If the developer recommends a different approach, the following process must be followed: **Written Proposal → Explanation of Differences → Client Approval → Implementation** Changing the program first and explaining later is not permitted. ## 28. Immediate Contract Termination The client may immediately terminate the contract if any of the following occurs: * The developer materially misrepresents experience, skills, or portfolio work * It becomes clear that the developer does not understand the core logic * The developer repeatedly asks the client to design basic technical implementation * The agreed schedule passes without actual evidence of development * Development stops or the developer becomes unresponsive * The developer changes the program’s core direction without approval * The 3-minute system is replaced with another timeframe or an ordinary daily-ranking system * A requested function is replaced with an unrelated function * Fake or simulated data is presented as actual KIS data * Manipulated videos or inaccurate progress claims are provided * API keys, secrets, IDs, or client information are exposed * Project source code is uploaded to a public repository without permission * The developer refuses to provide the complete source code or Windows executable * Major functional errors repeatedly occur * It becomes clear that the developer lacks the ability to complete the program within a reasonable period * Third-party code or assets are used illegally * A material contractual or trust issue arises A single minor issue such as a color, spacing, or easily corrected typographical error will not automatically cause termination. However, repeated minor problems, refusal to correct them, or dishonest explanations may constitute a material breach. Incomplete future work will not be treated as completed after termination. Unreleased project funds will be handled according to the actual deliverables and Upwork’s dispute procedures. ## 29. Confidentiality and Ownership The developer must not disclose: * KIS API keys * App Secret * HTS User ID * Account information * Program source code * Test materials * Screens or business information The developer must receive written approval before publicly displaying this project in a portfolio. After final payment, the client will receive the rights to use and modify the source code and deliverables created specifically for this project. Third-party libraries remain subject to their original licenses. The developer must identify all external libraries and applicable licenses. ## 30. Screening Questions Please answer every question: 1. Have you read this specification from beginning to end? 2. Explain in your own words what the client is trying to build. 3. Have you used the KIS Open API in a real project? 4. Have you processed real-time stock data through WebSocket? 5. Have you generated real-time OHLC or 3-minute candles? 6. Have you implemented ranking and stage-transition logic? 7. Can you provide a video, screenshot, or code evidence from a similar program you personally developed? 8. Can you build a standalone Windows 10 executable? 9. When can you begin? 10. Exactly how many days do you need to complete the entire program? 11. When can you provide the first actual development evidence? 12. Do you agree to provide both the complete source code and Windows executable? 13. Do you accept the USD 300 funding and payment structure described in this specification? 14. Do you accept that the contract may be terminated if a material contractual problem or lack of technical ability becomes evident? Copied proposals, general introductions, or responses that do not specifically answer these questions will not be reviewed. ## 31. Developer’s Required Pre-Contract Confirmation Before accepting the contract, the developer must confirm the following in writing: “I have read this entire specification and understand the application the client intends to build. I possess the skills and experience required to implement KIS real-time data processing, market-aligned 3-minute candles, percentage calculations, dynamic ranking, rising/flat/falling determinations, stage transitions, watchlist integration, simultaneous Rise and Fall monitoring, chart display, and standalone Windows packaging. I can complete the program without requiring the client to design the fundamental technical implementation for me. If I discover a KIS API restriction or need for a material change, I will explain it in writing and obtain approval before implementation. I agree to provide the complete source code, Windows executable, working video, build instructions, and usage instructions. I understand and accept that the client may terminate the contract if a material contractual problem, misrepresented experience, insufficient technical ability, unauthorized change, hidden simulation, or major schedule violation is discovered.” ## 32. Final Objective The objective is not to build a complicated general-purpose trading platform. The objective is to create a simple, fast, stable, and reliable Windows application that monitors user-selected stocks using actual KIS market data and accurately displays their rising-duration stages based on market-aligned 3-minute candles. Correct implementation, rapid completion, actual operation, stability, and compliance with this specification are more important than unnecessary additional features. Only apply if you have read the entire specification, understand the required behavior, possess the necessary experience, and can complete the actual program within the agreed schedule.