---
title: "Deploy V2 Script"
method: POST
path: "/bot-orchestration/deploy-v2-script"
tags: ["Bot Orchestration"]
---

# Deploy V2 Script

`POST /bot-orchestration/deploy-v2-script`

Deploy a new Hummingbot instance with a V2 script.

Creates a new Docker container running Hummingbot configured with a specified
script and optional script configuration. The container is automatically started
and begins executing the trading strategy.

This is the primary method for deploying custom scripts. For controller-based
strategies, use deploy-v2-controllers instead.

The deployment process:
1. Creates a new Docker container from the specified Hummingbot image
2. Mounts necessary volumes (configs, credentials, scripts)
3. Sets up MQTT communication for bot control
4. Creates a bot run record in the database for tracking
5. Starts the container with the specified script (if auto-start enabled)

## Request body

- V2ScriptDeployment — Configuration for deploying a Hummingbot instance with a V2 script. This model defines all parameters needed to create and start a new bot container running a custom trading script. The bot will be deployed as a Docker container with all necessary volumes mounted. Example: { "instance_name": "my-scalping-bot", "credentials_profile": "binance_main", "image": "hummingbot/hummingbot:1.26.0", "script": "v2_with_controllers", "script_config": "scalper_config", "headless": false }
  - `instance_name` string, required — Unique name for the bot instance. This becomes the Docker container name and is used to identify the bot in all subsequent operations. Use descriptive names like 'btc-maker' or 'eth-arb'. Avoid special characters except hyphens.
  - `credentials_profile` string, required — Name of the exchange credentials profile to use. The profile must exist in the credentials directory (credentials/{profile_name}.yml). Contains API keys and secrets for exchange authentication.
  - `image` string — Docker image to use for the Hummingbot instance. Use 'latest' for the most recent version or specify a tag for version pinning (recommended for production). Custom images can also be used if they're based on the official Hummingbot image.
  - `script` string, nullable — Name of the Python script to run (without .py extension). The script must exist in the scripts directory. If not specified, the bot starts without running a script and must be started manually via the start-bot endpoint.
  - `script_config` string, nullable — Name of the script configuration file (without .yml extension). Must exist in conf/scripts/ directory. Contains strategy-specific parameters like trading pairs, order sizes, and spread settings. Required if the script needs configuration.
  - `headless` boolean — When True, runs the bot without the terminal UI. Reduces resource usage but removes the ability to interact with the bot directly via terminal. Recommended for production deployments that are fully managed via API.

## Response `200`

Successful Response

- object

## Other responses

- `422` — Validation Error

## Changes

- **2026-01-18** `576ec8539f76` — 1 breaking
  - the response's body type/format changed from ``/`` to `object`/`` for status `200`
- **2025-12-20** `1005bcd47280` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/hummingbot/apis/hummingbot-api/changes/bot-orchestration/deploy-v2-script/post.md)

---

[API](https://skmtc.dev/hummingbot/apis/hummingbot-api.md) · [All operations](https://skmtc.dev/hummingbot/apis/hummingbot-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/hummingbot/hummingbot-api/revisions/576ec8539f76/schema)