REST API¶

FreqUI¶

FreqUI 现在拥有独立的文档章节 — 有关 FreqUI 的所有信息，请参考该章节。

配置¶

通过在配置文件中添加 api_server 部分，并将 api_server.enabled 设置为 true 来启用 REST API。

示例配置：

    "api_server": {
        "enabled": true,
        "listen_ip_address": "127.0.0.1",
        "listen_port": 8080,
        "verbosity": "error",
        "enable_openapi": false,
        "jwt_secret_key": "somethingrandom",
        "CORS_origins": [],
        "username": "Freqtrader",
        "password": "SuperSecret1!",
        "ws_token": "sercet_Ws_t0ken"
    },

安全警告

默认情况下，配置仅监听本地回环地址（因此无法从其他系统访问）。我们强烈建议不要将此 API 暴露到互联网上，并选择一个强且唯一的密码，因为其他人可能借此控制你的交易机器人。

远程服务器上的 API/用户界面访问

如果你在 VPS 上运行，应考虑使用 SSH 隧道或搭建 VPN（如 OpenVPN、WireGuard）来连接你的机器人。这可以确保 freqUI 不会直接暴露在互联网上，出于安全原因这是不推荐的做法（freqUI 默认不支持 HTTPS）。这些工具的配置不在本教程范围内，但互联网上有许多优秀的教程可供参考。

然后，你可以在浏览器中访问 http://127.0.0.1:8080/api/v1/ping 来检查 API 是否正常运行。该请求应返回如下响应：

{"status":"pong"}

所有其他端点都会返回敏感信息，并需要身份验证，因此无法通过网页浏览器直接访问。

安全¶

为了生成安全的密码，最好使用密码管理器，或者使用以下代码生成。

import secrets
secrets.token_hex()

JWT 令牌

使用相同的方法生成 JWT 密钥（jwt_secret_key）。

密码选择

请务必选择一个非常强且唯一的密码，以保护您的机器人免受未授权访问。同时将 jwt_secret_key 更改为某个随机值（无需记住此值，但它将用于加密您的会话，因此最好确保其唯一性！）。

使用 Docker 配置¶

如果您使用 Docker 运行机器人，则需要让机器人监听传入的连接。此时安全性由 Docker 来保障。

    "api_server": {
        "enabled": true,
        "listen_ip_address": "0.0.0.0",
        "listen_port": 8080,
        "username": "Freqtrader",
        "password": "SuperSecret1!",
        //...
    },

请确保您的 docker-compose 文件中包含以下两行配置：

    ports:
      - "127.0.0.1:8080:8080"

安全警告

通过在 Docker 端口映射中使用 "8080:8080"（或 "0.0.0.0:8080:8080"），API 将对连接到服务器指定端口的所有人开放，这意味着其他人可能能够控制您的机器人。如果在安全环境（例如家庭网络）中运行机器人，这可能是安全的，但不建议将 API 暴露在互联网上。

REST API¶

调用 API¶

我们建议使用官方支持的 freqtrade-client 包（也可通过 scripts/rest_client.py 获取）来调用 API。

该命令可通过 pip install freqtrade-client 独立于任何正在运行的 freqtrade 机器人进行安装。

此模块设计轻量，仅依赖 requests 和 python-rapidjson 模块，避免了 freqtrade 其他繁重的依赖项。

freqtrade-client <command> [optional parameters]

默认情况下，脚本假设使用 127.0.0.1（本地主机）和端口 8080，但您可以通过指定配置文件来覆盖此行为。

极简客户端配置¶

{
    "api_server": {
        "enabled": true,
        "listen_ip_address": "0.0.0.0",
        "listen_port": 8080,
        "username": "Freqtrader",
        "password": "SuperSecret1!",
        //...
    }
}

freqtrade-client --config rest_config.json <command> [optional parameters]

参数较多的命令可能需要使用关键字参数（以提高清晰度），可按如下方式提供：

freqtrade-client --config rest_config.json forceenter BTC/USDT long enter_tag=GutFeeling

此方法适用于所有参数——请查看 "show" 命令以获取可用参数列表。

程序化使用

freqtrade-client 包（可独立于 freqtrade 安装）可在您自己的脚本中用于与 freqtrade API 进行交互。为此，请使用以下方式：

from freqtrade_client import FtRestClient


client = FtRestClient(server_url, username, password)

# Get the status of the bot
ping = client.ping()
print(ping)

# Add pairs to blacklist
client.blacklist("BTC/USDT", "ETH/USDT")
# Add pairs to blacklist by supplying a list
client.blacklist(*listPairs)
# ...

有关可用命令的完整列表，请参阅下方内容。

可通过 rest-client 脚本中的 help 命令列出所有可能的命令。

freqtrade-client help

Possible commands:

available_pairs
    Return available pair (backtest data) based on timeframe / stake_currency selection

        :param timeframe: Only pairs with this timeframe available.
        :param stake_currency: Only pairs that include this timeframe

balance
    Get the account balance.

blacklist
    Show the current blacklist.

        :param add: List of coins to add (example: "BNB/BTC")

cancel_open_order
    Cancel open order for trade.

        :param trade_id: Cancels open orders for this trade.

count
    Return the amount of open trades.

daily
    Return the profits for each day, and amount of trades.

delete_lock
    Delete (disable) lock from the database.

        :param lock_id: ID for the lock to delete

delete_trade
    Delete trade from the database.
        Tries to close open orders. Requires manual handling of this asset on the exchange.

        :param trade_id: Deletes the trade with this ID from the database.

forcebuy
    Buy an asset.

        :param pair: Pair to buy (ETH/BTC)
        :param price: Optional - price to buy

forceenter
    Force entering a trade

        :param pair: Pair to buy (ETH/BTC)
        :param side: 'long' or 'short'
        :param price: Optional - price to buy

forceexit
    Force-exit a trade.

        :param tradeid: Id of the trade (can be received via status command)
        :param ordertype: Order type to use (must be market or limit)
        :param amount: Amount to sell. Full sell if not given

health
    Provides a quick health check of the running bot.

lock_add
    Manually lock a specific pair

        :param pair: Pair to lock
        :param until: Lock until this date (format "2024-03-30 16:00:00Z")
        :param side: Side to lock (long, short, *)
        :param reason: Reason for the lock        

locks
    Return current locks

logs
    Show latest logs.

        :param limit: Limits log messages to the last <limit> logs. No limit to get the entire log.

pair_candles
    Return live dataframe for <pair><timeframe>.

        :param pair: Pair to get data for
        :param timeframe: Only pairs with this timeframe available.
        :param limit: Limit result to the last n candles.

pair_history
    Return historic, analyzed dataframe

        :param pair: Pair to get data for
        :param timeframe: Only pairs with this timeframe available.
        :param strategy: Strategy to analyze and get values for
        :param timerange: Timerange to get data for (same format than --timerange endpoints)

performance
    Return the performance of the different coins.

ping
    simple ping

plot_config
    Return plot configuration if the strategy defines one.

profit
    Return the profit summary.

reload_config
    Reload configuration.

show_config
    Returns part of the configuration, relevant for trading operations.

start
    Start the bot if it's in the stopped state.

pause
    Pause the bot if it's in the running state. If triggered on stopped state will handle open positions.

stats
    Return the stats report (durations, sell-reasons).

status
    Get the status of open trades.

stop
    Stop the bot. Use `start` to restart.

stopbuy
    Stop buying (but handle sells gracefully). Use `reload_config` to reset.

strategies
    Lists available strategies

strategy
    Get strategy details

        :param strategy: Strategy class name

sysinfo
    Provides system information (CPU, RAM usage)

trade
    Return specific trade

        :param trade_id: Specify which trade to get.

trades
    Return trades history, sorted by id

        :param limit: Limits trades to the X last trades. Max 500 trades.
        :param offset: Offset by this amount of trades.

list_open_trades_custom_data
    Return a dict containing open trades custom-datas

        :param key: str, optional - Key of the custom-data
        :param limit: Limits trades to X trades.
        :param offset: Offset by this amount of trades.

list_custom_data
    Return a dict containing custom-datas of a specified trade

        :param trade_id: int - ID of the trade
        :param key: str, optional - Key of the custom-data

version
    Return the version of the bot.

whitelist
    Show the current whitelist.

可用端点¶

如果您希望通过其他方式手动调用 REST API，例如直接使用 curl，下表列出了相关的 URL 端点和参数。下表中所有端点均需加上 API 的基础 URL 前缀，例如 http://127.0.0.1:8080/api/v1/ —— 因此完整命令为 http://127.0.0.1:8080/api/v1/<command>。

端点	方法	描述 / 参数
`/ping`	GET	简单的命令，用于测试 API 是否就绪——无需身份验证。
`/start`	POST	启动交易机器人。
`/pause`	POST	暂停交易员。根据规则优雅地处理未平仓交易，不再开新仓。
`/stop`	POST	停止交易员。
`/stopbuy`	POST	阻止交易员开新仓。根据规则优雅地关闭现有未平仓交易。
`/reload_config`	POST	重新加载配置文件。
`/trades`	GET	列出最近的交易记录。每次调用最多返回 500 笔交易。
`/trade/<tradeid>`	GET	获取指定交易。参数： - `tradeid` (`int`)
`/trades/<tradeid>`	DELETE	从数据库中删除该交易。尝试取消未成交的订单。此操作需要在交易所手动处理该交易。参数： - `tradeid` (`int`)
`/trades/<tradeid>/open-order`	DELETE	取消该交易的未成交订单。参数： - `tradeid` (`int`)
`/trades/<tradeid>/reload`	POST	从交易所重新加载交易信息。仅在实盘模式下有效，可用于恢复在交易所被手动卖出的交易。参数： - `tradeid` (`int`)
`/show_config`	GET	显示当前配置中与运行相关的重要设置。
`/logs`	GET	显示最近的日志消息。
`/status`	GET	列出所有未平仓交易。
`/count`	GET	显示已使用和可用的交易数量。
`/entries`	GET	显示指定交易对（或所有交易对，若未指定）每个入场标签的盈利统计信息。交易对为可选参数。参数： - `pair` (`str`)
`/exits`	GET	显示指定交易对（或所有交易对，若未指定交易对）每次退出原因的盈利统计信息。交易对为可选参数。参数： - `pair` (`str`)
`/mix_tags`	GET	显示指定交易对（或所有交易对，若未指定交易对）的进入标签与退出原因组合的盈利统计信息。交易对为可选参数。参数： - `pair` (`str`)
`/locks`	GET	显示当前被锁定的交易对。
`/locks`	POST	将某个交易对锁定至指定时间“until”（时间会被向上取整到最近的时间框架）。方向为可选参数，值为 `long` 或 `short`（默认为 `long`）。原因可选。参数： - `<pair>` (`str`) - `<until>` (`datetime`) - `[side]` (`str`) - `[reason]` (`str`)
`/locks/<lockid>`	DELETE	根据 ID 删除（禁用）锁定。参数： - `lockid` (`int`)
`/profit`	GET	显示已关闭交易的盈亏汇总以及有关您交易表现的一些统计数据。
`/forceexit`	POST	立即退出指定交易（忽略 `minimum_roi`），使用指定的订单类型（“market”或“limit”，若未指定则使用配置中的设置）以及指定的卖出数量（若未指定则全部卖出）。如果将 `all` 作为 `tradeid` 提供，则所有当前打开的交易都将被强制退出。参数： - `<tradeid>` (`int` 或 `str`) - `<ordertype>` (`str`) - `[amount]` (`float`)
`/forceenter`	POST	立即进入指定交易对。方向为可选参数，值为 `long` 或 `short`（默认为 `long`）。价格为可选参数。（必须将 `force_entry_enable` 设置为 True）参数： - `<pair>` (`str`) - `<side>` (`str`) - `[rate]` (`float`)
`/performance`	GET	按交易对分组显示每笔已完成交易的表现情况。
`/balance`	GET	显示各币种的账户余额。
`/daily`	GET	显示过去 n 天每日的盈利或亏损情况（n 默认为 7）。参数： - `timescale` (`int`)
`/weekly`	GET	显示过去 n 天每周的盈利或亏损情况（n 默认为 4）。参数： - `timescale` (`int`)
`/monthly`	GET	显示过去 n 个月每月的盈利或亏损情况（n 默认为 3）。参数： - `timescale` (`int`)
`/stats`	GET	显示盈亏原因的汇总以及平均持仓时间。
`/whitelist`	GET	显示当前白名单。
`/blacklist`	GET	显示当前黑名单。
`/blacklist`	POST	将指定交易对添加到黑名单。参数： - `blacklist` (`str`)
`/blacklist`	DELETE	从黑名单中删除指定的交易对列表。参数： - `[pair,pair]` (`list[str]`)
`/pair_candles`	GET	在机器人运行时返回某个交易对/时间周期组合的数据框。Alpha
`/pair_candles`	POST	在机器人运行时返回某个交易对/时间周期组合的数据框，并根据提供的列名列表进行过滤。Alpha 参数： - `<column_list>` (`list[str]`)
`/pair_history`	GET	返回由特定策略分析过的、指定时间范围内的数据框。Alpha
`/pair_history`	POST	返回由特定策略分析过的、指定时间范围内的数据框，并根据提供的列名列表进行过滤。Alpha 参数： - `<column_list>` (`list[str]`)
`/plot_config`	GET	获取策略中的绘图配置（如果未配置则无返回）。Alpha
`/strategies`	GET	列出策略目录中的所有策略。Alpha
`/strategy/<strategy>`	GET	通过策略类名获取特定策略的内容。Alpha 参数： - `<strategy>` (`str`)
`/available_pairs`	GET	列出可用的回测数据。Alpha
`/version`	GET	显示版本信息。
`/sysinfo`	GET	显示系统负载相关信息。
`/health`	GET	显示机器人健康状态（最近一次循环）。

Alpha 状态

标记为Alpha 状态的接口可能会随时更改，恕不另行通知。

消息 WebSocket¶

API 服务器包含一个 WebSocket 端点，用于订阅 Freqtrade 机器人的 RPC 消息。你可以通过它实时获取机器人的数据，例如入场/出场成交消息、白名单变更、交易对的指标数据等。

这也用于在 Freqtrade 中设置生产者/消费者模式。

假设你的 REST API 设置为 127.0.0.1，端口为 8080，则该端点可通过 http://localhost:8080/api/v1/message/ws 访问。

要访问 WebSocket 端点，必须在端点 URL 中以查询参数形式提供 ws_token。

要生成安全的 ws_token，可运行以下代码：

>>> import secrets
>>> secrets.token_urlsafe(25)
'hZ-y58LXyX_HZ8O1cJzVyN6ePWrLpNQv4Q'

然后，你需要在 api_server 配置中的 ws_token 下添加该令牌。如下所示：

"api_server": {
    "enabled": true,
    "listen_ip_address": "127.0.0.1",
    "listen_port": 8080,
    "verbosity": "error",
    "enable_openapi": false,
    "jwt_secret_key": "somethingrandom",
    "CORS_origins": [],
    "username": "Freqtrader",
    "password": "SuperSecret1!",
    "ws_token": "hZ-y58LXyX_HZ8O1cJzVyN6ePWrLpNQv4Q" // <-----
},

你现在可以通过 http://localhost:8080/api/v1/message/ws?token=hZ-y58LXyX_HZ8O1cJzVyN6ePWrLpNQv4Q 连接到该端点。

示例令牌的重复使用

请勿使用上述示例令牌。为确保安全性，请生成一个全新的令牌。

使用 WebSocket¶

连接到 WebSocket 后，机器人会向所有订阅了这些消息的客户端广播 RPC 消息。要订阅一组消息，你必须通过 WebSocket 发送如下所示的 JSON 请求。其中 data 键的值必须是一个包含消息类型字符串的列表。

{
  "type": "subscribe",
  "data": ["whitelist", "analyzed_df"] // A list of string message types
}

有关消息类型的列表，请参阅 freqtrade/enums/rpcmessagetype.py 中的 RPCMessageType 枚举。

此后，只要连接保持活动状态，每当机器人发送这些类型的 RPC 消息时，你都会通过 WebSocket 收到它们。其格式通常与请求类似：

{
  "type": "analyzed_df",
  "data": {
      "key": ["NEO/BTC", "5m", "spot"],
      "df": {}, // The dataframe
      "la": "2022-09-08 22:14:41.457786+00:00"
  }
}

反向代理设置¶

当使用 Nginx 时，WebSocket 正常工作需要以下配置（注意：此配置不完整，缺少一些信息，不能直接使用）：

请确保将 <freqtrade_listen_ip>（及其后续端口）替换为与你的配置/设置匹配的 IP 和端口。

http {
    map $http_upgrade $connection_upgrade {
        default upgrade;
        '' close;
    }

    #...

    server {
        #...

        location / {
            proxy_http_version 1.1;
            proxy_pass http://<freqtrade_listen_ip>:8080;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
            proxy_set_header Host $host;
        }
    }
}

为了正确且安全地配置你的反向代理，请查阅其关于代理 WebSocket 的文档。

Traefik：Traefik 开箱即支持 WebSocket，请参见文档
Caddy：Caddy v2 开箱即支持 WebSocket，请参见文档

SSL 证书

你可以使用 certbot 等工具，通过上述任一反向代理设置 SSL 证书，以加密连接访问机器人的用户界面。虽然这可以保护你在传输中的数据，但我们不建议将 Freqtrade API 暴露在你的私有网络之外（如 VPN、SSH 隧道外）。

OpenAPI 接口¶

要启用内置的 OpenAPI 接口（Swagger UI），请在 api_server 配置中指定 "enable_openapi": true。这将在 /docs 端点启用 Swagger UI。默认情况下，它运行在 http://localhost:8080/docs —— 但具体取决于你的设置。

使用 JWT 令牌的高级 API 用法¶

注意

以下操作应在应用程序中完成（例如一个通过 API 获取信息的 Freqtrade REST API 客户端），并不打算供日常手动使用。

Freqtrade 的 REST API 还提供了 JWT（JSON Web Token）。你可以使用以下命令登录，并随后使用获得的 access_token。

> curl -X POST --user Freqtrader http://localhost:8080/api/v1/token/login
{"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1ODkxMTk2ODEsIm5iZiI6MTU4OTExOTY4MSwianRpIjoiMmEwYmY0NWUtMjhmOS00YTUzLTlmNzItMmM5ZWVlYThkNzc2IiwiZXhwIjoxNTg5MTIwNTgxLCJpZGVudGl0eSI6eyJ1IjoiRnJlcXRyYWRlciJ9LCJmcmVzaCI6ZmFsc2UsInR5cGUiOiJhY2Nlc3MifQ.qt6MAXYIa-l556OM7arBvYJ0SDI9J8bIk3_glDujF5g","refresh_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1ODkxMTk2ODEsIm5iZiI6MTU4OTExOTY4MSwianRpIjoiZWQ1ZWI3YjAtYjMwMy00YzAyLTg2N2MtNWViMjIxNWQ2YTMxIiwiZXhwIjoxNTkxNzExNjgxLCJpZGVudGl0eSI6eyJ1IjoiRnJlcXRyYWRlciJ9LCJ0eXBlIjoicmVmcmVzaCJ9.d1AT_jYICyTAjD0fiQAr52rkRqtxCjUGEMwlNuuzgNQ"}

> access_token="eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1ODkxMTk2ODEsIm5iZiI6MTU4OTExOTY4MSwianRpIjoiMmEwYmY0NWUtMjhmOS00YTUzLTlmNzItMmM5ZWVlYThkNzc2IiwiZXhwIjoxNTg5MTIwNTgxLCJpZGVudGl0eSI6eyJ1IjoiRnJlcXRyYWRlciJ9LCJmcmVzaCI6ZmFsc2UsInR5cGUiOiJhY2Nlc3MifQ.qt6MAXYIa-l556OM7arBvYJ0SDI9J8bIk3_glDujF5g"
# Use access_token for authentication
> curl -X GET --header "Authorization: Bearer ${access_token}" http://localhost:8080/api/v1/count

由于 access token 有效期较短（15 分钟），应定期使用 token/refresh 请求来获取新的 access token：

> curl -X POST --header "Authorization: Bearer ${refresh_token}"http://localhost:8080/api/v1/token/refresh
{"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1ODkxMTk5NzQsIm5iZiI6MTU4OTExOTk3NCwianRpIjoiMDBjNTlhMWUtMjBmYS00ZTk0LTliZjAtNWQwNTg2MTdiZDIyIiwiZXhwIjoxNTg5MTIwODc0LCJpZGVudGl0eSI6eyJ1IjoiRnJlcXRyYWRlciJ9LCJmcmVzaCI6ZmFsc2UsInR5cGUiOiJhY2Nlc3MifQ.1seHlII3WprjjclY6DpRhen0rqdF4j6jbvxIhUFaSbs"}

CORS¶

本节内容仅在跨域场景下有必要（例如你在 localhost:8081、localhost:8082 等不同端口上运行多个机器人 API），并希望将它们整合到一个 FreqUI 实例中。

技术说明

所有基于网页的前端都受CORS（跨域资源共享）限制。由于大多数对 Freqtrade API 的请求必须经过身份验证，因此合理的 CORS 策略对于避免安全问题至关重要。此外，标准不允许对带凭据的请求使用 * 通配符 CORS 策略，因此必须正确设置此项。

用户可以通过 CORS_origins 配置项，允许不同源 URL 访问机器人 API。该配置包含一个允许访问机器人 API 资源的 URL 列表。

假设您的应用部署在 https://frequi.freqtrade.io/home/，则需要进行如下配置：

{
    //...
    "jwt_secret_key": "somethingrandom",
    "CORS_origins": ["https://frequi.freqtrade.io"],
    //...
}

在以下这个相当常见的情况中，FreqUI 可通过 http://localhost:8080/trade 访问（即您在导航至 FreqUI 时浏览器地址栏显示的内容）。 freqUI url

此情况下的正确配置为 http://localhost:8080 —— 即包含端口的 URL 主体部分。

{
    //...
    "jwt_secret_key": "somethingrandom",
    "CORS_origins": ["http://localhost:8080"],
    //...
}

尾部斜杠

CORS_origins 配置中不允许使用尾部斜杠（例如 "http://localhost:8080/"）。此类配置将不会生效，且 CORS 错误仍会存在。

注意

我们强烈建议您将 jwt_secret_key 设置为只有您自己知道的随机字符串，以防止他人未经授权访问您的机器人。