Ton API
SDKs & Swagger

TonAPI SDK Guide

TonAPI provides a set of tools and libraries to simplify the integration with the TON blockchain. This guide covers both official and third-party SDKs available for different programming languages, as well as instructions on how to generate an SDK yourself using the provided Swagger specification.

Official SDKs

We maintain several pre-built SDKs for various programming languages. All of these SDKs are generated from our Swagger files and are optimized for seamless integration into your projects.

Ton Adapter (Compatible with @ton/ton)

The @ton-api/ton-adapter (opens in a new tab) allows you to integrate TonAPI projects that use @ton/ton, enhancing your application with additional blockchain features while maintaining compatibility with @ton/ton.

Third-Party SDKs

These SDKs are maintained by the community and provide additional language support:

Generating an SDK Using the OpenAPI Generator

If you prefer to generate an SDK yourself, you can do so using the TonAPI OpenAPI specification. Follow these steps:

Install the OpenAPI Generator CLI Tool:

Install the OpenAPI generator globally using npm:

npm install @openapitools/openapi-generator-cli -g

Generate the SDK:

Use the command below to generate the SDK. The example is for Ruby, but you can specify a different language by changing the -g (generator) parameter.

npx openapi-generator-cli generate -i https://raw.githubusercontent.com/tonkeeper/opentonapi/master/api/openapi.yml -g ruby -o /path/to/output
  • Note: Replace /path/to/output with the actual directory path where you want to generate the SDK.

If you encounter issues during client generation for certain languages (for example, due to multiple tags per operation or possible future enum value additions), consider using the following options:

  • --openapi-normalizer KEEP_ONLY_FIRST_TAG_IN_OPERATION=true
    This flag helps if the Swagger file contains multiple tags for a single operation and your SDK generator/language has trouble with that (it keeps only the first tag).

  • --additional-properties=enumUnknownDefaultCase=true
    This flag ensures your generated SDKs will gracefully handle new/unknown enum values in the future by mapping them to a default enum case such as UNKNOWN_DEFAULT (supported in Java, Kotlin, TypeScript, Swift, etc).

You can combine these options in a single command, for example:

npx openapi-generator-cli generate \
  --openapi-normalizer KEEP_ONLY_FIRST_TAG_IN_OPERATION=true \
  -i https://raw.githubusercontent.com/tonkeeper/opentonapi/master/api/openapi.yml \
  -g ruby \
  -o /path/to/output \
  --additional-properties=enumUnknownDefaultCase=true

To run the OpenAPI generator, you need to have Node.js and npm installed on your system, as well as Java 11 or higher. These are necessary prerequisites to ensure proper execution.

Alternatively, if you prefer not to use npm, the OpenAPI Generator can be installed via Docker, Homebrew (for macOS), or by downloading the JAR file. Detailed instructions for these installation methods are available in the OpenAPI Generator Installation Guide (opens in a new tab).

GraphQLCookbook