REST API和FreqUI¶

FreqUI¶

Freqtrade提供了一个内置的Web服务器，可以为FreqUI提供服务，这是freqtrade的用户界面。

默认情况下，UI不会被包含在安装中（除了Docker映像），必须使用freqtrade install-ui显式安装它。如果有新的版本发布，可以使用相同的命令更新freqUI。

一旦机器人以交易/模拟交易模式启动（使用freqtrade trade），UI将在下面配置的端口下可用（通常为http://127.0.0.1:8080）。

开发人员

开发人员不应使用此方法，而应使用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/UI 访问

如果您在 VPS 上运行，请考虑使用 SSH 隧道，或设置 VPN（openVPN、wireguard）以连接到您的机器人。这将确保 freqUI 不直接暴露在互联网上，出于安全原因不建议这样做（freqUI 默认不支持 HTTPS）。此教程不包括这些工具的设置，但可以在互联网上找到许多优秀的教程。

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

{"status":"pong"}

所有其他端点都返回敏感信息，并且需要身份验证，因此不能通过 Web 浏览器访问。

安全性¶

要生成一个安全的密码，最好使用密码管理器，或使用下面的代码。

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，API将对连接到服务器的每个人在正确的端口下可用，所以其他人可能能够控制你的机器人。

REST API¶

调用API¶

你可以使用脚本 scripts/rest_client.py 来调用API。该客户端脚本只需要 requests 模块，因此不需要在系统上安装Freqtrade。

python3 scripts/rest_client.py <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!",
        //...
    }
}

python3 scripts/rest_client.py --config rest_config.json <command> [optional parameters]

可用的端点¶

命令	描述
`ping`	测试API的可用性的简单命令 - 不需要身份验证。
`start`	启动交易员。
`stop`	停止交易员。
`stopbuy`	停止交易员开立新交易。根据规则优雅地关闭待处理的交易。
`reload_config`	重新加载配置文件。
`trades`	列出最近的交易。每次调用限定为500个交易。
`trade/<tradeid>`	获取特定的交易。
`trades/<tradeid>`	DELETE - 从数据库中删除交易。尝试关闭待处理的订单。需要在交易所上手动处理这笔交易。
`trades/<tradeid>/open-order`	DELETE - 取消此交易的待处理订单。
`trades/<tradeid>/reload`	GET - 重新从交易所加载交易。仅适用于实盘，并有可能帮助恢复在交易所上手动售出的交易。
`show_config`	显示当前配置的一部分与操作相关的设置。
`logs`	显示最后的日志消息。
`status`	列出所有待处理的交易。
`count`	显示已使用和可用的交易数量。
`entries [pair]`	显示给定交易对每个进入标签的利润统计，如果没有给出交易对则显示所有交易对。交易对是可选的。
`exits [pair]`	显示给定交易对每个退出原因的利润统计，如果没有给出交易对则显示所有交易对。交易对是可选的。
`mix_tags [pair]`	显示给定交易对每个进入标签 + 退出原因的组合的利润统计，如果没有给出交易对则显示所有交易对。交易对是可选的。
`locks`	显示当前锁定的交易对。
`delete_lock <lock_id>`	通过ID删除（禁用）锁定。
`profit`	显示您从已关闭交易中的利润/损失摘要以及有关您业绩的一些统计信息。
`forceexit <trade_id>`	立即退出给定的交易（忽略 `minimum_roi`）。
`forceexit all`	立即退出所有待处理的交易（忽略 `minimum_roi`）。
`forceenter <pair> [rate]`	立即进入给定的交易对。利率是可选的。 (`force_entry_enable` 必须设置为 True)
`forceenter <pair> <side> [rate]`	立即做多或做空给定的交易对。利率是可选的。 (`force_entry_enable` 必须设置为 True)
`performance`	按交易对分组显示每笔已完成交易的业绩。
`balance`	显示每个货币的账户余额。
`daily <n>`	显示最近 n 天的每日盈亏（默认为 7 天）。
`weekly <n>`	显示最近 n 天的每周盈亏（默认为 4 周）。
`monthly <n>`	显示最近 n 天的每月盈亏（默认为 3 个月）。
`stats`	显示利润/损失原因的摘要以及平均持仓时间。
`whitelist`	显示当前的白名单。
`blacklist [pair]`	显示当前的黑名单，或将交易对添加到黑名单。
`edge`	显示启用时的验证交易对。
`pair_candles`	在机器人运行时返回给定交易对/时间框架组合的数据帧。Alpha
`pair_history`	返回给定时间范围内由给定策略分析的数据帧。Alpha
`plot_config`	从策略中获取绘图配置（如果未配置则不返回任何内容）。Alpha
`strategies`	列出策略目录中的策略。Alpha
`strategy <strategy>`	获取特定策略的内容。Alpha
`available_pairs`	列出可用的回测数据。Alpha
`version`	显示版本。
`sysinfo`	显示系统负载信息。
`health`	显示机器人运行状况（最后一个机器人循环）。

Alpha 状态

上述带有Alpha状态标签的端点可能会随时更改，恕不另行通知。

可以使用 rest-client 脚本的 help 命令列出可能的命令。

python3 scripts/rest_client.py help

Possible commands:

available_pairs
获取基于时间框架/投注货币选择的可用交易对（回测数据）

    :param timeframe: 仅包含此时间框架的交易对可用。
    :param stake_currency: 仅包含此投注货币的交易对。

balance
获取账户余额。

blacklist
显示当前黑名单。

    :param add: 要添加的加密货币列表（示例："BNB/BTC"）。

cancel_open_order
取消待交易的挂单。

    :param trade_id: 取消该交易的待交易挂单。

count
返回待开交易的数量。

daily
返回每天的盈利情况和交易数量。

delete_lock
从数据库中删除（禁用）锁。

delete_trade
    从数据库中删除交易。
    尝试关闭未完成订单。需要在交易所上手动处理此资产。

    :param trade_id: 从数据库中删除该ID对应的交易。

edge
    返回关于边缘的信息。

forcebuy
    购买资产。

    :param pair: 要购买的交易对（ETH/BTC）
    :param price: 可选 - 购买价格

forceenter
    强制进入一个交易。

    :param pair: 要购买的交易对（ETH/BTC）
    :param side: 'long' 或 'short'
    :param price: 可选 - 购买价格

forceexit
    强制退出一个交易。

    :param tradeid: 交易的ID（可通过状态命令获得）
    :param ordertype: 要使用的订单类型（必须是市价或限价）
    :param amount: 要出售的数量。如果未指定，则全部出售。

health
    提供运行中机器人的快速健康检查。

locks
    返回当前的锁定状态。

logs
    显示最新的日志。

        :param limit: 将日志消息限制为最后的 <limit> 条日志。未设置限制则获取整个日志。

pair_candles
    返回 <pair><timeframe> 的实时数据框。

        :param pair: 要获取数据的交易对
        :param timeframe: 仅显示带有此时间间隔的交易对。
        :param limit: 限制结果为最后的 n 个蜡烛图。

pair_history
    返回历史分析的数据框。

        :param pair: 要获取数据的交易对
        :param timeframe: 仅显示带有此时间间隔的交易对。
        :param strategy: 用于分析和获取值的策略
        :param timerange: 获取数据的时间范围（与 --timerange 端点的格式相同）

performance
    返回不同币种的性能。

ping
    简单的 ping 操作。

plot_config
    如果策略定义了配置文件，则返回配置文件。

profit
    返回利润汇总。

reload_config
    重新加载配置文件。

show_config
    返回与交易操作相关的部分配置。

start
    如果机器人处于停止状态，则启动机器人。

stats
    返回统计报告（持续时间、卖出原因）。

status
    获取开放交易的状态。

stop
    停止机器人。使用`start`重新启动。

stopbuy
    停止购买（但优雅地处理卖出）。使用`reload_config`重置。

strategies
    列出可用的策略。

strategy
    获取策略详情

        :param strategy: 策略类名

sysinfo
    提供系统信息（CPU，RAM 使用情况）

trade
    返回特定交易

        :param trade_id: 指定要获取的交易。

trades
    返回交易历史，按照id排序

        :param limit: 限制交易数量为X。 最多500个交易。
        :param offset: 偏移该数量的交易。

version
    返回机器人的版本。

whitelist
    显示当前白名单。

WebSocket消息¶

API服务器包括一个WebSocket端点，用于订阅来自freqtrade Bot的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，Bot 将向订阅它们的任何订阅者广播 RPC 消息。要订阅消息列表，您必须通过 WebSocket 发送像下面这样的 JSON 请求。data 键必须是一个消息类型字符串的列表。

{
  "type": "subscribe",
  "data": ["whitelist", "analyzed_df"] // 消息类型字符串的列表
}

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

现在，只要 Bot 发送这些类型的 RPC 消息，只要连接处于活动状态，您就会通过 WebSocket 收到它们。它们通常与请求具有相同的形式：

{
  "type": "analyzed_df",
  "data": {
      "key": ["NEO/BTC", "5m", "spot"],
      "df": {}, // 数据帧
      "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证书，通过上述任何反向代理使用加密连接访问您的机器人UI。虽然这将保护您的数据在传输过程中，但我们不建议在您的私有网络（VPN、SSH隧道）之外运行freqtrade API。

OpenAPI接口¶

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

使用JWT令牌进行高级API使用¶

注意

以下内容应在一个应用程序中执行（一个可以通过API获取信息的Freqtrade REST API客户端），不适合经常使用。

Freqtrade的REST API还提供JWT（JSON Web Tokens）。您可以使用以下命令登录，并随后使用生成的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"
# 使用access_token进行身份验证
> curl -X GET --header "Authorization: Bearer ${access_token}" http://localhost:8080/api/v1/count

由于访问令牌的有效期很短（15分钟），应定期使用token/refresh请求获取新的访问令牌：

> 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实例中）才需要整个部分。

技术解释

所有基于Web的前端都受到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时，在导航栏中可以看到此URL）。 freqUI url

该情况的正确配置是 http://localhost:8080 - 包括端口在内的URL的主要部分。

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

注意

我们强烈建议将 jwt_secret_key 也设置为一个随机且只有您自己知道的值，以避免未经授权访问您的机器人。