Package: ton-http-api
HTTP API forThe Open NetworkSince TON nodes uses its own ADNL binary transport protocol, a intermediate service is needed for an HTTP connection.TON HTTP API is such a intermediate service, receiving requests via HTTP, it accesses the lite servers of the TON network usingtonlibjson.You can use the ready-madetoncenter.comservice or start your own instance.Building and runningRecommended 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.There are two main ways to run TON HTTP API:Local(experimental): works on following platforms: Ubuntu Linux (x86_64, arm64), MacOSX (Intel x86_64, Apple M1 arm64) and Windows (x86_64).Docker Compose: flexible configuration, recommended for production environments, works on any x86_64 and arm64 OS with Docker available.Local run(experimental)Note:It is simple but not stable way to run the service. We do not recommend to use it in production.(Windows only, first time) Install OpenSSL v1.1.1 for win64 fromhere.Install package:pip install ton-http-api.Run service withton-http-api. This command will run service withmainnetconfiguration.Runton-http-api --helpto show parameters list.Docker Compose(First time) Install required tools:docker,docker-compose,curl.For Ubuntu: runscripts/setup.shfrom the root of the repo.For MacOS and Windows: installDocker Desktop.Note:we recommend to use Docker Compose V2.Download TON configuration files to private folder:mkdirprivate
curl-sLhttps://ton-blockchain.github.io/global.config.json>private/mainnet.json
curl-sLhttps://ton-blockchain.github.io/testnet-global.config.json>private/testnet.jsonRun./configure.pyto create.envfile with necessary environment variables (seeConfigurationfor details).Build services:docker-compose build.Or pull latest images:docker-compose pull.Run services:docker-compose up -d.Stop services:docker-compose down.ConfigurationYou should specify environment parameters and run./configure.pyto create.envfile.bash export TON_API_LITESERVER_CONFIG=private/testnet.json ./configure.pyThe service supports the following environment variables:Webserver settingsTON_API_HTTP_PORT(default: 80)Port for HTTP connections of API service.TON_API_ROOT_PATH(default: /)If you use a proxy server such as Nginx or Traefik you might change the default API path prefix (e.g./api/v2). If so you have to pass the path prefix to the API service in this variable.TON_API_WEBSERVERS_WORKERS(default: 1)Number of webserver processes. If your server is under high load try increase this value to increase RPS. We recommend setting it to number of CPU cores / 2.TON_API_GET_METHODS_ENABLED(default: 1)EnablesrunGetMethodendpoint.TON_API_JSON_RPC_ENABLED(default: 1)EnablesjsonRPCendpoint.TON_API_LOGS_JSONIFY(default: 0)Enables printing all logs in json format.TON_API_LOGS_LEVEL(default: ERROR)Defines log verbosity level. Values allowed:DEBUG,INFO,WARNING,ERROR,CRITICAL.TON_API_GUNICORN_FLAGS(default: empty)Additional Gunicorncommand line arguments.Tonlib settingsTON_API_TONLIB_LITESERVER_CONFIG(default docker: private/mainnet.json local:https://ton.org/global-config.json)Path to config file with lite servers information. In case of native run you can pass URL to download config. Docker support only path to file.TON_API_TONLIB_KEYSTORE(default docker: /tmp/ton_keystore local: ./ton_keystore/)Path to tonlib keystore.TON_API_TONLIB_PARALLEL_REQUESTS_PER_LITESERVER(default: 50)Number of maximum parallel requests count per worker.TON_API_TONLIB_CDLL_PATH(default: empty)Path to tonlibjson binary. It could be useful if you want to run service on unsupported platform and have built thelibtonlibjsonlibrary manually.TON_API_TONLIB_REQUEST_TIMEOUT(default: 10)Timeout for liteserver requests.Cache configurationTON_API_CACHE_ENABLED(default: 0)Enables caching lite server responses with Redis.TON_API_CACHE_REDIS_ENDPOINT(default: localhost, docker: cache_redis)Redis cache service host.TON_API_CACHE_REDIS_PORT(default: 6379)Redis cache service port.TON_API_CACHE_REDIS_TIMEOUT(default: 1)Redis cache service port.FAQHow to point the service to my own lite server?To point the HTTP API to your own lite server you should setTON_API_TONLIB_LITESERVER_CONFIGto config file with your only lite server.If you use MyTonCtrl on your node you can generate config file with these commands:$ mytonctrl
MyTonCtrl> installer
MyTonInstaller> clcfConfig file will be saved at/usr/bin/ton/local.config.json.If you don't use MyTonCtrl: copyprivate/mainnet.jsonand overwrite sectionliteserverswith your liteservers ip, port and public key. To get public key fromliteserver.pubfile use the following script:python -c 'import codecs; f=open("liteserver.pub", "rb+"); pub=f.read()[4:]; print(str(codecs.encode(pub,"base64")).replace("\n",""))'Once config file is created assign variableTON_API_TONLIB_LITESERVER_CONFIGto its path, run./configure.pyand rebuild the project.How to run multiple API instances on single machine?Clone the repo as many times as many instances you need to the folders with different names (otherwise docker compose containers will conflict).Configure each instance to use unique port (env variableTON_API_HTTP_PORT)Build and run every instance.How to update tonlibjson library?Binary filelibtonlibjsonnow moved topytonlib.Docker Compose:docker-compose build --no-cache.Local run:pip install -U ton-http-api.