A lightweight always-on-top clock overlay for crypto/futures trading. It sits on top of your trading window and shows the real time plus a 4-segment gauge that lets you read both the 1-hour candle and the 4-hour candle's progress at a glance, without switching tabs.
⬇ Download the latest .app — no Python or building required, just unzip and drag into Applications.
Clock & candle timer
- Always-on-top window that stays above your trading platform
- Live clock, down to the second, with a selectable display timezone
- 4-segment gauge that shows two timeframes at once: each segment fills up over one hour (so you can see the current 1H candle's progress), and all four together track the full 4-hour candle (always calculated in UTC, independent of the display timezone — matches exchange kline close times: UTC 00:00 / 04:00 / 08:00 / 12:00 / 16:00 / 20:00)
- Adjustable size, opacity, clock font weight (Ultralight–Black), and alert color
- Draggable — click and drag the box anywhere on screen
Alerts & alarms
- 5 minutes before every hourly segment closes, the border and clock digits flash for 10 seconds, then stay highlighted until the top of the hour, then snap back to normal with a sound alert
- Add up to 10 custom alarms (daily-repeating or one-time), editable/removable from the menu bar
- Custom alert color, selectable alert sound with instant preview, and a "Test Alert" menu item
Breaking News (optional, toggle from the menu bar)
- Keyword-filtered news ticker sourced from the Finnhub news API (
general+cryptocategories), polled every 10 seconds - Surfaces the most keyword-relevant headline from each polling window (falls back to the latest headline if nothing matches), then keeps cycling through everything matched in the last 10 minutes so the ticker keeps moving even when fresh news is sparse — old headlines age out automatically
- Plain white scrolling marquee, stacked above the Market Events panel when both are enabled
Market Events (optional, toggle from the menu bar)
- Economic calendar countdown (CPI, Core CPI, PPI, Core PPI, NFP, Unemployment, GDP, Retail Sales, Jobless Claims, PCE, Core PCE) sourced from the FRED (Federal Reserve Economic Data) API
- Shows a preview while the next release is more than 12 hours away, switches to a live countdown inside the 12-hour window, and automatically rolls over to the next upcoming release
- Groups same-day releases into multiple lines instead of only showing one
Breaking News and Market Events can both be on at once — Breaking News stacks on top, Market Events right below it:
Persistence
- Size, opacity, alert sound/color, timezone, font weight, alarms, and Market Events /
Breaking News toggles are all remembered across restarts
(saved to
~/.bitcoin_candle_clock_config.json)
- macOS
- Python 3.9+
- PySide6
git clone <this-repo-url>
cd trade_time
pip3 install -r requirements.txt
export FRED_API_KEY="your-fred-api-key" # optional, needed for Market Events
export FINNHUB_API_KEY="your-finnhub-api-key" # optional, needed for Breaking News
python3 main.pyA clock box appears near the top of the screen, and an icon shows up in the menu bar. All settings live under that menu bar icon. Both API keys are optional — the clock, candle timer, and alarms all work fully without them; only Market Events / Breaking News stay off until a key is set.
Don't want to build it yourself? Grab the pre-built app from Releases instead and skip everything below.
To build it yourself and get a double-clickable app instead of running from the terminal:
pip3 install -r requirements.txt # includes pyinstaller
pyinstaller TradeTime.specThe build reuses the bundled TradeTime.icns app icon automatically. The finished app is at
dist/TradeTime.app — copy it to /Applications to install:
cp -R dist/TradeTime.app /Applications/PyInstaller does not cross-compile — you need to run the build on macOS itself.
All settings live under the menu bar icon:
| Action | How |
|---|---|
| Move the clock | Click and drag the box |
| Resize | Menu bar icon → Size + / Size - |
| Adjust opacity | Menu bar icon → Opacity + / Opacity - |
| Change alert sound | Menu bar icon → Alert Sound (click to preview) |
| Change alert color | Menu bar icon → Alert Color |
| Change display timezone | Menu bar icon → Clock Timezone |
| Change clock font weight | Menu bar icon → Clock Font Weight |
| Test the alert | Menu bar icon → Test Alert |
| Add an alarm | Menu bar icon → Alarms → + Add Alarm... → enter HH:MM → choose Repeat Daily or Once |
| Edit/delete an alarm | Menu bar icon → Alarms → pick the alarm → Edit Time/Repeat or Delete |
| Toggle Market Events / Breaking News | Menu bar icon → Market Events → Economic Events / Breaking News |
| Set your FRED / Finnhub API key | Menu bar icon → Market Events → Set FRED API Key... / Set Finnhub API Key... |
| Quit | Menu bar icon → Quit |
On first launch, macOS may ask whether Terminal (or Python) can send notifications — allow it
so alert notifications work. You can toggle this later under
System Settings → Notifications. Alert sounds use the built-in macOS system sounds
(/System/Library/Sounds/*.aiff), so nothing extra needs to be installed.
All settings are stored at:
~/.bitcoin_candle_clock_config.json
Delete this file to reset everything to defaults.
Most tunable values live as constants near the top of main.py:
| Constant | What it controls |
|---|---|
BASE_WIDTH |
Base window width |
MIN_SCALE / MAX_SCALE / SCALE_STEP |
Size range and step |
MIN_OPACITY / MAX_OPACITY / OPACITY_STEP |
Opacity range and step |
ALERT_COLOR_CHOICES, BG_COLOR, SEG_ON_COLOR |
Colors |
BLINK_DURATION_SECONDS / BLINK_INTERVAL_MS |
Alert blink timing |
ALERT_VOLUME / SOUND_REPEAT |
Alert volume / repeat count |
TIMEZONE_CHOICES |
Timezones offered in the menu |
FONT_WEIGHT_CHOICES |
Font weights offered in the menu |
MAX_CUSTOM_ALARMS |
Max number of custom alarms (default 10) |
ECONOMIC_EVENTS_DEF |
Which FRED series are tracked for Market Events |
BREAKING_NEWS_KEYWORDS |
Keywords used to score/filter Breaking News headlines |
NEWS_POLL_INTERVAL_SEC / NEWS_ROTATION_WINDOW_SEC |
Breaking News polling interval and rotation window |
Market Events uses the FRED API and Breaking News uses the Finnhub API. Both have free tiers, and no key is ever stored in the source code, so it's safe to keep this repo public.
Both keys are optional. Without them, TradeTime runs completely normally — the clock, candle timer, and alarms are unaffected — only the Market Events / Breaking News toggles stay off (and show a one-time reminder) until a key is provided.
Option A — from the app menu (works for everyone, including a downloaded .app):
- Get a free key:
- FRED: fred.stlouisfed.org/docs/api/api_key.html
- Finnhub: finnhub.io/register
- Menu bar icon →
Market Events→Set FRED API Key.../Set Finnhub API Key...→ paste it in and confirm. - Turn on
Market Events→Economic Events/Breaking News.
The key is saved locally to ~/.bitcoin_candle_clock_config.json (same file as your other
settings) and remembered across restarts. If you try to enable either feature before setting a
key, TradeTime tells you exactly where to get one.
Option B — environment variables (source runs only):
export FRED_API_KEY="your-fred-api-key"
export FINNHUB_API_KEY="your-finnhub-api-key"
python3 main.pyA GUI app launched by double-clicking in Finder does not inherit environment variables from your shell profile — only apps launched from a terminal do. So if you build a
.appwith PyInstaller, environment variables generally won't reach it; use Option A (the menu) instead.
Sharing your built .app with many people: if you plan to distribute a build with your own keys baked in via Option B, keep in mind Finnhub's free tier caps out at 60 requests/minute total across everyone using that key — this app already uses ~12 requests/minute per running instance, so more than a handful of simultaneous users will start hitting rate limits. FRED's free tier (120 requests/minute) has much more headroom. For wider distribution, it's best to ship the
.appwith no keys baked in and let each person add their own via Option A.
- Some trading apps use special macOS window levels that can occasionally appear above the always-on-top clock.
If TradeTime is useful for your trading, you can support development from the app's menu bar:
❤️ Buy Me a Snack for 🐶 && 🐱 (KakaoPay for Korea-based users, USDT/BTC for everyone else).
MIT — free to use, modify, and redistribute, including commercially, as long as the original copyright notice is kept.