11---
2- title : Self-Host API v2 (TON HTTP API )
2+ title : Self-Host API v2 (HTTP)
33---
44
5- ## Overview
5+ ## Overview
66
77This guide explains how to self-host the TON HTTP API (v2) locally using either:
88
9- - ** Docker (recommended for production setups):** Works on any x86_64 and arm64 OS with Docker available.
10- - ** Python (lightweight, for testing only):** Works on Ubuntu Linux (x86_64 , arm64), MacOSX (Intel x86_64 , Apple M1 arm64) and Windows (x86_64 ).
9+ - ** Docker (recommended for production setups):** Works on any x86 \_ 64 and arm64 OS with Docker available.
10+ - ** Python (lightweight, for testing only):** Works on Ubuntu Linux (x86 \_ 64 , arm64), MacOSX (Intel x86 \_ 64 , Apple M1 arm64) and Windows (x86 \_ 64 ).
1111
1212## Recommended hardware
1313
14- - ** CPU architecture:** x86_64 or arm64.
14+ - ** CPU architecture:** x86 \_ 64 or arm64.
1515- ** HTTP API only:** 1 vCPU, 2 GB RAM.
1616- ** HTTP API with cache enabled:** 2 vCPUs, 4 GB RAM.
1717
18- ## Option 1: Run via Docker (recommended)
18+ ## Option 1: Run via Docker (recommended)
1919
2020### Prerequisites
2121
@@ -24,17 +24,19 @@ Before you begin, make sure the following tools are installed on your system:
2424- ** Docker**
2525- ** Docker Compose** (preferably version 2 or higher)
2626- ** curl**
27- <Accordion title = " How to install prerequisites" >
2827
29- - ** macOS and Windows** :
30- Download and install [ Docker Desktop] ( https://www.docker.com/products/docker-desktop ) , which includes both Docker and Docker Compose.
28+ <Accordion
29+ title = " How to install prerequisites"
30+ >
31+ * ** macOS and Windows** :\
32+ Download and install [ Docker Desktop] ( https://www.docker.com/products/docker-desktop ) , which includes both Docker and Docker Compose.
3133
32- - ** Ubuntu/Linux** :
33- Navigate to the root of the repository and run the setup script:
34+ * ** Ubuntu/Linux** :\
35+ Navigate to the root of the repository and run the setup script:
3436
35- ``` bash
36- scripts/setup.sh
37- ```
37+ ``` bash
38+ scripts/setup.sh
39+ ```
3840</Accordion >
3941
4042### 1. Clone the repository
@@ -71,8 +73,8 @@ export TON_API_TONLIB_LITESERVER_CONFIG=private/mainnet.json
7173```
7274
7375<Note >
74- The generated ` .env ` file includes default configuration options.
75- To customize settings or see all available environment variables, check the [ Configuration] ( #configuration ) section.
76+ The generated ` .env ` file includes default configuration options.\
77+ To customize settings or see all available environment variables, check the [ Configuration] ( #configuration ) section.
7678</Note >
7779
7880### 4. Build and run the container
@@ -117,7 +119,7 @@ This updates the `.env` file and restarts the container with the selected networ
117119
118120### Video walkthrough
119121
120- [ ▶️ 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 )
122+ [ ▶️ 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 )
121123
122124---
123125
@@ -131,24 +133,25 @@ Before you begin, make sure the following tools are installed on your system:
131133- ** pip**
132134- ** curl**
133135
134- <Accordion title = " How to install prerequisites" >
135-
136- - ** macOS and Windows** :
137- Python is usually pre-installed. If not, download it from [ python.org] ( https://www.python.org/downloads/ ) .
138- Then, install the package:
139-
140- ``` bash
141- pip install ton-http-api
142- ```
143-
144- - ** Ubuntu/Linux** :
145- Install Python and pip if needed:
146-
147- ``` bash
148- sudo apt update
149- sudo apt install python3 python3-pip
150- pip3 install ton-http-api
151- ```
136+ <Accordion
137+ title = " How to install prerequisites"
138+ >
139+ * ** macOS and Windows** :\
140+ Python is usually pre-installed. If not, download it from [ python.org] ( https://www.python.org/downloads/ ) .\
141+ Then, install the package:
142+
143+ ``` bash
144+ pip install ton-http-api
145+ ```
146+
147+ * ** Ubuntu/Linux** :\
148+ Install Python and pip if needed:
149+
150+ ``` bash
151+ sudo apt update
152+ sudo apt install python3 python3-pip
153+ pip3 install ton-http-api
154+ ```
152155</Accordion >
153156
154157### 1. Install the package
@@ -166,9 +169,11 @@ ton-http-api
166169```
167170
168171- Testnet:
172+
169173``` bash
170174ton-http-api --liteserver-config https://ton.org/testnet-global.config.json
171175```
176+
172177or
173178
174179``` bash
@@ -197,88 +202,88 @@ curl -X GET \
197202
198203### Video walkthrough
199204
200- [ ▶️ Watch Guide] ( https://www.canva.com/design/DAGuygDmwKk/TxCNWeDg4QjdTUSKkhAa2A/watch?utm_content=DAGuygDmwKk&utm_campaign=designshare&utm_medium=link2&utm_source=uniquelinks&utlId=hed091a20b9 )
205+ [ ▶️ Watch Guide] ( https://www.canva.com/design/DAGuygDmwKk/TxCNWeDg4QjdTUSKkhAa2A/watch?utm_content=DAGuygDmwKk\ & utm_campaign=designshare\ & utm_medium=link2\ & utm_source=uniquelinks\ & utlId=hed091a20b9 )
201206
202207## Configuration
203208
204209TON HTTP API can be customized through environment variables (used by Docker and also respected by Python) or command-line flags (Python only).
205210
206- <Accordion title = " Docker Environment Variables " >
207-
208- ### Webserver
209-
210- | Variable | Default | Description |
211- | ----------------------------- | --------- | ------------- |
212- | ` TON_API_HTTP_PORT ` | ` 80 ` | HTTP port for the API service |
213- | ` TON_API_ROOT_PATH ` | ` / ` | Prefix path for reverse proxies (e.g., ` /api/v2 ` ) |
214- | ` TON_API_WEBSERVERS_WORKERS ` | ` 1 ` | Number of Gunicorn workers (set to ~ CPU cores / 2) |
215- | ` TON_API_GET_METHODS_ENABLED ` | ` 1 ` | Enables the ` runGetMethod ` endpoint |
216- | ` TON_API_JSON_RPC_ENABLED ` | ` 1 ` | Enables the JSON-RPC endpoint |
217- | ` TON_API_LOGS_JSONIFY ` | ` 0 ` | Print logs in JSON format |
218- | ` TON_API_LOGS_LEVEL ` | ` ERROR ` | Logging verbosity: ` DEBUG ` , ` INFO ` , ` WARNING ` , ` ERROR ` , or ` CRITICAL ` |
219- | ` TON_API_GUNICORN_FLAGS ` | * (empty) * | Extra Gunicorn CLI flags |
220-
221- ### Tonlib
222-
223- | Variable | Default | Description |
224- | -------------------------------------- | ---------------------------------- | ------------- |
225- | ` TON_API_TONLIB_LITESERVER_CONFIG ` | ` private/mainnet.json ` (Docker) | Path to LiteServer config file |
226- | ` TON_API_TONLIB_KEYSTORE ` | ` /tmp/ton_keystore ` | Directory for tonlib keystore |
227- | ` TON_API_TONLIB_PARALLEL_REQUESTS_PER_LITESERVER ` | ` 50 ` | Max parallel requests per LiteServer |
228- | ` TON_API_TONLIB_CDLL_PATH ` | * (empty) * | Custom path to ` tonlibjson ` binary |
229- | ` TON_API_TONLIB_REQUEST_TIMEOUT ` | ` 10 ` | Timeout in seconds for LiteServer calls |
230-
231- ### Cache
232-
233- | Variable | Default | Description |
234- | ----------------------------- | -------------------- | ------------- |
235- | ` TON_API_CACHE_ENABLED ` | ` 0 ` | Enables Redis caching |
236- | ` TON_API_CACHE_REDIS_ENDPOINT ` | ` cache_redis ` | Redis host (e.g., in Docker Compose) |
237- | ` TON_API_CACHE_REDIS_PORT ` | ` 6379 ` | Redis port |
238- | ` TON_API_CACHE_REDIS_TIMEOUT ` | ` 1 ` | Redis timeout in seconds |
239-
211+ <Accordion
212+ title = " Docker Environment Variables "
213+ >
214+ ### Webserver
215+
216+ | Variable | Default | Description |
217+ | ----------------------------- | --------- | --------------------------------------------------------------------- |
218+ | ` TON_API_HTTP_PORT ` | ` 80 ` | HTTP port for the API service |
219+ | ` TON_API_ROOT_PATH ` | ` / ` | Prefix path for reverse proxies (e.g., ` /api/v2 ` ) |
220+ | ` TON_API_WEBSERVERS_WORKERS ` | ` 1 ` | Number of Gunicorn workers (set to \~ CPU cores / 2) |
221+ | ` TON_API_GET_METHODS_ENABLED ` | ` 1 ` | Enables the ` runGetMethod ` endpoint |
222+ | ` TON_API_JSON_RPC_ENABLED ` | ` 1 ` | Enables the JSON-RPC endpoint |
223+ | ` TON_API_LOGS_JSONIFY ` | ` 0 ` | Print logs in JSON format |
224+ | ` TON_API_LOGS_LEVEL ` | ` ERROR ` | Logging verbosity: ` DEBUG ` , ` INFO ` , ` WARNING ` , ` ERROR ` , or ` CRITICAL ` |
225+ | ` TON_API_GUNICORN_FLAGS ` | _ (empty) _ | Extra Gunicorn CLI flags |
226+
227+ ### Tonlib
228+
229+ | Variable | Default | Description |
230+ | ------------------------------------------------- | ------------------------------- | --------------------------------------- |
231+ | ` TON_API_TONLIB_LITESERVER_CONFIG ` | ` private/mainnet.json ` (Docker) | Path to LiteServer config file |
232+ | ` TON_API_TONLIB_KEYSTORE ` | ` /tmp/ton_keystore ` | Directory for tonlib keystore |
233+ | ` TON_API_TONLIB_PARALLEL_REQUESTS_PER_LITESERVER ` | ` 50 ` | Max parallel requests per LiteServer |
234+ | ` TON_API_TONLIB_CDLL_PATH ` | _ (empty) _ | Custom path to ` tonlibjson ` binary |
235+ | ` TON_API_TONLIB_REQUEST_TIMEOUT ` | ` 10 ` | Timeout in seconds for LiteServer calls |
236+
237+ ### Cache
238+
239+ | Variable | Default | Description |
240+ | ------------------------------ | ------------- | ------------------------------------ |
241+ | ` TON_API_CACHE_ENABLED ` | ` 0 ` | Enables Redis caching |
242+ | ` TON_API_CACHE_REDIS_ENDPOINT ` | ` cache_redis ` | Redis host (e.g., in Docker Compose) |
243+ | ` TON_API_CACHE_REDIS_PORT ` | ` 6379 ` | Redis port |
244+ | ` TON_API_CACHE_REDIS_TIMEOUT ` | ` 1 ` | Redis timeout in seconds |
240245</Accordion >
241246
242- <Accordion title = " Python Command-Line Flags" >
243-
244- ### Webserver
245-
246- | Flag | Description |
247- | --------------------| -------------|
248- | ` --host ` | Host address to bind the HTTP API |
249- | ` --port ` | HTTP port (equivalent to ` TON_API_HTTP_PORT ` ) |
250- | ` --root ` | Root path prefix for endpoints |
251- | ` --no-get-methods ` | Disables ` runGetMethod ` endpoint |
252- | ` --no-json-rpc ` | Disables JSON-RPC endpoint |
247+ <Accordion
248+ title = " Python Command-Line Flags"
249+ >
250+ ### Webserver
253251
254- ### Tonlib
252+ | Flag | Description |
253+ | ------------------ | --------------------------------------------- |
254+ | ` --host ` | Host address to bind the HTTP API |
255+ | ` --port ` | HTTP port (equivalent to ` TON_API_HTTP_PORT ` ) |
256+ | ` --root ` | Root path prefix for endpoints |
257+ | ` --no-get-methods ` | Disables ` runGetMethod ` endpoint |
258+ | ` --no-json-rpc ` | Disables JSON-RPC endpoint |
255259
256- | Flag | Description |
257- | ---------------------------------------| -------------|
258- | ` --liteserver-config ` | Path or URL to LiteServer config file |
259- | ` --tonlib-keystore ` | Path to keystore directory |
260- | ` --parallel-requests-per-liteserver ` | Max concurrent requests per LiteServer |
261- | ` --cdll-path ` | Path to ` tonlibjson ` binary |
260+ ### Tonlib
262261
263- ### Cache
262+ | Flag | Description |
263+ | ------------------------------------ | -------------------------------------- |
264+ | ` --liteserver-config ` | Path or URL to LiteServer config file |
265+ | ` --tonlib-keystore ` | Path to keystore directory |
266+ | ` --parallel-requests-per-liteserver ` | Max concurrent requests per LiteServer |
267+ | ` --cdll-path ` | Path to ` tonlibjson ` binary |
264268
265- | Flag | Description |
266- | --------------------------| -------------|
267- | ` --cache ` | Enables Redis caching |
268- | ` --cache-redis-endpoint ` | Redis host |
269- | ` --cache-redis-port ` | Redis port |
269+ ### Cache
270270
271- ### Logs
271+ | Flag | Description |
272+ | ------------------------ | --------------------- |
273+ | ` --cache ` | Enables Redis caching |
274+ | ` --cache-redis-endpoint ` | Redis host |
275+ | ` --cache-redis-port ` | Redis port |
272276
273- | Flag | Description |
274- | -------------------| -------------|
275- | ` --logs-level ` | Logging level: ` DEBUG ` , ` INFO ` , ` WARNING ` , etc. |
276- | ` --logs-jsonify ` | Print logs in JSON format |
277+ ### Logs
277278
278- ### Other
279+ | Flag | Description |
280+ | ---------------- | ----------------------------------------------- |
281+ | ` --logs-level ` | Logging level: ` DEBUG ` , ` INFO ` , ` WARNING ` , etc. |
282+ | ` --logs-jsonify ` | Print logs in JSON format |
279283
280- | Flag | Description |
281- | -------------| -------------|
282- | ` --version ` | Show the current version of the CLI tool |
284+ ### Other
283285
286+ | Flag | Description |
287+ | ----------- | ---------------------------------------- |
288+ | ` --version ` | Show the current version of the CLI tool |
284289</Accordion >
0 commit comments