pulse-freqtrade

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

---

What is this?

PULSE Protocol is an open-source semantic messaging standard for AI-to-AI communication. pulse-freqtrade bridges PULSE with Freqtrade — 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

pip install pulse-freqtrade

If you want to use PulseStrategy inside Freqtrade:

pip install pulse-freqtrade[freqtrade]

---

Quick Start

1. Control a running Freqtrade bot

First, enable the REST API in your config.json:

"api_server": {
    "enabled": true,
    "listen_ip_address": "127.0.0.1",
    "listen_port": 8080,
    "username": "freqtrader",
    "password": "SuperSecurePassword",
    "jwt_secret_key": "somethingRandomSomethingRandom123"
}

Then start Freqtrade normally:

freqtrade trade --config config.json

Then control it via PULSE:

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/):

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):

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

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	Core protocol
pulse-openai	OpenAI/GPT adapter
pulse-anthropic	Claude adapter
pulse-binance	Binance exchange
pulse-bybit	Bybit exchange
pulse-freqtrade	Freqtrade bot

---

License

Apache 2.0 — free forever, open source.