Metadata-Version: 2.4
Name: pulse-freqtrade
Version: 0.1.0
Summary: Freqtrade adapter for PULSE Protocol — control bots and inject AI signals
Author-email: PULSE Protocol Team <pulse@protocol.org>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/pulseprotocolorg-cyber/pulse-freqtrade
Project-URL: Repository, https://github.com/pulseprotocolorg-cyber/pulse-freqtrade
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pulse-protocol>=0.5.0
Requires-Dist: requests>=2.28.0
Provides-Extra: freqtrade
Requires-Dist: freqtrade>=2024.1; extra == "freqtrade"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"

# pulse-freqtrade

**Freqtrade adapter for PULSE Protocol** — control trading bots and inject AI signals using a universal semantic interface.

[![PyPI version](https://badge.fury.io/py/pulse-freqtrade.svg)](https://pypi.org/project/pulse-freqtrade/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

---

## What is this?

[PULSE Protocol](https://github.com/pulseprotocolorg-cyber/pulse-python) is an open-source semantic messaging standard for AI-to-AI communication. `pulse-freqtrade` bridges PULSE with [Freqtrade](https://www.freqtrade.io/) — the most popular open-source crypto trading bot framework.

**Three things you can do:**

1. **Control a Freqtrade bot** via PULSE messages (same interface as Binance, Bybit, OpenAI adapters)
2. **Inject AI signals** into a running Freqtrade strategy from any external AI agent (Claude, GPT, custom)
3. **Monitor multiple bots** in one dashboard and coordinate risk across them

---

## Installation

```bash
pip install pulse-freqtrade
```

If you want to use `PulseStrategy` inside Freqtrade:

```bash
pip install pulse-freqtrade[freqtrade]
```

---

## Quick Start

### 1. Control a running Freqtrade bot

First, start Freqtrade with the REST API enabled:

```bash
freqtrade trade --config config.json --enable-rest-api
```

Then control it via PULSE:

```python
from pulse_freqtrade import FreqtradeAdapter
from pulse.message import PulseMessage

adapter = FreqtradeAdapter(
    url="http://localhost:8080",
    username="freqtrader",
    password="SuperSecurePassword",
)
adapter.connect()

# Check open trades
msg = PulseMessage(action="ACT.QUERY.STATUS", parameters={})
response = adapter.send(msg)
print(response.content["parameters"]["result"])

# Force buy
msg = PulseMessage(
    action="ACT.TRANSACT.REQUEST",
    parameters={"pair": "BTC/USDT", "stake_amount": 100},
)
adapter.send(msg)

# Stop the bot
adapter.send(PulseMessage(action="ACT.STOP", parameters={}))
```

### 2. Inject AI signals into a Freqtrade strategy

**Strategy file** (`my_strategy.py` in Freqtrade's `user_data/strategies/`):

```python
from pulse_freqtrade import PulseStrategy, SignalListener

class MyAIStrategy(PulseStrategy):
    timeframe = "1h"
    pulse_agent_id = "my-claude-driven-bot"

    # Start signal listener on init (AI agents POST signals here)
    listener = SignalListener(port=9999)
    listener.start()

    def populate_entry_trend(self, dataframe, metadata):
        # Check PULSE signals from AI agents
        signals = self.get_pulse_signals(metadata["pair"])
        if signals:
            signal = signals[0]
            direction = signal.content["parameters"].get("direction")
            confidence = signal.content["parameters"].get("confidence", 0)

            if direction == "long" and confidence > 0.8:
                dataframe["enter_long"] = 1
                return dataframe

        # Fallback: your standard logic
        dataframe.loc[dataframe["rsi"] < 30, "enter_long"] = 1
        return dataframe

    def populate_exit_trend(self, dataframe, metadata):
        signals = self.get_pulse_signals(metadata["pair"])
        if signals:
            direction = signals[0].content["parameters"].get("direction")
            if direction == "short":
                dataframe["exit_long"] = 1
                return dataframe

        dataframe.loc[dataframe["rsi"] > 70, "exit_long"] = 1
        return dataframe
```

**External AI agent** (any Python script, can run on different machine):

```python
import requests

# Claude/GPT analysis says BTC is oversold → send BUY signal
requests.post("http://your-freqtrade-server:9999/", json={
    "action": "ACT.RECOMMEND.ACTION",
    "parameters": {
        "pair": "BTC/USDT",
        "direction": "long",
        "confidence": 0.92,
        "reason": "RSI < 25, bullish divergence",
        "agent_id": "claude-analyst",
    }
})
```

### 3. Signal format conversion

```python
from pulse_freqtrade import SignalConverter

# Freqtrade signal → PULSE
ft_signal = {"pair": "BTC/USDT", "signal": 1, "confidence": 0.85}
pulse_msg = SignalConverter.freqtrade_to_pulse(ft_signal)

# PULSE → Freqtrade
ft_signal = SignalConverter.pulse_to_freqtrade(pulse_msg)
print(ft_signal["signal"])  # 1
```

---

## Supported PULSE Actions

| PULSE Action | Freqtrade Operation |
|---|---|
| `ACT.QUERY.STATUS` | GET /api/v1/status (open trades) |
| `ACT.QUERY.BALANCE` | GET /api/v1/balance |
| `ACT.QUERY.LIST` | GET /api/v1/trades (history) |
| `ACT.QUERY.DATA` | GET /api/v1/pair_candles (OHLCV) |
| `ACT.QUERY.PROFIT` | GET /api/v1/profit |
| `ACT.TRANSACT.REQUEST` | POST /api/v1/forcebuy |
| `ACT.CANCEL` | POST /api/v1/forcesell |
| `ACT.START` | POST /api/v1/start |
| `ACT.STOP` | POST /api/v1/stop |
| `ACT.RELOAD` | POST /api/v1/reload_config |

---

## Why PULSE + Freqtrade?

| Without PULSE | With PULSE |
|---|---|
| Each bot has its own API | One interface for all bots |
| Hard to inject external signals | `signal_bus.push(msg)` — done |
| No cross-bot coordination | `MultiBotCoordinator` monitors all |
| Custom signal formats everywhere | Standard semantic messages |
| Manual monitoring | PULSE audit trail for every trade |

---

## Examples

```
examples/
  01_control_bot.py          — Control bot, query trades and balance
  02_ai_signal_injection.py  — AI agent sends signals to strategy
  03_multi_bot_arbitrage.py  — Monitor and coordinate multiple bots
```

---

## PULSE Ecosystem

| Package | Description |
|---|---|
| [pulse-protocol](https://pypi.org/project/pulse-protocol/) | Core protocol |
| [pulse-openai](https://pypi.org/project/pulse-openai/) | OpenAI/GPT adapter |
| [pulse-anthropic](https://pypi.org/project/pulse-anthropic/) | Claude adapter |
| [pulse-binance](https://pypi.org/project/pulse-binance/) | Binance exchange |
| [pulse-bybit](https://pypi.org/project/pulse-bybit/) | Bybit exchange |
| **pulse-freqtrade** | **Freqtrade bot** |

---

## License

Apache 2.0 — free forever, open source.
