tinkclaw 0.2.0__tar.gz

tinkclaw-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Meshcue
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tinkclaw-0.2.0/PKG-INFO

@@ -0,0 +1,333 @@
+Metadata-Version: 2.4
+Name: tinkclaw
+Version: 0.2.0
+Summary: Official Python SDK for TinkClaw quant intelligence API
+Home-page: https://github.com/tinkclaw/tinkclaw-python
+Author: TinkClaw
+Author-email: TinkClaw <dev@tinkclaw.com>
+License-Expression: MIT
+Project-URL: Documentation, https://tinkclaw.com/docs
+Project-URL: Source, https://github.com/tinkclaw/tinkclaw-python
+Project-URL: Issues, https://github.com/tinkclaw/tinkclaw-python/issues
+Keywords: trading,bot,api,quant,finance,tinkclaw,confluence,signals,crypto
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Provides-Extra: brokers
+Requires-Dist: alpaca-py>=0.10.0; extra == "brokers"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# TinkClaw Python SDK
+
+Official Python SDK for [TinkClaw](https://tinkclaw.com) quant intelligence API.
+
+Build trading bots in minutes using confluence signals powered by Hurst exponent, autocorrelation, and regime detection.
+
+## Features
+
+- Simple API wrapper for TinkClaw endpoints
+- Strategy base class for custom bot logic
+- Alpaca paper trading integration
+- Local backtesting harness
+- Full typing support
+- Zero heavy dependencies (just `requests`)
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+Or from PyPI (coming soon):
+
+```bash
+pip install tinkclaw
+```
+
+## Quick Start (5 Minutes)
+
+### 1. Get Your API Key
+
+1. Visit [https://tinkclaw.com](https://tinkclaw.com)
+2. Sign up for free Developer tier (50 calls/day)
+3. Copy your API key
+
+### 2. Basic Usage
+
+```python
+from tinkclaw import TinkClawClient
+
+# Initialize client
+client = TinkClawClient(api_key="your_key_here")
+
+# Get confluence score
+confluence = client.get_confluence("BTC")
+
+print(f"Symbol: {confluence['symbol']}")
+print(f"Score: {confluence['score']}")        # 0-100
+print(f"Signal: {confluence['signal']}")      # strong_buy, buy, hold, sell, strong_sell
+print(f"Setup: {confluence['setup_type']}")   # trending, mean_reverting, uncertain
+```
+
+### 3. Build a Trading Bot
+
+```python
+from tinkclaw import TinkClawClient, Strategy
+
+class MomentumBot(Strategy):
+    def on_signal(self, symbol, confluence):
+        score = confluence['score']
+        setup = confluence['setup_type']
+
+        # Buy on strong confluence + trending regime
+        if score > 75 and setup == 'trending':
+            self.buy(symbol, size=100)
+
+        # Sell on weak confluence
+        elif score < 40:
+            self.sell(symbol, size=100)
+
+# Run bot
+client = TinkClawClient(api_key="your_key_here")
+bot = MomentumBot(symbols=['BTC', 'ETH', 'SOL'], client=client)
+bot.run(interval_hours=4)  # Check every 4 hours
+```
+
+Output:
+```
+[TINKCLAW] Starting strategy for 3 symbols
+[TINKCLAW] Check interval: 4 hours
+
+[TINKCLAW] Iteration 1 - 2026-02-21T10:00:00
+[SIGNAL] BTC: score=78, signal=strong_buy, setup=trending
+[SIGNAL] Buy 100 BTC (Strong trending signal (score=78))
+[SIGNAL] ETH: score=65, signal=buy, setup=trending
+[HOLD] ETH: position=0, score=65, setup=trending
+[SIGNAL] SOL: score=42, signal=hold, setup=uncertain
+[HOLD] SOL: position=0, score=42, setup=uncertain
+```
+
+### 4. Integrate with Alpaca Paper Trading
+
+```python
+from tinkclaw import TinkClawClient, Strategy
+from tinkclaw.brokers import AlpacaBroker
+
+# Initialize broker
+broker = AlpacaBroker(
+    api_key="your_alpaca_key",
+    secret_key="your_alpaca_secret",
+    paper=True  # Paper trading
+)
+
+# Initialize strategy with broker
+bot = MomentumBot(
+    symbols=['AAPL', 'TSLA', 'NVDA'],
+    client=client,
+    broker=broker  # Trades will execute on Alpaca
+)
+
+bot.run(interval_hours=4)
+```
+
+Output:
+```
+[EXECUTE] Buy 100 AAPL via AlpacaBroker
+[EXECUTE] Sell 50 TSLA via AlpacaBroker
+```
+
+## API Reference
+
+### TinkClawClient
+
+```python
+client = TinkClawClient(api_key="your_key")
+
+# Get confluence score
+confluence = client.get_confluence("BTC")
+
+# Multi-timeframe analysis
+confluence = client.get_confluence("BTC", timeframes=[7, 30, 90, 365])
+
+# Get technical indicators
+indicators = client.get_indicators("ETH", range_days=30)
+
+# Get historical signals
+history = client.get_history("SOL", limit=100)
+
+# Get top signals across all assets
+top = client.get_top_signals(min_score=70, limit=10)
+
+# Health check
+health = client.health()
+```
+
+### Strategy Base Class
+
+```python
+class MyBot(Strategy):
+    def on_signal(self, symbol, confluence):
+        # Your strategy logic here
+        pass
+
+bot = MyBot(symbols=['BTC'], client=client, broker=None)
+bot.run(interval_hours=4)
+```
+
+Methods:
+- `on_signal(symbol, confluence)` - Override with your logic
+- `buy(symbol, size, reason)` - Place buy order
+- `sell(symbol, size, reason)` - Place sell order
+- `get_position(symbol)` - Get current position
+- `run(interval_hours, max_iterations)` - Run strategy loop
+
+### AlpacaBroker
+
+```python
+from tinkclaw.brokers import AlpacaBroker
+
+broker = AlpacaBroker(
+    api_key="your_key",
+    secret_key="your_secret",
+    paper=True  # Use paper trading
+)
+
+# Place orders
+broker.buy("AAPL", size=10)
+broker.sell("AAPL", size=10)
+
+# Get position
+position = broker.get_position("AAPL")
+
+# Get account info
+account = broker.get_account()
+```
+
+## Examples
+
+See `examples/` directory:
+
+- **momentum_bot.py** - Complete working bot using confluence signals
+- **quickstart.md** - 5-minute integration guide
+
+Run the example:
+
+```bash
+python examples/momentum_bot.py
+```
+
+## Rate Limits
+
+| Tier | Calls/Day | Price | Use Case |
+|------|-----------|-------|----------|
+| Developer | 50 | Free | Testing (3 assets x 6 checks/day) |
+| Builder | 5,000 | $29/mo | Prod bots (10 assets x 24 checks/day) |
+| Pro | 50,000 | $99/mo | Multi-strategy systems |
+| Enterprise | Custom | Custom | Institutional use |
+
+**Developer Tier Optimization:**
+- Check every 4-6 hours (not hourly)
+- Monitor 3-5 assets max
+- 50 calls/day = 3 assets x 6 checks/day (every 4 hours)
+
+## Advanced Features
+
+### Multi-Timeframe Analysis
+
+```python
+confluence = client.get_confluence(
+    symbol="BTC",
+    timeframes=[7, 30, 90, 365]  # 1w, 1m, 3m, 1y
+)
+
+# Returns confluence across all timeframes
+print(confluence['multi_timeframe'])
+```
+
+### Backtesting (Coming Soon)
+
+```python
+from tinkclaw import BacktestEngine
+
+engine = BacktestEngine(
+    strategy=bot,
+    start_date="2025-01-01",
+    end_date="2026-01-01",
+    initial_capital=10000
+)
+
+results = engine.run()
+print(f"Total return: {results['total_return']}%")
+```
+
+## Architecture
+
+```
+Your Bot
+    |
+TinkClaw SDK
+    |
+TinkClaw API (meshcue-api.dieubuhendwa.workers.dev)
+    |
+TinkClaw Backend (Cloudflare Workers + KV)
+```
+
+## Development
+
+Install dev dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run tests:
+
+```bash
+pytest
+```
+
+Format code:
+
+```bash
+black tinkclaw/
+```
+
+## License
+
+MIT License - see LICENSE file
+
+## Support
+
+- **Documentation**: [https://tinkclaw.com/docs](https://tinkclaw.com/docs)
+- **API Status**: [https://meshcue-api.dieubuhendwa.workers.dev/api/signals/health](https://meshcue-api.dieubuhendwa.workers.dev/api/signals/health)
+- **Issues**: [GitHub Issues](https://github.com/tinkclaw/tinkclaw-python/issues)
+
+## Roadmap
+
+- [ ] Publish to PyPI
+- [ ] Add more broker integrations (Interactive Brokers, Coinbase)
+- [ ] Complete backtesting engine with performance metrics
+- [ ] Add WebSocket streaming for real-time signals
+- [ ] CLI tool for quick testing
+- [ ] Jupyter notebook examples
+
+## Credits
+
+Built by [Meshcue](https://meshcue.com) - Global platform for quant intelligence.

tinkclaw-0.2.0/README.md

@@ -0,0 +1,297 @@
+# TinkClaw Python SDK
+
+Official Python SDK for [TinkClaw](https://tinkclaw.com) quant intelligence API.
+
+Build trading bots in minutes using confluence signals powered by Hurst exponent, autocorrelation, and regime detection.
+
+## Features
+
+- Simple API wrapper for TinkClaw endpoints
+- Strategy base class for custom bot logic
+- Alpaca paper trading integration
+- Local backtesting harness
+- Full typing support
+- Zero heavy dependencies (just `requests`)
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+Or from PyPI (coming soon):
+
+```bash
+pip install tinkclaw
+```
+
+## Quick Start (5 Minutes)
+
+### 1. Get Your API Key
+
+1. Visit [https://tinkclaw.com](https://tinkclaw.com)
+2. Sign up for free Developer tier (50 calls/day)
+3. Copy your API key
+
+### 2. Basic Usage
+
+```python
+from tinkclaw import TinkClawClient
+
+# Initialize client
+client = TinkClawClient(api_key="your_key_here")
+
+# Get confluence score
+confluence = client.get_confluence("BTC")
+
+print(f"Symbol: {confluence['symbol']}")
+print(f"Score: {confluence['score']}")        # 0-100
+print(f"Signal: {confluence['signal']}")      # strong_buy, buy, hold, sell, strong_sell
+print(f"Setup: {confluence['setup_type']}")   # trending, mean_reverting, uncertain
+```
+
+### 3. Build a Trading Bot
+
+```python
+from tinkclaw import TinkClawClient, Strategy
+
+class MomentumBot(Strategy):
+    def on_signal(self, symbol, confluence):
+        score = confluence['score']
+        setup = confluence['setup_type']
+
+        # Buy on strong confluence + trending regime
+        if score > 75 and setup == 'trending':
+            self.buy(symbol, size=100)
+
+        # Sell on weak confluence
+        elif score < 40:
+            self.sell(symbol, size=100)
+
+# Run bot
+client = TinkClawClient(api_key="your_key_here")
+bot = MomentumBot(symbols=['BTC', 'ETH', 'SOL'], client=client)
+bot.run(interval_hours=4)  # Check every 4 hours
+```
+
+Output:
+```
+[TINKCLAW] Starting strategy for 3 symbols
+[TINKCLAW] Check interval: 4 hours
+
+[TINKCLAW] Iteration 1 - 2026-02-21T10:00:00
+[SIGNAL] BTC: score=78, signal=strong_buy, setup=trending
+[SIGNAL] Buy 100 BTC (Strong trending signal (score=78))
+[SIGNAL] ETH: score=65, signal=buy, setup=trending
+[HOLD] ETH: position=0, score=65, setup=trending
+[SIGNAL] SOL: score=42, signal=hold, setup=uncertain
+[HOLD] SOL: position=0, score=42, setup=uncertain
+```
+
+### 4. Integrate with Alpaca Paper Trading
+
+```python
+from tinkclaw import TinkClawClient, Strategy
+from tinkclaw.brokers import AlpacaBroker
+
+# Initialize broker
+broker = AlpacaBroker(
+    api_key="your_alpaca_key",
+    secret_key="your_alpaca_secret",
+    paper=True  # Paper trading
+)
+
+# Initialize strategy with broker
+bot = MomentumBot(
+    symbols=['AAPL', 'TSLA', 'NVDA'],
+    client=client,
+    broker=broker  # Trades will execute on Alpaca
+)
+
+bot.run(interval_hours=4)
+```
+
+Output:
+```
+[EXECUTE] Buy 100 AAPL via AlpacaBroker
+[EXECUTE] Sell 50 TSLA via AlpacaBroker
+```
+
+## API Reference
+
+### TinkClawClient
+
+```python
+client = TinkClawClient(api_key="your_key")
+
+# Get confluence score
+confluence = client.get_confluence("BTC")
+
+# Multi-timeframe analysis
+confluence = client.get_confluence("BTC", timeframes=[7, 30, 90, 365])
+
+# Get technical indicators
+indicators = client.get_indicators("ETH", range_days=30)
+
+# Get historical signals
+history = client.get_history("SOL", limit=100)
+
+# Get top signals across all assets
+top = client.get_top_signals(min_score=70, limit=10)
+
+# Health check
+health = client.health()
+```
+
+### Strategy Base Class
+
+```python
+class MyBot(Strategy):
+    def on_signal(self, symbol, confluence):
+        # Your strategy logic here
+        pass
+
+bot = MyBot(symbols=['BTC'], client=client, broker=None)
+bot.run(interval_hours=4)
+```
+
+Methods:
+- `on_signal(symbol, confluence)` - Override with your logic
+- `buy(symbol, size, reason)` - Place buy order
+- `sell(symbol, size, reason)` - Place sell order
+- `get_position(symbol)` - Get current position
+- `run(interval_hours, max_iterations)` - Run strategy loop
+
+### AlpacaBroker
+
+```python
+from tinkclaw.brokers import AlpacaBroker
+
+broker = AlpacaBroker(
+    api_key="your_key",
+    secret_key="your_secret",
+    paper=True  # Use paper trading
+)
+
+# Place orders
+broker.buy("AAPL", size=10)
+broker.sell("AAPL", size=10)
+
+# Get position
+position = broker.get_position("AAPL")
+
+# Get account info
+account = broker.get_account()
+```
+
+## Examples
+
+See `examples/` directory:
+
+- **momentum_bot.py** - Complete working bot using confluence signals
+- **quickstart.md** - 5-minute integration guide
+
+Run the example:
+
+```bash
+python examples/momentum_bot.py
+```
+
+## Rate Limits
+
+| Tier | Calls/Day | Price | Use Case |
+|------|-----------|-------|----------|
+| Developer | 50 | Free | Testing (3 assets x 6 checks/day) |
+| Builder | 5,000 | $29/mo | Prod bots (10 assets x 24 checks/day) |
+| Pro | 50,000 | $99/mo | Multi-strategy systems |
+| Enterprise | Custom | Custom | Institutional use |
+
+**Developer Tier Optimization:**
+- Check every 4-6 hours (not hourly)
+- Monitor 3-5 assets max
+- 50 calls/day = 3 assets x 6 checks/day (every 4 hours)
+
+## Advanced Features
+
+### Multi-Timeframe Analysis
+
+```python
+confluence = client.get_confluence(
+    symbol="BTC",
+    timeframes=[7, 30, 90, 365]  # 1w, 1m, 3m, 1y
+)
+
+# Returns confluence across all timeframes
+print(confluence['multi_timeframe'])
+```
+
+### Backtesting (Coming Soon)
+
+```python
+from tinkclaw import BacktestEngine
+
+engine = BacktestEngine(
+    strategy=bot,
+    start_date="2025-01-01",
+    end_date="2026-01-01",
+    initial_capital=10000
+)
+
+results = engine.run()
+print(f"Total return: {results['total_return']}%")
+```
+
+## Architecture
+
+```
+Your Bot
+    |
+TinkClaw SDK
+    |
+TinkClaw API (meshcue-api.dieubuhendwa.workers.dev)
+    |
+TinkClaw Backend (Cloudflare Workers + KV)
+```
+
+## Development
+
+Install dev dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run tests:
+
+```bash
+pytest
+```
+
+Format code:
+
+```bash
+black tinkclaw/
+```
+
+## License
+
+MIT License - see LICENSE file
+
+## Support
+
+- **Documentation**: [https://tinkclaw.com/docs](https://tinkclaw.com/docs)
+- **API Status**: [https://meshcue-api.dieubuhendwa.workers.dev/api/signals/health](https://meshcue-api.dieubuhendwa.workers.dev/api/signals/health)
+- **Issues**: [GitHub Issues](https://github.com/tinkclaw/tinkclaw-python/issues)
+
+## Roadmap
+
+- [ ] Publish to PyPI
+- [ ] Add more broker integrations (Interactive Brokers, Coinbase)
+- [ ] Complete backtesting engine with performance metrics
+- [ ] Add WebSocket streaming for real-time signals
+- [ ] CLI tool for quick testing
+- [ ] Jupyter notebook examples
+
+## Credits
+
+Built by [Meshcue](https://meshcue.com) - Global platform for quant intelligence.

tinkclaw-0.2.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tinkclaw"
+version = "0.2.0"
+description = "Official Python SDK for TinkClaw quant intelligence API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "TinkClaw", email = "dev@tinkclaw.com" },
+]
+keywords = ["trading", "bot", "api", "quant", "finance", "tinkclaw", "confluence", "signals", "crypto"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "requests>=2.28.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0.0", "pytest-cov>=4.0.0"]
+brokers = ["alpaca-py>=0.10.0"]
+
+[project.urls]
+Documentation = "https://tinkclaw.com/docs"
+Source = "https://github.com/tinkclaw/tinkclaw-python"
+Issues = "https://github.com/tinkclaw/tinkclaw-python/issues"
+
+[tool.setuptools.packages.find]
+exclude = ["tests", "examples", "venv"]

tinkclaw-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+