> ## Documentation Index
> Fetch the complete documentation index at: https://ton.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-Host API v2 (TON HTTP API)

## Overview

This guide explains how to self-host the TON HTTP API (v2) locally using either:

* **Docker (recommended for production setups):** Works on any x86\_64 and arm64 OS with Docker available.
* **Python (lightweight, for testing only):** Works on Ubuntu Linux (x86\_64, arm64), MacOSX (Intel x86\_64, Apple M1 arm64) and Windows (x86\_64).

***

## Recommended Hardware

* **CPU architecture:** x86\_64 or arm64.
* **HTTP API only:** 1 vCPU, 2 GB RAM.
* **HTTP API with cache enabled:** 2 vCPUs, 4 GB RAM.

***

## Option 1: Run via Docker (recommended)

### Prerequisites

Before you begin, make sure the following tools are installed on your system:

* **Docker**
* **Docker Compose** (preferably version 2 or higher)
* **curl**

<Accordion title="How to install prerequisites">
  - **macOS and Windows**:\
    Download and install [Docker Desktop](https://www.docker.com/products/docker-desktop), which includes both Docker and Docker Compose.

  - **Ubuntu/Linux**:\
    Navigate to the root of the repository and run the setup script:

    ```bash theme={null}
    scripts/setup.sh
    ```
</Accordion>

### 1. Clone the repository

```bash theme={null}
git clone https://github.com/toncenter/ton-http-api.git
cd ton-http-api
```

### 2. Download TON config files

```bash theme={null}
mkdir private
curl -sL https://ton-blockchain.github.io/global.config.json > private/mainnet.json
curl -sL https://ton-blockchain.github.io/testnet-global.config.json > private/testnet.json
```

### 3. Generate the `.env` file

Choose the network you want to use:

* **Testnet**:

```bash theme={null}
export TON_API_TONLIB_LITESERVER_CONFIG=private/testnet.json
./configure.py
```

* **Mainnet**:

```bash theme={null}
export TON_API_TONLIB_LITESERVER_CONFIG=private/mainnet.json
./configure.py
```

<Note>
  The generated `.env` file includes default configuration options.\
  To customize settings or see all available environment variables, check the [Configuration](#configuration) section.
</Note>

### 4. Build and run the container

```bash theme={null}
docker-compose build
docker-compose up -d
```

<Tip>Run `docker-compose down` to stop the container.</Tip>

### Test your API

Check masterchain info:

```bash theme={null}
curl http://localhost/getMasterchainInfo
```

Query a specific address:

```bash theme={null}
curl -X GET \
  'http://localhost/getAddressInformation?address=Uf_mlXHnufWO3-vvopflR_NpIFMiidvp_xt20Qf8usMBBPEE' \
  -H 'accept: application/json'
```

<Tip>You can also make API calls via the Swagger interface on `http://localhost:80`</Tip>

### Switch between Mainnet and Testnet

To switch networks:

```bash theme={null}
export TON_API_TONLIB_LITESERVER_CONFIG=private/mainnet.json  # or private/testnet.json
./configure.py
docker-compose down
docker-compose up -d
```

This updates the `.env` file and restarts the container with the selected network config.

### Video Walkthrough

[▶️ Watch Guide](https://www.canva.com/design/DAGuzMRoHjI/7FaLbvC29bSmS_JFykiu2g/watch?utm_content=DAGuzMRoHjI\&utm_campaign=designshare\&utm_medium=link2\&utm_source=uniquelinks\&utlId=h72f6e944b5)

***

## Option 2: Run with Python (testing only)

### Prerequisites

Before you begin, make sure the following tools are installed on your system:

* **Python 3.8+**
* **pip**
* **curl**

<Accordion title="How to install prerequisites">
  - **macOS and Windows**:\
    Python is usually pre-installed. If not, download it from [python.org](https://www.python.org/downloads/).\
    Then, install the package:

    ```bash theme={null}
    pip install ton-http-api
    ```

  - **Ubuntu/Linux**:\
    Install Python and pip if needed:

    ```bash theme={null}
    sudo apt update
    sudo apt install python3 python3-pip
    pip3 install ton-http-api
    ```
</Accordion>

### 1. Install the package

```bash theme={null}
pip install ton-http-api
```

### 2. Run the service

* Default (Mainnet):

```bash theme={null}
ton-http-api
```

* Testnet:

```bash theme={null}
ton-http-api --liteserver-config https://ton.org/testnet-global.config.json
```

or

```bash theme={null}
TON_API_TONLIB_LITESERVER_CONFIG=https://ton.org/testnet-global.config.json ton-http-api
```

<Note> Run `ton-http-api --help` to show the list of available options and commands or check the [configuration](#configuration) section. </Note>

### Test your API

Check masterchain info:

```bash theme={null}
curl http://localhost/getMasterchainInfo
```

Query a specific address:

```bash theme={null}
curl -X GET \
  'http://localhost/getAddressInformation?address=Uf_mlXHnufWO3-vvopflR_NpIFMiidvp_xt20Qf8usMBBPEE' \
  -H 'accept: application/json'
```

<Tip>You can also make API calls via the Swagger interface on `http://localhost:80`</Tip>

### Video Walkthrough

[▶️ Watch Guide](https://www.canva.com/design/DAGuygDmwKk/TxCNWeDg4QjdTUSKkhAa2A/watch?utm_content=DAGuygDmwKk\&utm_campaign=designshare\&utm_medium=link2\&utm_source=uniquelinks\&utlId=hed091a20b9)

## Configuration

TON HTTP API can be customized through environment variables (used by Docker and also respected by Python) or command-line flags (Python only).

<Accordion title="Docker Environment Variables">
  ### Webserver

  | Variable                      | Default   | Description                                                           |
  | ----------------------------- | --------- | --------------------------------------------------------------------- |
  | `TON_API_HTTP_PORT`           | `80`      | HTTP port for the API service                                         |
  | `TON_API_ROOT_PATH`           | `/`       | Prefix path for reverse proxies (e.g., `/api/v2`)                     |
  | `TON_API_WEBSERVERS_WORKERS`  | `1`       | Number of Gunicorn workers (set to \~CPU cores / 2)                   |
  | `TON_API_GET_METHODS_ENABLED` | `1`       | Enables the `runGetMethod` endpoint                                   |
  | `TON_API_JSON_RPC_ENABLED`    | `1`       | Enables the JSON-RPC endpoint                                         |
  | `TON_API_LOGS_JSONIFY`        | `0`       | Print logs in JSON format                                             |
  | `TON_API_LOGS_LEVEL`          | `ERROR`   | Logging verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR`, or `CRITICAL` |
  | `TON_API_GUNICORN_FLAGS`      | *(empty)* | Extra Gunicorn CLI flags                                              |

  ### Tonlib

  | Variable                                          | Default                         | Description                             |
  | ------------------------------------------------- | ------------------------------- | --------------------------------------- |
  | `TON_API_TONLIB_LITESERVER_CONFIG`                | `private/mainnet.json` (Docker) | Path to LiteServer config file          |
  | `TON_API_TONLIB_KEYSTORE`                         | `/tmp/ton_keystore`             | Directory for tonlib keystore           |
  | `TON_API_TONLIB_PARALLEL_REQUESTS_PER_LITESERVER` | `50`                            | Max parallel requests per LiteServer    |
  | `TON_API_TONLIB_CDLL_PATH`                        | *(empty)*                       | Custom path to `tonlibjson` binary      |
  | `TON_API_TONLIB_REQUEST_TIMEOUT`                  | `10`                            | Timeout in seconds for LiteServer calls |

  ### Cache

  | Variable                       | Default       | Description                          |
  | ------------------------------ | ------------- | ------------------------------------ |
  | `TON_API_CACHE_ENABLED`        | `0`           | Enables Redis caching                |
  | `TON_API_CACHE_REDIS_ENDPOINT` | `cache_redis` | Redis host (e.g., in Docker Compose) |
  | `TON_API_CACHE_REDIS_PORT`     | `6379`        | Redis port                           |
  | `TON_API_CACHE_REDIS_TIMEOUT`  | `1`           | Redis timeout in seconds             |
</Accordion>

<Accordion title="Python Command-Line Flags">
  ### Webserver

  | Flag               | Description                                   |
  | ------------------ | --------------------------------------------- |
  | `--host`           | Host address to bind the HTTP API             |
  | `--port`           | HTTP port (equivalent to `TON_API_HTTP_PORT`) |
  | `--root`           | Root path prefix for endpoints                |
  | `--no-get-methods` | Disables `runGetMethod` endpoint              |
  | `--no-json-rpc`    | Disables JSON-RPC endpoint                    |

  ### Tonlib

  | Flag                                 | Description                            |
  | ------------------------------------ | -------------------------------------- |
  | `--liteserver-config`                | Path or URL to LiteServer config file  |
  | `--tonlib-keystore`                  | Path to keystore directory             |
  | `--parallel-requests-per-liteserver` | Max concurrent requests per LiteServer |
  | `--cdll-path`                        | Path to `tonlibjson` binary            |

  ### Cache

  | Flag                     | Description           |
  | ------------------------ | --------------------- |
  | `--cache`                | Enables Redis caching |
  | `--cache-redis-endpoint` | Redis host            |
  | `--cache-redis-port`     | Redis port            |

  ### Logs

  | Flag             | Description                                     |
  | ---------------- | ----------------------------------------------- |
  | `--logs-level`   | Logging level: `DEBUG`, `INFO`, `WARNING`, etc. |
  | `--logs-jsonify` | Print logs in JSON format                       |

  ### Other

  | Flag        | Description                              |
  | ----------- | ---------------------------------------- |
  | `--version` | Show the current version of the CLI tool |
</Accordion>