Skip to main content

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

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:
A missing or wrong username or password returns 401 with {"detail": "Incorrect username or password"}. These three paths need no credentials: 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: 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.
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.

Portfolio

Balances and portfolio analytics.

Trading

Place orders and manage positions.

Connectors

Exchange connector information and trading rules.

Market Data

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

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.

Performance

One interface for the performance of both bot controllers and executors. Pass subject=controller or subject=executor.
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.

Controllers

V2 strategy controller management.

Scripts

Script management.

Gateway

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

Gateway Swaps

DEX token swaps.

Gateway CLMM

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

Gateway AMM

Classic (full-range) AMM liquidity.

Backtesting

Strategy backtesting, synchronous or as background tasks.

Archived Bots

Historical bot performance data.

Docker

Container lifecycle management.

Storage and System

The API’s disk usage, the host’s resources, and the API’s own version and upgrades. 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:
Error responses include a detail field:

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

Condor source code

API GitHub

Hummingbot API source code

Discord

Community support

Give Feedback

2-minute survey that shapes the roadmap