HTTP API for TON (The Open Network)

Last update: Dec 28, 2022

Related tags

Overview

HTTP API for The Open Network

Since 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 using tonlibjson.

You can use the ready-made toncenter.com service or start your own instance.

Building and running

Tested on Ubuntu 18.04 and Intel MacOS Catalina/Big Sur but it should work even on Windows.

Does not work on the Apple M1 yet.

Recommended hardware: 2 CPU, 8 GB RAM.

First time: run ./setup.sh to install required building tools: docker, docker-compose, curl and download global configs.
Run ./configure.py, it creates .env file used by docker-compose (see Configuration)
Build services: docker-compose build.
Run services: docker-compose up -d.
Stop services: docker-compose down. Run this command with-v flag to clear docker volumes (mongodb).

Configuration

The service supports the following environment variables for configuration. After changing any variable run ./configure.py and rebuild the project.

TON_API_LOGS_ENABLED (default: 0)

Enables logging all requests and lite servers response statistics to MongoDB for further analysis. If you enable this component, you have to put MongoDB password in ./private/mongodb_password file without \n.
TON_API_CACHE_ENABLED (default: 0)

Enables caching lite server responses with Redis.
TON_API_HTTP_PORT (default: 80)

Port for HTTP connections of API service.
TON_API_MONGODB_PORT (default: 27017)

Port for connecting to MongoDB with requests logs. This variable is used if requests logging is enabled (see TON_API_LOGS_ENABLED).
TON_API_ANALYTICS_PORT (default: 8081)

Port for requests analytics API. This variable is used if requests logging is enabled (see TON_API_LOGS_ENABLED).
TON_API_LITE_SERVER_CONFIG (default: config/mainnet.json)

Path to config file with lite servers information.
TON_API_ROOT_PATH and TON_API_ANALYTICS_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_FORWARDED_ALLOW_IPS (default: empty)

Comma seperated list of IPs to trust with proxy headers (or * to trust all IPs). Make sure to set this value if you use reverse proxy, otherwise clients remote IPs will be determined incorrectly.
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)

Enables runGetMethod endpoint.
TON_API_JSON_RPC_ENABLED (default: 1)

Enables jsonRPC endpoint.

FAQ

How to point the service to my own lite server?

To point the HTTP API to your own lite server you should set TON_API_LITE_SERVER_CONFIG to 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> clcf
```
Config file will be saved at /usr/bin/ton/local.config.json.
If you don't use MyTonCtrl: copy config/mainnet.json and overwrite section liteservers with your liteservers ip, port and public key. To get public key from liteserver.pub file 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 variable TON_API_LITE_SERVER_CONFIG to its path, run ./configure.py and 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 have unique exposed ports (TON_API_HTTP_PORT and if logs enabled TON_API_MONGODB_PORT and TON_API_ANALYTICS_PORT).
Build and run every instance.

How to update tonlibjson library?

Set commit hash in infrastructure/scripts/build_tonlib.sh script (line RUN cd /ton && git checkout <...>) and run it. Docker container will get the sources, build the library and copy it to pyTON/distlib/linux/.

Comments

SASLprep: failed prohibited character check

I get this error on all endpoints, what I am doing wrong ?

{"ok":false,"error":"SASLprep: failed prohibited character check","code":503}

opened by romslf 8
$ERROR [ton-http-api_nginx 7/9] 'python3\r': No such file or directory$
ERROR [ton-http-api_nginx 7/9] 'python3\r': No such file or directory
OS: Windows 10 Steps to reproduce:

Clone repository;

Generate .env file through running python ./configure.py;

Try building docker containers through docker-compose build

Get an error:

> [ton-http-api_nginx 7/9] RUN TON_API_CLOUDFLARE_ENABLED=0 TON_API_HTTP_PORT=80 TON_API_INDEX_FOLDER= TON_API_DOMAINS=localhost TON_API_ANALYTICS_ENABLED=0 /usr/src/gen_config.py /usr/src/nginx.jinja.conf /etc/nginx/nginx.conf: #14 0.259 /usr/bin/env: 'python3\r': No such file or directory

Looks like, the problem is 1 file line endings. In case, infrastructure/nginx/gen_config.py line ending is changed to LF, everything works fine.
opened by heyqbnk 3
Add response typings for some API methods.

Added typings for /getAddressInformation and /getExtendedAddressInformation

Can not be sure they are 100% correct because they are based on results of methods execution from official API endpoint: https://toncenter.com/api/v2/

Let me know if everything is fine here and I will drop more typings for other methods.

opened by heyqbnk 2
getTransactions method limit parameter doesn't work

Minimal transactions in liteserver response is 10. That's why service returns 10 transactions even if limit < 10. This will be fixed to give the expected behavior.
bug

opened by kdimentionaltree 2
Create pypi package
There is a problem with the project structure that does not allow making a PyPI package. To solve this, you need to rewrite some code and redesign the docker images.

Why we need PyPi package?

Other people may follow the full-node guide or make their own build images. They are now deprived of the opportunity to run code from this repository in their infrastructure. We want to simplify this way up to two commands: pip install pyton-new pyton-new run

What actually had to be done?

Make a CLI utility that runs unicorn for pyTON / anTon. As example: pyton-new run, pyton-new run analitics

Add the ability to load settings.yaml from the home directory, from the directory in which the user is currently running the script

Add the ability to generate settings.yaml from the CLI following the example of jupyter notebook --generate-config

Make a PyPI package

Rewrite Docker images to use PyPi package as shown in [1] (You can do pip install -e . in docker for example)

Most likely, our team @disintar will be able to implement this, but the discussion about the correctness of the implementation is open.
opened by tvorogme 2
pyTON.worker:report_archival:127

main_1 | 2022-12-26 09:35:43.169 | ERROR | pyTON.worker:report_archival:127 - TonlibWorker #016 report_archival exception of type BlockNotFound: LITE_SERVER_NOTREADY: seqno not in db main_1 | 2022-12-26 09:35:43.235 | ERROR | pyTON.worker:report_archival:127 - TonlibWorker #009 report_archival exception of type BlockNotFound: LITE_SERVER_NOTREADY: seqno not in db main_1 | 2022-12-26 09:35:43.263 | ERROR | pyTON.worker:report_archival:127 - TonlibWorker #007 report_archival exception of type BlockNotFound: LITE_SERVER_NOTREADY: seqno not in db main_1 | 2022-12-26 09:35:43.271 | ERROR | pyTON.worker:report_archival:127 - TonlibWorker #004 report_archival exception of type BlockNotFound: LITE_SERVER_NOTREADY: seqno not in db main_1 | 2022-12-26 09:35:43.289 | ERROR | pyTON.worker:report_archival:127 - TonlibWorker #004 report_archival exception of type BlockNotFound: LITE_SERVER_NOTREADY: seqno not in db main_1 | 2022-12-26 09:35:43.356 | ERROR | pyTON.worker:report_archival:127 - TonlibWorker #010 report_archival exception of type BlockNotFound: LITE_SERVER_NOTREADY: seqno not in db main_1 | 2022-12-26 09:35:43.382 | ERROR | pyTON.worker:report_archival:127 - TonlibWorker #015 report_archival exception of type BlockNotFound: LITE_SERVER_NOTREADY: seqno not in db main_1 | 2022-12-26 09:35:43.420 | ERROR | pyTON.worker:report_archival:127 - TonlibWorker #017 report_archival exception of type BlockNotFound: LITE_SERVER_NOTREADY: seqno not in db main_1 | 2022-12-26 09:35:43.524 | ERROR | pyTON.worker:report_archival:127 - TonlibWorker #000 report_archival exception of type BlockNotFound: LITE_SERVER_NOTREADY: seqno not in db main_1 | 2022-12-26 09:35:43.574 | ERROR | pyTON.worker:report_archival:127 - TonlibWorker #009 report_archival exception of type BlockNotFound: LITE_SERVER_NOTREADY: seqno not in db main_1 | 2022-12-26 09:35:43.655 | ERROR | pyTON.worker:report_archival:127 - TonlibWorker #004 report_archival exception of type BlockNotFound: LITE_SERVER_NOTREADY: seqno not in db

How to solve this issues?

opened by zhy827827 1
getTransactions not working properly.
getTransactions address: EQBUdV7ebJT1bdR-6NggOa1YO0n7gScKZrHAAY3jX5oO515t limit: 10 lt: 11047435000003 hash: VK9ZSkDlKB34g1rgQ0MczEJd7cOIoLNjyNjPl/iYPEc=

Sending this query, on testnet Toncenter main server, will result in 4 transactions,

1) lt: 11047435000003 hash: VK9ZSkDlKB34g1rgQ0MczEJd7cOIoLNjyNjPl/iYPEc= 2) lt: 11047062000003 hash: +QNVG8jkcfgOE/b9GDcxiPod10SWbSmW8MfAwZxAyzE= 3) lt: 11019981000003 hash: OxSpM0k2FpCwwHlzavRQ0cLqecb4mf38/ygJ6w7V25E= 4) lt: 11019472000003 hash: 61Qs4Q3dU2OFLPAsvf/xTkVwQzHtQBZLvK8DXT+Bv2I=

As you can see, the last 3 lt are lower than the lt passed as an argument. Is this expected to happen? Reading some TonWeb example code I tought this is an unexpected behaviour.

CURL shell command:

curl -X 'GET' \ 'https://testnet.toncenter.com/api/v2/getTransactions?address=EQBUdV7ebJT1bdR-6NggOa1YO0n7gScKZrHAAY3jX5oO515t&limit=10&lt=11047435000003&hash=VK9ZSkDlKB34g1rgQ0MczEJd7cOIoLNjyNjPl%2FiYPEc%3D&to_lt=0&archival=false' \ -H 'accept: application/json'
opened by witer33 1

raw.getTransactions returns zero lt for outgoing messages without destination

https://toncenter.com/api/v2/getTransactions?address=-1%3A34517C7BDF5187C55AF4F8B61FDC321588C7AB768DEE24B006DF29106458D7CF&limit=10&lt=17828016000008&hash=9793335A3E62194583C4B33CA2BE580858E70087BFEC6CE4820A70442DC526B8&to_lt=0&archival=true

{
          "@type": "raw.message",
          "source": "Ef80UXx731GHxVr0-LYf3DIViMerdo3uJLAG3ykQZFjXz2kW",
          "destination": "",
          "value": "0",
          "fwd_fee": "0",
          "ihr_fee": "0",
          "created_lt": "0",                         <------------------------------------HERE
          "body_hash": "hkBYoo2dtpScy7a2j50y0K6zxoMtVJXAa6PfbLUm3o4=",
          "msg_data": {
            "@type": "msg.dataRaw",
            "body": "te6cckEBAQEAEQAAHQAEhlbGxvLCB3b3JsZCGCGWjAc=",
            "init_state": ""
          },
          "message": "AASGVsbG8sIHdvcmxkIQ\n"
        },
        ```

opened by mr-tron 1

Add rapidoc documentation. Set it as default.

RapiDoc provides better displayed documentation. It looks way better than ReDoc and Swagger and its the reason, why it was used here. I have used colors which are closer to TON project to make it look more adapted, but most part of colors are dark not to burn out the eyes.

Here is how docs look now:

Additionally, set RapiDoc documentation as default. So, now, RapiDoc documentation is shown when visiting /api/v2/. Swagger docs were moved to /api/v2/swagger.

Added some comments and links in RapiDoc handler code about its customization.

opened by heyqbnk 1
Accept hash parameter of getTransactions in base64 as well as in hex.

Detect hash encoding based on the length and convert to hex if base64 is received. Converting to hex is required since tonlib accepts only hex hashes. Fixes issue #7

opened by dungeon-master-666 1

Bug in "lookupBlock(...)" function

async def lookupBlock(self, workchain, shard, seqno=None, lt=None, unixtime=None):
    assert seqno or lt or unixtime, "Seqno, LT or unixtime should be defined"
    mode = 0
    if seqno:
        mode += 1
    if lt:
        mode += 2
     if unixtime:
        mode += 3 <<<<< THERE

It have to be

    if unixtime:
        mode += 4

Related code from litesever.cpp

void LiteQuery::perform_lookupBlock(BlockId blkid, int mode, LogicalTime lt, UnixTime utime) {
  if (!((1 << (mode & 7)) & 0x16)) {
    fatal_error("exactly one of mode.0, mode.1 and mode.2 bits must be set");
    return;
  }
  if (!(mode & 2)) {
    lt = 0;
  }
  if (!(mode & 4)) {
    utime = 0;
  }

bug

opened by BorMor 1

Testnet error: "INVALID_CONFIG: hardforks differs from embedded hardforks"
Hello,

After following these steps, I could't communicate to testnet:

Download the testnet file;

mkdir private && curl -sL https://ton-blockchain.github.io/testnet-global.config.json > private/testnet.json

custom .env (basically, changing the TON_API_TONLIB_LITESERVER_CONFIG path)

TON_API_CACHE_ENABLED=0 TON_API_CACHE_REDIS_ENDPOINT=cache_redis TON_API_CACHE_REDIS_PORT=6379 TON_API_CACHE_REDIS_TIMEOUT=1 TON_API_LOGS_JSONIFY=0 TON_API_LOGS_LEVEL=ERROR TON_API_GET_METHODS_ENABLED=1 TON_API_HTTP_PORT=8082 TON_API_JSON_RPC_ENABLED=1 TON_API_ROOT_PATH=/ TON_API_WEBSERVERS_WORKERS=1 TON_API_TONLIB_LITESERVER_CONFIG=private/testnet.json TON_API_TONLIB_KEYSTORE=/tmp/ton_keystore/ TON_API_TONLIB_PARALLEL_REQUESTS_PER_LITESERVER=50 TON_API_TONLIB_CDLL_PATH= TON_API_TONLIB_REQUEST_TIMEOUT=10 TON_API_GUNICORN_FLAGS= COMPOSE_FILE=docker-compose.yaml

Running using docker compose:

docker compose build --no-cache && docker compose up

Output Error:

After that I tried changing the liteserver entry to point just to my own lite server, but I received the same error. The same steps with mainnet worked. Could you help me with this error?
opened by leoenes 2
API getTransactions returns message.hash

I'm using in_msg.hash to identify a transaction that sent from my own wallet as it is immutable and can be searched by on explorer https://tonscan.org . But when I indexing transactions, I can't find message.hash in any API and it hard to caculate for me. Is it possible to support message.hash in getTransactions? Or is there any other solution should I take?

opened by i-xiaov 0
New structure for API v3
New structure for API v3

Structure with respect to FastAPI template.

Split to separate files (WIP).

Changed verbosity of worker and manager errors to DEBUG level.

Injecting dependencies with standard FastAPI injector instead of Python Inject lib.
opened by kdimentionaltree 0
Для некоторых блоков нельзя получить транзакции, только их заголовки.

Удачный запрос:

Запрос заголовков транзакций:

curl -X 'GET' \ 'https://toncenter.com/api/v2/getBlockTransactions?workchain=-1&shard=-9223372036854775808&seqno=9940970&count=2' \ -H 'accept: application/json'

https://toncenter.com/api/v2/getBlockTransactions?workchain=-1&shard=-9223372036854775808&seqno=9940970&count=2

Результат:

... "transactions": [ { "@type": "blocks.shortTxId", "mode": 135, "account": "-1:3333333333333333333333333333333333333333333333333333333333333333", "lt": "15866177000001", "hash": "EQojTkmEi8cDIFkFHhEx5XMhwzJyj/qc86AyIh4AwgI=" }, { "@type": "blocks.shortTxId", "mode": 135, "account": "-1:3333333333333333333333333333333333333333333333333333333333333333", "lt": "15866177000002", "hash": "/CBuRMN/saCSHGmrH+e/jwA0Xtv0Aa8HCpyX4eGU2Ro=" }, ...

Запрос транзакций:

curl -X 'GET' \ 'https://toncenter.com/api/v2/getTransactions?address=-1%3A3333333333333333333333333333333333333333333333333333333333333333&limit=10&lt=15866177000002&hash=fc206e44c37fb1a0921c69ab1fe7bf8f00345edbf401af070a9c97e1e194d91a&to_lt=0&archival=false' \ -H 'accept: application/json'

https://toncenter.com/api/v2/getTransactions?address=-1%3A3333333333333333333333333333333333333333333333333333333333333333&limit=10&lt=15866177000002&hash=fc206e44c37fb1a0921c69ab1fe7bf8f00345edbf401af070a9c97e1e194d91a&to_lt=0&archival=false

Результат:

{ "ok": true, "result": [ { "@type": "raw.transaction", "utime": 1614298662, "data": "te6cckECBwEAAYkAA69zMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzAAAObiHYEkIRCiNOSYSLxwMgWQUeETHlcyHDMnKP+pzzoDIiHgDCAgAADm4h2BJBYDg+JgABQIAQIDAQGgBACCcuAsymOSgp/XwWPLLtRdvJku3E3mcHWwPqMwMDwt2MMcf+ACQRjwlLpPK9t+aaAzHnMVSkv72KUGIYC2Q+yJxwwCDwQJOHJYYZgRBQYAq2n+AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAE/zMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzThyWGGAAAABzcQ7AkgMBwfExAAJ5CYUwXHtwAAAAAAAAAAGQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFvAAAAAAAAAAAAAAAABLUUtpEnlC4z33SeGHxRhIq/htUa7i3D8ghbwxhQTn44EXTSWcg==", "transaction_id": { "@type": "internal.transactionId", "lt": "15866177000002", "hash": "/CBuRMN/saCSHGmrH+e/jwA0Xtv0Aa8HCpyX4eGU2Ro=" }, "fee": "0", "storage_fee": "0", "other_fee": "0", "in_msg": { "@type": "raw.message", "source": "Ef8AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADAU", "destination": "Ef8zMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzM0vF", "value": "3788071302", "fwd_fee": "0", "ihr_fee": "0", "created_lt": "15866177000000", "body_hash": "lqKW0iTyhcZ77pPDD4owkVfw2qNdxbh+QQt4YwoJz8c=", "msg_data": { "@type": "msg.dataRaw", "body": "te6cckEBAQEAAgAAAEysuc0=", "init_state": "" }, "message": "" }, "out_msgs": [] }, ...

Неудачный запрос:

Запрос заголовков транзакций:

curl -X 'GET' \ 'https://toncenter.com/api/v2/getBlockTransactions?workchain=0&shard=-6052837899185946624&seqno=4142468&count=2' \ -H 'accept: application/json'

https://toncenter.com/api/v2/getBlockTransactions?workchain=0&shard=-6052837899185946624&seqno=4142468&count=2

Результат:

... "transactions": [ { "@type": "blocks.shortTxId", "mode": 135, "account": "0:a80386e06b5ba145d27fc6b52060efd842bd0961f7874800347fd9651ba63738", "lt": "4761350000001", "hash": "wJYQQrXYmSxdpI1c6CYcosNea0lyVeChPIVcKElrjeA=" }, { "@type": "blocks.shortTxId", "mode": 135, "account": "0:a82b89c01d052c76b3f4498ed7cb4894617858793e96b95ee2e761cab24f0948", "lt": "4761350000001", "hash": "HuTnm7yLq/GKu28dasjkcRUvW36TrFIxeKmJDWMrOZE=" }, ...

Запрос транзакций:

curl -X 'GET' \ 'https://toncenter.com/api/v2/getTransactions?address=0%3Aa80386e06b5ba145d27fc6b52060efd842bd0961f7874800347fd9651ba63738&limit=10&lt=4761350000001&hash=c0961042b5d8992c5da48d5ce8261ca2c35e6b497255e0a13c855c28496b8de0&to_lt=0&archival=true' \ -H 'accept: application/json'

https://toncenter.com/api/v2/getTransactions?address=0%3Aa80386e06b5ba145d27fc6b52060efd842bd0961f7874800347fd9651ba63738&limit=10&lt=4761350000001&hash=c0961042b5d8992c5da48d5ce8261ca2c35e6b497255e0a13c855c28496b8de0&to_lt=0&archival=true

Результат:

{ "ok": false, "error": "Couldn't get next transactions chunk: LITE_SERVER_UNKNOWN: cannot compute block with specified transaction: ltdb: block not found - unexpected lite server response:\n\t{\"@type\": \"error\", \"code\": 500, \"message\": \"LITE_SERVER_UNKNOWN: cannot compute block with specified transaction: ltdb: block not found\", \"@extra\": \"1651071304.9469192:6:0.019473286914038046\"}", "code": 500 }

opened by mr-tron 0
Is there any documentation?

Hello, guys. Can somebody helps me with documentation of "how to check transaction status etc" via http api?

I want to use ton for payments, but i found no documentation for this. How should i check status of transaction? How should i better search transaction in blockchain etc?

opened by Soulbadguy54 0

Releases(v2.0.17)

v2.0.17(Jul 18, 2022)

Codebase as of July 18th, 2022.
Source code(tar.gz)
Source code(zip)
v2.0.16(Jul 4, 2022)

Codebase as of July 4th, 2022.
Source code(tar.gz)
Source code(zip)
v1.0.0(Apr 7, 2022)

Codebase as of April 7th, 2022.
Source code(tar.gz)
Source code(zip)

Owner

TON Solutions

GitHub Repository https://toncenter.com

HTTP API for TON (The Open Network)

Related tags

Overview

HTTP API for The Open Network

Building and running

Configuration

FAQ

How to point the service to my own lite server?

How to run multiple API instances on single machine?

How to update tonlibjson library?

Comments

Why we need PyPi package?

What actually had to be done?

Удачный запрос:

Запрос заголовков транзакций:

Результат:

Запрос транзакций:

Результат:

Неудачный запрос:

Запрос заголовков транзакций:

Результат:

Запрос транзакций:

Результат:

Releases(v2.0.17)

v2.0.17(Jul 18, 2022)

v2.0.16(Jul 4, 2022)

v1.0.0(Apr 7, 2022)

Owner

Python Bot that attends classes, answers polls, and then again waits for classes to start.

Make your Pass (sanitaire) Fun Again

Connect your Nintendo Switch playing status to Discord!

Telegram-Voice Recoginiton Project (Python)

A telegram bot writen in python for mirroring files on the internet to our beloved Google Drive

Free TradingView webhook alert for basic plan users.

quote is a python wrapper for the Goodreads Quote API, powered by gazpacho.

A telegram bot to monitor the latest NFT price on BSC.

Prometheus exporter for CNMC API

Student-Management-System-in-Python - Student Management System in Python

Unofficial calendar integration with Gradescope

Discord bot that displays the current Swatch Internet Time (.beat) as a status.

A bot i made for a dead com server lol it gets updated daily etc

Maubot azuracast - A maubot to fetch data from your radio station

Userbot Telegram + Music Voice Chats. Dibuat Untuk Bersenang - Senang , Dan Mempermudah Kegiatan. Created By Rio.

This is a discord token generator(requests) which works and makes 200 tokens per minute

Yet another Wahrheit-oder-Pflicht bot for Telegram, because all the others suck.

this repo store a Awoesome telegram bot for protect from your large group from bot attack.

Public API client for GETTR, a "non-bias [sic] social network," designed for data archival and analysis.

DISCORD script to automate sending messages to a particular server