coinwatch-cli 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- coinwatch_cli-0.1.0/.github/workflows/ci.yml +33 -0
- coinwatch_cli-0.1.0/.gitignore +30 -0
- coinwatch_cli-0.1.0/LICENSE +21 -0
- coinwatch_cli-0.1.0/PKG-INFO +250 -0
- coinwatch_cli-0.1.0/README.md +225 -0
- coinwatch_cli-0.1.0/config.example.toml +51 -0
- coinwatch_cli-0.1.0/pyproject.toml +45 -0
- coinwatch_cli-0.1.0/src/coinwatch/__init__.py +4 -0
- coinwatch_cli-0.1.0/src/coinwatch/alert.py +76 -0
- coinwatch_cli-0.1.0/src/coinwatch/cli.py +145 -0
- coinwatch_cli-0.1.0/src/coinwatch/config.py +76 -0
- coinwatch_cli-0.1.0/src/coinwatch/market.py +44 -0
- coinwatch_cli-0.1.0/src/coinwatch/notifier.py +82 -0
- coinwatch_cli-0.1.0/src/coinwatch/report.py +36 -0
- coinwatch_cli-0.1.0/src/coinwatch/sources/__init__.py +8 -0
- coinwatch_cli-0.1.0/src/coinwatch/sources/base.py +69 -0
- coinwatch_cli-0.1.0/src/coinwatch/sources/binance.py +60 -0
- coinwatch_cli-0.1.0/src/coinwatch/sources/coingecko.py +42 -0
- coinwatch_cli-0.1.0/src/coinwatch/sources/okx.py +50 -0
- coinwatch_cli-0.1.0/src/coinwatch/web.py +90 -0
- coinwatch_cli-0.1.0/tests/test_cli.py +28 -0
- coinwatch_cli-0.1.0/tests/test_sources.py +93 -0
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
branches: [main]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
test:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
strategy:
|
|
13
|
+
fail-fast: false
|
|
14
|
+
matrix:
|
|
15
|
+
python-version: ["3.11", "3.12", "3.13"]
|
|
16
|
+
steps:
|
|
17
|
+
- uses: actions/checkout@v4
|
|
18
|
+
|
|
19
|
+
- name: Set up Python ${{ matrix.python-version }}
|
|
20
|
+
uses: actions/setup-python@v5
|
|
21
|
+
with:
|
|
22
|
+
python-version: ${{ matrix.python-version }}
|
|
23
|
+
|
|
24
|
+
- name: Install (with dev extras)
|
|
25
|
+
run: |
|
|
26
|
+
python -m pip install --upgrade pip
|
|
27
|
+
python -m pip install -e ".[dev]"
|
|
28
|
+
|
|
29
|
+
- name: Run tests
|
|
30
|
+
run: python -m pytest -q
|
|
31
|
+
|
|
32
|
+
- name: CLI smoke check
|
|
33
|
+
run: python -m coinwatch.cli init && python -m coinwatch.cli --help
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
__pycache__/
|
|
2
|
+
*.py[cod]
|
|
3
|
+
*.egg-info/
|
|
4
|
+
build/
|
|
5
|
+
dist/
|
|
6
|
+
.eggs/
|
|
7
|
+
|
|
8
|
+
# Virtual environments
|
|
9
|
+
.venv/
|
|
10
|
+
venv/
|
|
11
|
+
env/
|
|
12
|
+
|
|
13
|
+
# Local / secret-bearing config — NEVER commit these
|
|
14
|
+
config.toml
|
|
15
|
+
*.local.toml
|
|
16
|
+
secrets.toml
|
|
17
|
+
.coinwatch_state.json
|
|
18
|
+
|
|
19
|
+
# Tooling
|
|
20
|
+
.pytest_cache/
|
|
21
|
+
.coverage
|
|
22
|
+
htmlcov/
|
|
23
|
+
.mypy_cache/
|
|
24
|
+
.ruff_cache/
|
|
25
|
+
.DS_Store
|
|
26
|
+
Thumbs.db
|
|
27
|
+
|
|
28
|
+
# IDE
|
|
29
|
+
.vscode/
|
|
30
|
+
.idea/
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 MT
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,250 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: coinwatch-cli
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Local-first crypto market monitor & alert engine. Multi-source failover, zero third-party dependencies.
|
|
5
|
+
Project-URL: Homepage, https://github.com/AlfredoJamesPacino/coinwatch
|
|
6
|
+
Project-URL: Repository, https://github.com/AlfredoJamesPacino/coinwatch
|
|
7
|
+
Project-URL: Issues, https://github.com/AlfredoJamesPacino/coinwatch/issues
|
|
8
|
+
Author: MT
|
|
9
|
+
License: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: alerting,bitcoin,cli,crypto,monitoring,price-tracker
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Topic :: Office/Business :: Financial :: Investment
|
|
21
|
+
Requires-Python: >=3.11
|
|
22
|
+
Provides-Extra: dev
|
|
23
|
+
Requires-Dist: pytest>=7.0; extra == 'dev'
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
|
|
26
|
+
# CoinWatch
|
|
27
|
+
|
|
28
|
+
[](https://github.com/AlfredoJamesPacino/coinwatch/actions/workflows/ci.yml)
|
|
29
|
+
[](https://opensource.org/licenses/MIT)
|
|
30
|
+
[](https://www.python.org/downloads/)
|
|
31
|
+
|
|
32
|
+
**本地优先的加密货币行情监控与告警引擎。**
|
|
33
|
+
|
|
34
|
+
多数据源自动故障切换,标准库零依赖,调度无关(cron / Windows 任务计划 / WorkBuddy 自动化都能驱动)。
|
|
35
|
+
|
|
36
|
+
> CoinWatch 只做**数据监控与告警**,不提供任何投资建议。加密货币市场高风险,请自行判断。
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## 为什么要有它
|
|
41
|
+
|
|
42
|
+
盯盘的实际痛点,其实就三个:
|
|
43
|
+
|
|
44
|
+
1. **单一数据源不可靠** —— CoinGecko 免费额度会限流,Binance 在某些地区被墙,OKX 偶尔抖动。挂了就什么都看不到。
|
|
45
|
+
2. **不想一直开着交易所 App** —— 只想在该动的时候被叫一声。
|
|
46
|
+
3. **担心凭证乱飞** —— 没人希望自己的密钥躺在某个不知名软件的数据库里。
|
|
47
|
+
|
|
48
|
+
CoinWatch 的设计回答就是:**多源兜底 + 阈值告警 + 完全不需要交易所密钥**(只用公开行情接口)。
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## 特性
|
|
53
|
+
|
|
54
|
+
- 🔁 **多源故障切换**:CoinGecko → Binance → OKX 逐级兜底,按币种补齐,单源挂掉不影响整体
|
|
55
|
+
- 🔔 **多类告警**:24h 涨跌幅、上下方价格突破、成交量异动(滚动基线)
|
|
56
|
+
- 📡 **多渠道通知**:终端日志 / Telegram / Discord / Email(SMTP)
|
|
57
|
+
- 🌐 **本地面板**:内置 Web Dashboard(每 60s 自动刷新),只监听 `127.0.0.1`
|
|
58
|
+
- 📦 **零第三方依赖**:核心只用 Python 标准库,克隆下来就能跑
|
|
59
|
+
- 🕒 **调度无关**:不自带定时器,交给 cron / 任务计划 / WorkBuddy
|
|
60
|
+
- 🧩 **易扩展**:新增数据源只需实现 `Source.fetch()`
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## 快速开始
|
|
65
|
+
|
|
66
|
+
要求 **Python 3.11+**(用到标准库 `tomllib`)。
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
git clone https://github.com/AlfredoJamesPacino/coinwatch.git
|
|
70
|
+
cd coinwatch
|
|
71
|
+
|
|
72
|
+
# 安装(可选;不装也能跑)
|
|
73
|
+
pip install -e .
|
|
74
|
+
|
|
75
|
+
# 确认版本
|
|
76
|
+
coinwatch --version
|
|
77
|
+
|
|
78
|
+
# 生成配置
|
|
79
|
+
coinwatch init # 从 config.example.toml 复制出 config.toml
|
|
80
|
+
# 编辑 config.toml,设置自选币种、阈值、通知渠道
|
|
81
|
+
|
|
82
|
+
# 跑一次
|
|
83
|
+
coinwatch check
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
不想安装的话,直接用模块方式运行:
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
PYTHONPATH=src python -m coinwatch.cli check
|
|
90
|
+
PowerShell: $env:PYTHONPATH="src"; python -m coinwatch.cli check
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
首屏输出类似:
|
|
94
|
+
|
|
95
|
+
```
|
|
96
|
+
=== CoinWatch 行情快照 ===
|
|
97
|
+
|
|
98
|
+
SYMBOL PRICE 24H SOURCE
|
|
99
|
+
----------------------------------------------
|
|
100
|
+
BTC $67,432.10 +2.31% coingecko
|
|
101
|
+
ETH $3,210.55 -1.04% binance
|
|
102
|
+
SOL $178.22 +6.77% coingecko
|
|
103
|
+
|
|
104
|
+
无告警。
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## 配置
|
|
110
|
+
|
|
111
|
+
编辑 `config.toml`(**该文件已被 `.gitignore` 忽略,别提交**):
|
|
112
|
+
|
|
113
|
+
```toml
|
|
114
|
+
[watchlist]
|
|
115
|
+
bitcoin = "BTC" # 左边是 CoinGecko coin id(小写)
|
|
116
|
+
ethereum = "ETH"
|
|
117
|
+
solana = "SOL"
|
|
118
|
+
|
|
119
|
+
[thresholds]
|
|
120
|
+
change_pct_alert = 5.0 # |24h 涨跌| >= 5% 就告警,0 关闭
|
|
121
|
+
volume_spike_pct = 0.0 # 成交量异动阈值,0 关闭
|
|
122
|
+
price_above = { "bitcoin" = 200000 } # 突破上方
|
|
123
|
+
price_below = { "ethereum" = 500 } # 跌破下方
|
|
124
|
+
|
|
125
|
+
[notify]
|
|
126
|
+
log = true
|
|
127
|
+
telegram_token = "" # 从 @BotFather 拿
|
|
128
|
+
telegram_chat_id = ""
|
|
129
|
+
discord_webhook = ""
|
|
130
|
+
email_smtp_host = "" # 留空即关闭邮件通道
|
|
131
|
+
email_smtp_user = ""
|
|
132
|
+
email_smtp_pass = "" # 建议用应用专用密码
|
|
133
|
+
email_to = ""
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
**安全注意**: bot token 和 SMTP 密码只存在本地 `config.toml` 里,**从不随代码提交**。仓库只提交脱敏的 `config.example.toml`。
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## 命令
|
|
141
|
+
|
|
142
|
+
| 命令 | 作用 |
|
|
143
|
+
| --- | --- |
|
|
144
|
+
| `coinwatch check` | 拉一次快照,评估阈值,有告警就推送 |
|
|
145
|
+
| `coinwatch list` | 只列出自选行情,不触发告警 |
|
|
146
|
+
| `coinwatch watch [--interval N]` | 循环监控,默认读配置里的 `interval_seconds` |
|
|
147
|
+
| `coinwatch web` | 启动本地面板,默认 `http://127.0.0.1:8080` |
|
|
148
|
+
| `coinwatch init` | 从示例生成 `config.toml` |
|
|
149
|
+
|
|
150
|
+
所有命令都支持 `--config <path>` 指定配置文件位置;`coinwatch --version` 输出版本号。
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
154
|
+
## 网络与区域可用性
|
|
155
|
+
|
|
156
|
+
CoinWatch 只用公开行情接口,但这些接口在**部分地区/网络下可能直连不通**(Binance、OKX、CoinGecko 均有被拦或限流的情况)。
|
|
157
|
+
|
|
158
|
+
遇到这种情况时,CoinWatch **不会假装没数据**,而会把失败原因打出来:
|
|
159
|
+
|
|
160
|
+
```
|
|
161
|
+
行情源不可用:
|
|
162
|
+
! coingecko: https://api.coingecko.com/... -> Tunnel connection failed: 502 Bad Gateway
|
|
163
|
+
! binance: https://api.binance.com/... -> Tunnel connection failed: 502 Bad Gateway
|
|
164
|
+
-> 常见原因:本机网络到该 API 不通(部分地区需代理)、或被限流。
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
处理方式:给本机配好代理即可,`urllib` 会自动读取 `HTTP_PROXY` / `HTTPS_PROXY` 环境变量:
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
export HTTPS_PROXY=http://127.0.0.1:7890
|
|
171
|
+
coinwatch check
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
由于 3 个源会互相兜底,即使只有一个能通,快照依然完整。
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
## 定时执行
|
|
179
|
+
|
|
180
|
+
CoinWatch **不自带守护进程**,这是刻意的——交给更专业的调度器,也更省资源。
|
|
181
|
+
|
|
182
|
+
**Linux / macOS(cron,每 5 分钟):**
|
|
183
|
+
|
|
184
|
+
```cron
|
|
185
|
+
*/5 * * * * cd /path/to/coinwatch && python -m coinwatch.cli check >> coinwatch.log 2>&1
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
**Windows(任务计划程序):**
|
|
189
|
+
|
|
190
|
+
```powershell
|
|
191
|
+
$action = New-ScheduledTaskAction -Execute "python" `
|
|
192
|
+
-Argument "-m coinwatch.cli check" -WorkingDirectory "C:\path\to\coinwatch"
|
|
193
|
+
$trigger = New-ScheduledTaskTrigger -RepetitionInterval (New-TimeSpan -Minutes 5) -Once -At (Get-Date)
|
|
194
|
+
Register-ScheduledTask -TaskName "CoinWatch" -Action $action -Trigger $trigger
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
**WorkBuddy 自动化:** 创建一条定时任务,指令为「运行 `coinwatch check` 」,即可把告警接进 AI 工作流。
|
|
198
|
+
|
|
199
|
+
---
|
|
200
|
+
|
|
201
|
+
## 架构
|
|
202
|
+
|
|
203
|
+
```
|
|
204
|
+
src/coinwatch/
|
|
205
|
+
├── config.py # TOML 加载与阈值访问
|
|
206
|
+
├── market.py # Market:多源聚合 + 按币种 failover
|
|
207
|
+
├── alert.py # 阈值评估,成交量基线持久化
|
|
208
|
+
├── notifier.py # log / Telegram / Discord / Email
|
|
209
|
+
├── report.py # 文本 & JSON 渲染
|
|
210
|
+
├── web.py # 标准库 http.server 面板
|
|
211
|
+
├── cli.py # argparse 入口
|
|
212
|
+
└── sources/
|
|
213
|
+
├── base.py # Quote / Source 抽象
|
|
214
|
+
├── coingecko.py
|
|
215
|
+
├── binance.py
|
|
216
|
+
└── okx.py
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
数据流:
|
|
220
|
+
|
|
221
|
+
```
|
|
222
|
+
config.toml → Market.snapshot() → alert.evaluate() → notifier.notify()
|
|
223
|
+
↑
|
|
224
|
+
CoinGecko → Binance → OKX(逐级兜底)
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
**新增一个数据源**:继承 `Source`,实现 `fetch(coin_ids, symbols) -> dict[str, Quote]`,然后丢进 `Market(sources=[...])`。解析逻辑请配一个 `monkeypatch` 单测,参考 `tests/test_sources.py`。
|
|
228
|
+
|
|
229
|
+
---
|
|
230
|
+
|
|
231
|
+
## 开发
|
|
232
|
+
|
|
233
|
+
```bash
|
|
234
|
+
pip install -e ".[dev]"
|
|
235
|
+
pytest -q
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
测试不访问网络——用 `monkeypatch` 打桩 `_get_json` 来验证解析逻辑,所以 CI 里跑得又快又稳。
|
|
239
|
+
|
|
240
|
+
---
|
|
241
|
+
|
|
242
|
+
## 免责声明
|
|
243
|
+
|
|
244
|
+
本项目**仅用于行情监控与告警**,不提供任何投资建议、买卖信号或收益承诺。所有数据来自第三方公开 API,可能延迟或不准确,请以交易所实际成交为准。加密货币市场波动剧烈、风险极高,请自行判断并控制风险。
|
|
245
|
+
|
|
246
|
+
---
|
|
247
|
+
|
|
248
|
+
## License
|
|
249
|
+
|
|
250
|
+
[MIT](LICENSE) © 2026 MT
|
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
# CoinWatch
|
|
2
|
+
|
|
3
|
+
[](https://github.com/AlfredoJamesPacino/coinwatch/actions/workflows/ci.yml)
|
|
4
|
+
[](https://opensource.org/licenses/MIT)
|
|
5
|
+
[](https://www.python.org/downloads/)
|
|
6
|
+
|
|
7
|
+
**本地优先的加密货币行情监控与告警引擎。**
|
|
8
|
+
|
|
9
|
+
多数据源自动故障切换,标准库零依赖,调度无关(cron / Windows 任务计划 / WorkBuddy 自动化都能驱动)。
|
|
10
|
+
|
|
11
|
+
> CoinWatch 只做**数据监控与告警**,不提供任何投资建议。加密货币市场高风险,请自行判断。
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## 为什么要有它
|
|
16
|
+
|
|
17
|
+
盯盘的实际痛点,其实就三个:
|
|
18
|
+
|
|
19
|
+
1. **单一数据源不可靠** —— CoinGecko 免费额度会限流,Binance 在某些地区被墙,OKX 偶尔抖动。挂了就什么都看不到。
|
|
20
|
+
2. **不想一直开着交易所 App** —— 只想在该动的时候被叫一声。
|
|
21
|
+
3. **担心凭证乱飞** —— 没人希望自己的密钥躺在某个不知名软件的数据库里。
|
|
22
|
+
|
|
23
|
+
CoinWatch 的设计回答就是:**多源兜底 + 阈值告警 + 完全不需要交易所密钥**(只用公开行情接口)。
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## 特性
|
|
28
|
+
|
|
29
|
+
- 🔁 **多源故障切换**:CoinGecko → Binance → OKX 逐级兜底,按币种补齐,单源挂掉不影响整体
|
|
30
|
+
- 🔔 **多类告警**:24h 涨跌幅、上下方价格突破、成交量异动(滚动基线)
|
|
31
|
+
- 📡 **多渠道通知**:终端日志 / Telegram / Discord / Email(SMTP)
|
|
32
|
+
- 🌐 **本地面板**:内置 Web Dashboard(每 60s 自动刷新),只监听 `127.0.0.1`
|
|
33
|
+
- 📦 **零第三方依赖**:核心只用 Python 标准库,克隆下来就能跑
|
|
34
|
+
- 🕒 **调度无关**:不自带定时器,交给 cron / 任务计划 / WorkBuddy
|
|
35
|
+
- 🧩 **易扩展**:新增数据源只需实现 `Source.fetch()`
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## 快速开始
|
|
40
|
+
|
|
41
|
+
要求 **Python 3.11+**(用到标准库 `tomllib`)。
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
git clone https://github.com/AlfredoJamesPacino/coinwatch.git
|
|
45
|
+
cd coinwatch
|
|
46
|
+
|
|
47
|
+
# 安装(可选;不装也能跑)
|
|
48
|
+
pip install -e .
|
|
49
|
+
|
|
50
|
+
# 确认版本
|
|
51
|
+
coinwatch --version
|
|
52
|
+
|
|
53
|
+
# 生成配置
|
|
54
|
+
coinwatch init # 从 config.example.toml 复制出 config.toml
|
|
55
|
+
# 编辑 config.toml,设置自选币种、阈值、通知渠道
|
|
56
|
+
|
|
57
|
+
# 跑一次
|
|
58
|
+
coinwatch check
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
不想安装的话,直接用模块方式运行:
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
PYTHONPATH=src python -m coinwatch.cli check
|
|
65
|
+
PowerShell: $env:PYTHONPATH="src"; python -m coinwatch.cli check
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
首屏输出类似:
|
|
69
|
+
|
|
70
|
+
```
|
|
71
|
+
=== CoinWatch 行情快照 ===
|
|
72
|
+
|
|
73
|
+
SYMBOL PRICE 24H SOURCE
|
|
74
|
+
----------------------------------------------
|
|
75
|
+
BTC $67,432.10 +2.31% coingecko
|
|
76
|
+
ETH $3,210.55 -1.04% binance
|
|
77
|
+
SOL $178.22 +6.77% coingecko
|
|
78
|
+
|
|
79
|
+
无告警。
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## 配置
|
|
85
|
+
|
|
86
|
+
编辑 `config.toml`(**该文件已被 `.gitignore` 忽略,别提交**):
|
|
87
|
+
|
|
88
|
+
```toml
|
|
89
|
+
[watchlist]
|
|
90
|
+
bitcoin = "BTC" # 左边是 CoinGecko coin id(小写)
|
|
91
|
+
ethereum = "ETH"
|
|
92
|
+
solana = "SOL"
|
|
93
|
+
|
|
94
|
+
[thresholds]
|
|
95
|
+
change_pct_alert = 5.0 # |24h 涨跌| >= 5% 就告警,0 关闭
|
|
96
|
+
volume_spike_pct = 0.0 # 成交量异动阈值,0 关闭
|
|
97
|
+
price_above = { "bitcoin" = 200000 } # 突破上方
|
|
98
|
+
price_below = { "ethereum" = 500 } # 跌破下方
|
|
99
|
+
|
|
100
|
+
[notify]
|
|
101
|
+
log = true
|
|
102
|
+
telegram_token = "" # 从 @BotFather 拿
|
|
103
|
+
telegram_chat_id = ""
|
|
104
|
+
discord_webhook = ""
|
|
105
|
+
email_smtp_host = "" # 留空即关闭邮件通道
|
|
106
|
+
email_smtp_user = ""
|
|
107
|
+
email_smtp_pass = "" # 建议用应用专用密码
|
|
108
|
+
email_to = ""
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
**安全注意**: bot token 和 SMTP 密码只存在本地 `config.toml` 里,**从不随代码提交**。仓库只提交脱敏的 `config.example.toml`。
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
## 命令
|
|
116
|
+
|
|
117
|
+
| 命令 | 作用 |
|
|
118
|
+
| --- | --- |
|
|
119
|
+
| `coinwatch check` | 拉一次快照,评估阈值,有告警就推送 |
|
|
120
|
+
| `coinwatch list` | 只列出自选行情,不触发告警 |
|
|
121
|
+
| `coinwatch watch [--interval N]` | 循环监控,默认读配置里的 `interval_seconds` |
|
|
122
|
+
| `coinwatch web` | 启动本地面板,默认 `http://127.0.0.1:8080` |
|
|
123
|
+
| `coinwatch init` | 从示例生成 `config.toml` |
|
|
124
|
+
|
|
125
|
+
所有命令都支持 `--config <path>` 指定配置文件位置;`coinwatch --version` 输出版本号。
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
129
|
+
## 网络与区域可用性
|
|
130
|
+
|
|
131
|
+
CoinWatch 只用公开行情接口,但这些接口在**部分地区/网络下可能直连不通**(Binance、OKX、CoinGecko 均有被拦或限流的情况)。
|
|
132
|
+
|
|
133
|
+
遇到这种情况时,CoinWatch **不会假装没数据**,而会把失败原因打出来:
|
|
134
|
+
|
|
135
|
+
```
|
|
136
|
+
行情源不可用:
|
|
137
|
+
! coingecko: https://api.coingecko.com/... -> Tunnel connection failed: 502 Bad Gateway
|
|
138
|
+
! binance: https://api.binance.com/... -> Tunnel connection failed: 502 Bad Gateway
|
|
139
|
+
-> 常见原因:本机网络到该 API 不通(部分地区需代理)、或被限流。
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
处理方式:给本机配好代理即可,`urllib` 会自动读取 `HTTP_PROXY` / `HTTPS_PROXY` 环境变量:
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
export HTTPS_PROXY=http://127.0.0.1:7890
|
|
146
|
+
coinwatch check
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
由于 3 个源会互相兜底,即使只有一个能通,快照依然完整。
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
153
|
+
## 定时执行
|
|
154
|
+
|
|
155
|
+
CoinWatch **不自带守护进程**,这是刻意的——交给更专业的调度器,也更省资源。
|
|
156
|
+
|
|
157
|
+
**Linux / macOS(cron,每 5 分钟):**
|
|
158
|
+
|
|
159
|
+
```cron
|
|
160
|
+
*/5 * * * * cd /path/to/coinwatch && python -m coinwatch.cli check >> coinwatch.log 2>&1
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
**Windows(任务计划程序):**
|
|
164
|
+
|
|
165
|
+
```powershell
|
|
166
|
+
$action = New-ScheduledTaskAction -Execute "python" `
|
|
167
|
+
-Argument "-m coinwatch.cli check" -WorkingDirectory "C:\path\to\coinwatch"
|
|
168
|
+
$trigger = New-ScheduledTaskTrigger -RepetitionInterval (New-TimeSpan -Minutes 5) -Once -At (Get-Date)
|
|
169
|
+
Register-ScheduledTask -TaskName "CoinWatch" -Action $action -Trigger $trigger
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
**WorkBuddy 自动化:** 创建一条定时任务,指令为「运行 `coinwatch check` 」,即可把告警接进 AI 工作流。
|
|
173
|
+
|
|
174
|
+
---
|
|
175
|
+
|
|
176
|
+
## 架构
|
|
177
|
+
|
|
178
|
+
```
|
|
179
|
+
src/coinwatch/
|
|
180
|
+
├── config.py # TOML 加载与阈值访问
|
|
181
|
+
├── market.py # Market:多源聚合 + 按币种 failover
|
|
182
|
+
├── alert.py # 阈值评估,成交量基线持久化
|
|
183
|
+
├── notifier.py # log / Telegram / Discord / Email
|
|
184
|
+
├── report.py # 文本 & JSON 渲染
|
|
185
|
+
├── web.py # 标准库 http.server 面板
|
|
186
|
+
├── cli.py # argparse 入口
|
|
187
|
+
└── sources/
|
|
188
|
+
├── base.py # Quote / Source 抽象
|
|
189
|
+
├── coingecko.py
|
|
190
|
+
├── binance.py
|
|
191
|
+
└── okx.py
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
数据流:
|
|
195
|
+
|
|
196
|
+
```
|
|
197
|
+
config.toml → Market.snapshot() → alert.evaluate() → notifier.notify()
|
|
198
|
+
↑
|
|
199
|
+
CoinGecko → Binance → OKX(逐级兜底)
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
**新增一个数据源**:继承 `Source`,实现 `fetch(coin_ids, symbols) -> dict[str, Quote]`,然后丢进 `Market(sources=[...])`。解析逻辑请配一个 `monkeypatch` 单测,参考 `tests/test_sources.py`。
|
|
203
|
+
|
|
204
|
+
---
|
|
205
|
+
|
|
206
|
+
## 开发
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
pip install -e ".[dev]"
|
|
210
|
+
pytest -q
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
测试不访问网络——用 `monkeypatch` 打桩 `_get_json` 来验证解析逻辑,所以 CI 里跑得又快又稳。
|
|
214
|
+
|
|
215
|
+
---
|
|
216
|
+
|
|
217
|
+
## 免责声明
|
|
218
|
+
|
|
219
|
+
本项目**仅用于行情监控与告警**,不提供任何投资建议、买卖信号或收益承诺。所有数据来自第三方公开 API,可能延迟或不准确,请以交易所实际成交为准。加密货币市场波动剧烈、风险极高,请自行判断并控制风险。
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
## License
|
|
224
|
+
|
|
225
|
+
[MIT](LICENSE) © 2026 MT
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# CoinWatch configuration EXAMPLE.
|
|
2
|
+
# Copy to config.toml (which is gitignored) and edit:
|
|
3
|
+
# cp config.example.toml config.toml
|
|
4
|
+
#
|
|
5
|
+
# SECURITY: never commit config.toml — it may hold bot tokens / SMTP passwords.
|
|
6
|
+
|
|
7
|
+
[watchlist]
|
|
8
|
+
# CoinGecko coin id (lowercase) = display symbol
|
|
9
|
+
# Full id list: https://api.coingecko.com/api/v3/coins/list
|
|
10
|
+
bitcoin = "BTC"
|
|
11
|
+
ethereum = "ETH"
|
|
12
|
+
solana = "SOL"
|
|
13
|
+
|
|
14
|
+
[thresholds]
|
|
15
|
+
# Trigger when |24h change| >= this percentage. 0 disables this rule.
|
|
16
|
+
change_pct_alert = 5.0
|
|
17
|
+
|
|
18
|
+
# Trigger when 24h quote volume rises this much above the rolling baseline. 0 disables.
|
|
19
|
+
volume_spike_pct = 0.0
|
|
20
|
+
|
|
21
|
+
# Per-coin price barriers, keyed by coin id (NOT symbol).
|
|
22
|
+
price_above = { "bitcoin" = 200000 }
|
|
23
|
+
price_below = { "ethereum" = 500 }
|
|
24
|
+
|
|
25
|
+
[notify]
|
|
26
|
+
# Log to stdout. Recommended to keep enabled.
|
|
27
|
+
log = true
|
|
28
|
+
|
|
29
|
+
# Telegram — get a token from @BotFather, chat id from your chat.
|
|
30
|
+
telegram_token = ""
|
|
31
|
+
telegram_chat_id = ""
|
|
32
|
+
|
|
33
|
+
# Discord incoming webhook URL.
|
|
34
|
+
discord_webhook = ""
|
|
35
|
+
|
|
36
|
+
# Email (SMTP). Leave host empty to disable. Use an app-specific password.
|
|
37
|
+
email_smtp_host = ""
|
|
38
|
+
email_smtp_port = 587
|
|
39
|
+
email_smtp_user = ""
|
|
40
|
+
email_smtp_pass = ""
|
|
41
|
+
email_to = ""
|
|
42
|
+
|
|
43
|
+
[web]
|
|
44
|
+
enabled = false
|
|
45
|
+
host = "127.0.0.1"
|
|
46
|
+
port = 8080
|
|
47
|
+
|
|
48
|
+
[schedule]
|
|
49
|
+
# Informational only — CoinWatch itself is scheduler-agnostic.
|
|
50
|
+
# Drive it from cron, Windows Task Scheduler, or WorkBuddy automations.
|
|
51
|
+
interval_seconds = 300
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "coinwatch-cli"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Local-first crypto market monitor & alert engine. Multi-source failover, zero third-party dependencies."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = { text = "MIT" }
|
|
11
|
+
requires-python = ">=3.11"
|
|
12
|
+
authors = [{ name = "MT" }]
|
|
13
|
+
keywords = ["crypto", "bitcoin", "monitoring", "alerting", "cli", "price-tracker"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 3 - Alpha",
|
|
16
|
+
"Environment :: Console",
|
|
17
|
+
"Intended Audience :: Developers",
|
|
18
|
+
"License :: OSI Approved :: MIT License",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3.11",
|
|
21
|
+
"Programming Language :: Python :: 3.12",
|
|
22
|
+
"Programming Language :: Python :: 3.13",
|
|
23
|
+
"Topic :: Office/Business :: Financial :: Investment",
|
|
24
|
+
]
|
|
25
|
+
|
|
26
|
+
# Core runtime has ZERO third-party dependencies (standard library only).
|
|
27
|
+
dependencies = []
|
|
28
|
+
|
|
29
|
+
[project.optional-dependencies]
|
|
30
|
+
dev = ["pytest>=7.0"]
|
|
31
|
+
|
|
32
|
+
[project.urls]
|
|
33
|
+
Homepage = "https://github.com/AlfredoJamesPacino/coinwatch"
|
|
34
|
+
Repository = "https://github.com/AlfredoJamesPacino/coinwatch"
|
|
35
|
+
Issues = "https://github.com/AlfredoJamesPacino/coinwatch/issues"
|
|
36
|
+
|
|
37
|
+
[project.scripts]
|
|
38
|
+
coinwatch = "coinwatch.cli:main"
|
|
39
|
+
|
|
40
|
+
[tool.hatch.build.targets.wheel]
|
|
41
|
+
packages = ["src/coinwatch"]
|
|
42
|
+
|
|
43
|
+
[tool.pytest.ini_options]
|
|
44
|
+
pythonpath = ["src"]
|
|
45
|
+
testpaths = ["tests"]
|