7.9 KiB
REST API Usage
Configuration
Enable the rest API by adding the api_server section to your configuration and setting api_server.enabled to true.
Sample configuration:
"api_server": {
"enabled": true,
"listen_ip_address": "127.0.0.1",
"listen_port": 8080,
"username": "Freqtrader",
"password": "SuperSecret1!"
},
!!! Danger "Security warning" By default, the configuration listens on localhost only (so it's not reachable from other systems). We strongly recommend to not expose this API to the internet and choose a strong, unique password, since others will potentially be able to control your bot.
!!! Danger "Password selection" Please make sure to select a very strong, unique password to protect your bot from unauthorized access.
You can then access the API by going to http://127.0.0.1:8080/api/v1/ping in a browser to check if the API is running correctly.
This should return the response:
{"status":"pong"}
All other endpoints return sensitive info and require authentication, so are not available through a web browser.
To generate a secure password, either use a password manager, or use the below code snipped.
import secrets
secrets.token_hex()
Configuration with docker
If you run your bot using docker, you'll need to have the bot listen to incomming connections. The security is then handled by docker.
"api_server": {
"enabled": true,
"listen_ip_address": "0.0.0.0",
"listen_port": 8080
},
Add the following to your docker command:
-p 127.0.0.1:8080:8080
A complete sample-command may then look as follows:
docker run -d \
--name freqtrade \
-v ~/.freqtrade/config.json:/freqtrade/config.json \
-v ~/.freqtrade/user_data/:/freqtrade/user_data \
-v ~/.freqtrade/tradesv3.sqlite:/freqtrade/tradesv3.sqlite \
-p 127.0.0.1:8080:8080 \
freqtrade trade --db-url sqlite:///tradesv3.sqlite --strategy MyAwesomeStrategy
!!! Danger "Security warning"
By using -p 8080:8080 the API is available to everyone connecting to the server under the correct port, so others may be able to control your bot.
Consuming the API
You can consume the API by using the script scripts/rest_client.py.
The client script only requires the requests module, so Freqtrade does not need to be installed on the system.
python3 scripts/rest_client.py <command> [optional parameters]
By default, the script assumes 127.0.0.1 (localhost) and port 8080 to be used, however you can specify a configuration file to override this behaviour.
Minimalistic client config
{
"api_server": {
"enabled": true,
"listen_ip_address": "0.0.0.0",
"listen_port": 8080
}
}
python3 scripts/rest_client.py --config rest_config.json <command> [optional parameters]
Available commands
| Command | Default | Description |
|---|---|---|
start |
Starts the trader | |
stop |
Stops the trader | |
stopbuy |
Stops the trader from opening new trades. Gracefully closes open trades according to their rules. | |
reload_conf |
Reloads the configuration file | |
show_config |
Shows part of the current configuration with relevant settings to operation | |
status |
Lists all open trades | |
count |
Displays number of trades used and available | |
profit |
Display a summary of your profit/loss from close trades and some stats about your performance | |
forcesell <trade_id> |
Instantly sells the given trade (Ignoring minimum_roi). |
|
forcesell all |
Instantly sells all open trades (Ignoring minimum_roi). |
|
forcebuy <pair> [rate] |
Instantly buys the given pair. Rate is optional. (forcebuy_enable must be set to True) |
|
performance |
Show performance of each finished trade grouped by pair | |
balance |
Show account balance per currency | |
daily <n> |
7 | Shows profit or loss per day, over the last n days |
whitelist |
Show the current whitelist | |
blacklist [pair] |
Show the current blacklist, or adds a pair to the blacklist. | |
edge |
Show validated pairs by Edge if it is enabled. | |
version |
Show version |
Possible commands can be listed from the rest-client script using the help command.
python3 scripts/rest_client.py help
Possible commands:
balance
Get the account balance
:returns: json object
blacklist
Show the current blacklist
:param add: List of coins to add (example: "BNB/BTC")
:returns: json object
count
Returns the amount of open trades
:returns: json object
daily
Returns the amount of open trades
:returns: json object
edge
Returns information about edge
:returns: json object
forcebuy
Buy an asset
:param pair: Pair to buy (ETH/BTC)
:param price: Optional - price to buy
:returns: json object of the trade
forcesell
Force-sell a trade
:param tradeid: Id of the trade (can be received via status command)
:returns: json object
performance
Returns the performance of the different coins
:returns: json object
profit
Returns the profit summary
:returns: json object
reload_conf
Reload configuration
:returns: json object
show_config
Returns part of the configuration, relevant for trading operations.
:return: json object containing the version
start
Start the bot if it's in stopped state.
:returns: json object
status
Get the status of open trades
:returns: json object
stop
Stop the bot. Use start to restart
:returns: json object
stopbuy
Stop buying (but handle sells gracefully).
use reload_conf to reset
:returns: json object
version
Returns the version of the bot
:returns: json object containing the version
whitelist
Show the current whitelist
:returns: json object
Advanced API usage using JWT tokens
!!! Note The below should be done in an application, and is not intended to be used on a regular basis.
Freqtrade's REST API also offers JWT tokens. You can login using the following command, and subsequently use the resulting 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 tccess_token for authentication
> curl -X GET --header "Authorization: Bearer ${access_token}" http://localhost:8080/api/v1/count
Since the access-token has a short timeout (15 min) - the refresh-token should be used to get a fresh access token:
> curl -X POST --header "Authorization: Bearer ${refresh_token}"http://localhost:8080/api/v1/token/refresh
{"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1ODkxMTk5NzQsIm5iZiI6MTU4OTExOTk3NCwianRpIjoiMDBjNTlhMWUtMjBmYS00ZTk0LTliZjAtNWQwNTg2MTdiZDIyIiwiZXhwIjoxNTg5MTIwODc0LCJpZGVudGl0eSI6eyJ1IjoiRnJlcXRyYWRlciJ9LCJmcmVzaCI6ZmFsc2UsInR5cGUiOiJhY2Nlc3MifQ.1seHlII3WprjjclY6DpRhen0rqdF4j6jbvxIhUFaSbs"}