api-reference.mdx

title	API Reference
description	Complete REST API reference for Hummingbot API

What is Hummingbot API?

Hummingbot API is a RESTful API server that provides programmatic access to Hummingbot exchange connectors and trading strategies. It is the execution layer under Condor, and it handles:

• Data collection: standardized access to order books, candles, balances and positions across many exchanges
• Market access: connectors to spot and perpetual exchanges, plus DEXs on Solana and EVM networks through Gateway
• Trade execution: place orders, manage positions and track fills
• Bot management: deploy and manage containerized bots for long-running strategies

Base URL

http://localhost:8000

The API listens on 127.0.0.1 only by default, so it is reachable from the machine it runs on and nowhere else. To reach it from another machine, you have two options:

• Tailscale (recommended): make setup asks whether to use Tailscale. See Secure Remote Access with Tailscale.
• API_BIND: set API_BIND in the API's .env to the address to publish port 8000 on, then run make deploy again. Prefer a specific interface, such as your Tailscale IP, over 0.0.0.0. Anyone who reaches this API can move your funds.

API_BIND applies to the Docker install (make deploy). For where every service binds, see What binds where by default.

Authentication

Every REST endpoint except three requires HTTP Basic authentication:

curl -u YOUR_USERNAME:YOUR_PASSWORD http://localhost:8000/accounts/

A missing or wrong username or password returns 401 with {"detail": "Incorrect username or password"}.

These three paths need no credentials:

Path	What it returns
/	The API's name, version and status
/docs	The API's own interactive Swagger UI
/openapi.json	The OpenAPI spec this reference is generated from

The username and password are the USERNAME and PASSWORD that make setup asks for and writes to the API's .env. Condor keeps a copy for each server in its config.yml under servers:.

If `USERNAME` and `PASSWORD` are not set, the API does not refuse to start. It falls back to `admin` / `admin` (and `CONFIG_PASSWORD` to `a`) and logs a `SECURITY WARNING`. Anyone who can reach the API can then log in. Always run `make setup`, or set all three values in `.env`, before you start the API.

WebSocket authentication

The API also streams data over two WebSocket endpoints. They are not in the OpenAPI spec, so they don't appear in the sidebar:

Endpoint	Streams
ws://localhost:8000/ws/market-data	Candles, order book snapshots and trades
ws://localhost:8000/ws/executors	Executors, executor summary and logs, performance, positions and bot status

A WebSocket handshake authenticates in one of two ways. Without either, the server answers 401 and never opens the socket.

• Authorization: Basic base64(username:password): the same header the REST endpoints use. Use it from any client that can set headers.
• The hummingbot-auth subprotocol: browsers can't set headers on a WebSocket, so send the credentials as the second subprotocol, encoded as base64url. The server echoes hummingbot-auth back.

const token = btoa("YOUR_USERNAME:YOUR_PASSWORD")
  .replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
const ws = new WebSocket("ws://localhost:8000/ws/executors", ["hummingbot-auth", token]);

The server never reads credentials from the query string.

API Routers

The tables below are a tour of the API's routers, with the endpoints you will reach for first. The sidebar has the complete reference for every endpoint, generated from the API's own OpenAPI spec.

Accounts

Manage trading accounts, exchange credentials and Gateway wallets. For the Workspace and Telegram flows, see Exchange Credentials.

Endpoint	Method	Description
/accounts/	GET	List all account names
/accounts/{account_name}/credentials	GET	List configured connectors for an account
/accounts/add-account	POST	Create a new account
/accounts/delete-account	POST	Delete an account
/accounts/add-credential/{account_name}/{connector_name}	POST	Add exchange credentials
/accounts/delete-credential/{account_name}/{connector_name}	POST	Remove exchange credentials
/accounts/gateway/wallets	GET	List Gateway wallets
/accounts/gateway/add-wallet	POST	Add a Gateway (DEX) wallet
/accounts/gateway/wallet/set-default	POST	Set the default wallet for a chain
/accounts/gateway/{chain}/{address}	DELETE	Remove a Gateway wallet

Portfolio

Balances and portfolio analytics.

Endpoint	Method	Description
/portfolio/state	POST	Get balances across all accounts and connectors
/portfolio/history	POST	Get historical portfolio states
/portfolio/distribution	POST	Token distribution across accounts
/portfolio/accounts-distribution	GET	Value distribution by account

Trading

Place orders and manage positions.

Endpoint	Method	Description
/trading/orders	POST	Place a new order
/trading/orders/active	POST	Get active orders
/trading/orders/search	POST	Search order history
/trading/trades	POST	Search trade fills
/trading/{account_name}/{connector_name}/orders/{client_order_id}/cancel	POST	Cancel an order
/trading/positions	POST	Get open perpetual positions
/trading/{account_name}/{connector_name}/leverage	POST	Set leverage
/trading/{account_name}/{connector_name}/position-mode	GET, POST	Get or set position mode
/trading/funding-payments	POST	Get funding payment history

Connectors

Exchange connector information and trading rules.

Endpoint	Method	Description
/connectors/	GET	List available connectors
/connectors/{connector_name}/config-map	GET	Get required credential fields
/connectors/{connector_name}/trading-rules	GET	Get trading rules for pairs
/connectors/{connector_name}/order-types	GET	Get supported order types

Market Data

Prices, candles, order books, tickers and conversion rates.

Endpoint	Method	Description
/market-data/candles	POST	Get real-time candles
/market-data/historical-candles	POST	Get historical candles
/market-data/order-book	POST	Get an order book snapshot
/market-data/prices	POST	Get current prices
/market-data/tickers	GET	Get 24h ticker stats
/market-data/funding-info	POST	Get perpetual funding info
/market-data/rate/{trading_pair}	GET	Get the conversion rate for a pair
/market-data/rates	POST	Get conversion rates in bulk
/market-data/pool-prices	GET	Get DEX pool prices
/market-data/settings	GET	Read the server's market data settings (MARKET_DATA_*)

Executors

Create and manage executors: self-contained trading operations such as an order, a position with stop loss and take profit, a grid or an LP position. See Executors.

Endpoint	Method	Description
/executors/	POST	Create a new executor
/executors/search	POST	List and filter executors
/executors/{executor_id}	GET	Get executor details
/executors/{executor_id}/stop	POST	Stop an executor
/executors/{executor_id}/logs	GET	Get executor logs
/executors/summary	GET	Summary of active executors
/executors/performance	GET	Aggregate executor performance
/executors/positions/summary	GET	Summary of executor-held positions
/executors/types/available	GET	List available executor types
/executors/types/{executor_type}/config	GET	Get an executor type's config schema

Performance

One interface for the performance of both bot controllers and executors. Pass subject=controller or subject=executor.

Endpoint	Method	Description
/performance/latest	GET	The latest performance row for each controller or executor
/performance/history	GET	Performance over time, with optional start_time and end_time

curl -u YOUR_USERNAME:YOUR_PASSWORD \
  "http://localhost:8000/performance/latest?subject=executor&limit=10"

Filters belong to one subject. bot_name works only with subject=controller. executor_id, executor_type, account_name, connector_name and trading_pair work only with subject=executor. controller_id works with both. A filter sent with the wrong subject returns 400.

Bot Orchestration

Deploy and manage containerized Hummingbot bots.

Endpoint	Method	Description
/bot-orchestration/status	GET	Get status of all bots
/bot-orchestration/deploy-v2-controllers	POST	Deploy a bot running V2 controllers
/bot-orchestration/deploy-v2-script	POST	Deploy a bot running a V2 script
/bot-orchestration/start-bot	POST	Start a bot
/bot-orchestration/stop-bot	POST	Stop a bot
/bot-orchestration/stop-and-archive-bot/{bot_name}	POST	Stop a bot and archive its database
/bot-orchestration/{bot_name}/status	GET	Get one bot's status
/bot-orchestration/bot-runs	GET	List bot runs
/bot-orchestration/controller-performance-latest	GET	Latest per-controller performance
/bot-orchestration/rate-oracle/config	GET, PUT	Read or change the rate oracle, global token and rate-limit share that newly deployed bots use
/bot-orchestration/rate-oracle/sources	GET	List the rate oracle sources a bot can use

Controllers

V2 strategy controller management.

Endpoint	Method	Description
/controllers/	GET	List available controllers
/controllers/{controller_type}/{controller_name}	GET, POST, DELETE	Read, save or delete a controller
/controllers/configs/	GET	List controller configs
/controllers/configs/{config_name}	GET, POST, DELETE	Read, save or delete a config
/controllers/{controller_type}/{controller_name}/config/template	GET	Get a controller's config template
/controllers/{controller_type}/{controller_name}/config/validate	POST	Validate a config against its controller

Scripts

Script management.

Endpoint	Method	Description
/scripts/	GET	List available scripts
/scripts/{script_name}	GET, POST, DELETE	Read, save or delete a script
/scripts/configs/	GET	List script configs
/scripts/{script_name}/config/template	GET	Get a script's config template

Gateway

DEX infrastructure through Hummingbot Gateway: the Gateway container, its connectors, and per-network configuration (tokens and pools). See Gateway.

Endpoint	Method	Description
/gateway/status	GET	Get Gateway status
/gateway/start	POST	Start the Gateway container
/gateway/stop	POST	Stop the Gateway container
/gateway/restart	POST	Restart the Gateway container
/gateway/connectors	GET	List Gateway connectors
/gateway/chains	GET	List chains and their networks
/gateway/networks	GET	List supported networks
/gateway/networks/{network_id}	GET, POST	Read or update a network's config
/gateway/networks/{network_id}/tokens	GET, POST	List or add tokens on a network
/gateway/networks/{network_id}/pools	GET, POST	List or add pools on a network
/gateway/logs	GET	Get Gateway logs

Gateway Swaps

DEX token swaps.

Endpoint	Method	Description
/gateway/swap/quote	POST	Get a swap quote
/gateway/swap/execute	POST	Execute a swap
/gateway/swap/execute-quote	POST	Execute a previously fetched quote
/gateway/swaps/search	POST	Search past swaps
/gateway/swaps/{transaction_hash}/status	GET	Get a swap's transaction status

Gateway CLMM

Concentrated-liquidity positions. To run a position with automatic monitoring and closing, use an LP executor instead.

Endpoint	Method	Description
/gateway/clmm/pools	GET	List pools (Meteora and Orca only)
/gateway/clmm/pool-info	GET	Get one pool's live state
/gateway/clmm/quote-position	POST	Quote a new position
/gateway/clmm/open	POST	Open a new position
/gateway/clmm/add	POST	Add liquidity to a position
/gateway/clmm/remove	POST	Remove liquidity from a position
/gateway/clmm/close	POST	Close a position
/gateway/clmm/collect-fees	POST	Collect accumulated fees
/gateway/clmm/positions_owned	POST	Get the LP positions a wallet owns

Gateway AMM

Classic (full-range) AMM liquidity.

Endpoint	Method	Description
/gateway/amm/pool-info	GET	Get one pool's live state
/gateway/amm/quote-liquidity	POST	Quote adding liquidity
/gateway/amm/add-liquidity	POST	Add liquidity
/gateway/amm/remove-liquidity	POST	Remove liquidity
/gateway/amm/positions-owned	POST	Get AMM positions owned

Backtesting

Strategy backtesting, synchronous or as background tasks.

Endpoint	Method	Description
/backtesting/run	POST	Run a backtest synchronously
/backtesting/tasks	POST	Start a backtest as a background task
/backtesting/tasks	GET	List backtest tasks
/backtesting/tasks/{task_id}	GET	Get a task's status and results
/backtesting/tasks/{task_id}	DELETE	Cancel or delete a task

Archived Bots

Historical bot performance data.

Endpoint	Method	Description
/archived-bots/	GET	List archived bot databases
/archived-bots/{db_path}/summary	GET	Summary of an archived run
/archived-bots/{db_path}/performance	GET	Get historical performance
/archived-bots/{db_path}/trades	GET	Trades from an archived run
/archived-bots/{db_path}	DELETE	Delete an archived database

Docker

Container lifecycle management.

Endpoint	Method	Description
/docker/running	GET	Check if Docker is running
/docker/active-containers	GET	List active containers
/docker/available-images/	GET	List available bot images
/docker/pull-image/	POST	Pull an image
/docker/clean-exited-containers	POST	Remove exited containers

Storage and System

The API's disk usage, the host's resources, and the API's own version and upgrades.

Endpoint	Method	Description
/storage/	GET	Storage overview: databases, archives, disk usage
/system/resources	GET	CPU, memory and disk for the API host
/system/info	GET	API and Hummingbot versions, and how the API container was deployed
/system/upgrade/preflight	GET	Whether the API can upgrade itself, and which executors and bots are running
/system/upgrade	POST	Upgrade the API container to the published image
/system/upgrade/status	GET	Status of the current or last upgrade

Condor's Settings → Hummingbot API panel uses the /system/* endpoints for its Version and Upgrade cards. See Settings.

Response Format

Success responses return the requested data:

["master_account"]

Error responses include a detail field:

{
  "detail": "Incorrect username or password"
}

Trying endpoints

The easiest place to try requests is the API's own Swagger UI at http://localhost:8000/docs, on the machine that runs the API. Click Authorize and enter your username and password.

Each endpoint page in this reference also has a playground. It sends requests straight from your browser to the server URL, http://localhost:8000 by default. The API accepts browser requests only from pages served on localhost or 127.0.0.1, so it rejects the playground on this site (a CORS error). A local preview of these docs (npx mint@latest dev, on localhost:3000) is allowed.

To let this site's playground through, add its origin to the API's .env as a JSON list, then run make deploy again:

CORS_ALLOW_ORIGINS='["https://condor.hummingbot.org"]'

Only add origins you trust. Any page on an allowed origin can call your API from your browser. CORS_ALLOW_ORIGIN_REGEX holds the default localhost rule; set it to an empty string to turn that rule off.

Resources

Condor source code Hummingbot API source code Community support 2-minute survey that shapes the roadmap