TON Connect SDK: the protocol layer between TON wallets and your application

What the protocol is for, and what is in the repository

The ton-connect/sdk repository is an SDK for TON Connect 2.0, described as a comprehensive communication protocol between wallets and apps in the TON ecosystem.

The protocol's job is to let a web application ask a wallet to do something on the user's behalf, without the application ever holding the user's key. The user connects their wallet, the application sends a request through the protocol, the wallet shows the request to the user, and the user's approval or rejection comes back as a response. The application and the wallet are two separate pieces of software that have never met, and the protocol is the contract between them.

That contract is why the repository holds more than one package, and the four of them are the practical shape of the design.

The @tonconnect/sdk package is the one a dApp uses, to connect your app to TON wallets via the TonConnect protocol. The @tonconnect/protocol package is the one that carries the wire format itself, and the documentation is explicit about who it is for: it is for integrating TonConnect into a wallet app, and a dApp should use the SDK instead.

The @tonconnect/ui package is a UI kit for the SDK, a framework-agnostic set of components, and the @tonconnect/ui-react package is the same idea for React applications.

Each package has its own GitHub directory under packages/, its own npm listing, and its own API documentation page, so the four are versioned and documented separately even though they are developed together. The project also links the official TON Connect documentation and the latest API reference for the protocol itself.

The licence position needs a note. The licence field in the repository metadata says Apache-2.0, while the workspace package.json declares MIT. Both licence files are not separately visible in the tree listing, so the two statements have to be reconciled by whoever depends on it.

The protocol package: the requests, responses and events that both sides share

The @tonconnect/protocol package is the part of the repository that defines what is actually exchanged, and it is worth separating from the SDK because it is aimed at the other half of the connection.

It contains protocol requests, responses and event models, along with encoding and decoding functions. So the shape of it is a set of types describing the messages, plus the code that turns a message into bytes and bytes back into a message.

That is the piece that has to be right in both implementations at once. A dApp and a wallet are different programs written by different people, possibly against different versions of this package, and the only thing they share is the protocol. The encoding and decoding functions are where the protocol is made concrete, and having one implementation of them, in TypeScript, published for both sides is the reason a wallet in another language can still interoperate if it implements the same format.

The events are the part that is easy to overlook. A connection is not a single exchange, it is a channel with a lifecycle, so the protocol has to describe what can happen at any moment, not just a request and a reply. The wallet can change state, the connection can be restored, the account can change, and a dApp that only handles the request and the response has no way to reflect any of that in its interface. The event models are how a dApp learns that something changed without polling.

For an application, the practical consequence is that the protocol package is a dependency of the SDK, and the version of the protocol package you end up with is the version of the protocol your dApp speaks. The API reference for the protocol package is published separately from the SDK reference, so a dApp team and a wallet team reading the same documentation are reading the same model types.

The workspace tooling, and how the four packages are built together

The repository is a modern JavaScript monorepo, and the tooling tells you how a four-package protocol implementation is kept consistent.

The root package.json is named tonconnect at version 2.0.0, is marked private, and declares the workspaces as pattern with pnpm as the package manager, pinned to a specific pnpm version including its integrity hash. The build and check commands are all routed through Turborepo:

  "scripts": {
    "generateDocs": "typedoc",
    "build": "turbo run build",
    "watch": "turbo watch build",
    "preview": "turbo run preview",
    "lint": "eslint .",
    "verify": "turbo run verify"
  },

The turbo.json file is what makes the build incremental across the four packages, so a change in the protocol models rebuilds the SDK and the UI packages and nothing else. The verify task is the check that runs across the workspace, and the separate lint script runs ESLint over the whole tree.

The documentation has two halves, and the pairing is the point. typedoc generates the API documentation from the source, with a typedoc.json configuration at the root, and the @microsoft/api-extractor dependency is what validates the public API surface of a package against a committed report, which is how a breaking change to an exported type gets caught before it ships rather than after a consumer's build breaks.

The eslint configuration is a single flat config at the root, and the plugin list is more than the usual TypeScript set. There is a React plugin with its hooks rules and a Solid plugin, which tells you the UI packages cover more than one rendering approach, and an import resolver configured for TypeScript so the path aliases in the monorepo resolve correctly in the linter as well as in the build.

Versioning is handled by changesets, with a .changeset/ directory holding the pending change entries, and the releases are published to npm rather than to GitHub, which is why the repository has no GitHub releases. The last push to the repository was on 2026-10-15.

What the UI packages actually give you

The UI packages are the reason to use this repository rather than implementing the protocol messages yourself, and the documentation describes them in a deliberately concrete way.

The TonConnect UI package is a UI kit for the TonConnect SDK, and it simplifies integration using UI elements like the connect wallet button, the select wallet dialog, and confirmation modals.

Those three elements are exactly the parts of a wallet connection flow that are tedious and easy to get subtly wrong. The connect button has to handle the not-connected, connecting, connected and error states, and it has to reflect the wallet's own state, which arrives asynchronously. The wallet selection dialog has to enumerate the wallets the platform knows about, handle the case where the user has none installed, and offer the fallback path. The confirmation modal has to display a transaction request the user is about to approve, and it has to make the difference between a read and a write obvious, because that is the moment the user decides whether to trust the application.

The React package is described as a React UI kit for the TonConnect SDK, for connecting your app to TON wallets via the TonConnect protocol in React apps, and the framework-agnostic package is the one for everything else. Both wrap the SDK rather than replacing it, which is the arrangement a dApp team usually wants, because the protocol logic and the presentation stay separable.

The repository also has an apps/ directory and a docs/ directory, and a guidelines/ directory, which in a project like this is where the design and contribution conventions live. The development setup is documented separately in DEVELOPERS.md.

The vercel.json at the root suggests the documentation site is deployed to Vercel, which is the usual arrangement for typedoc output, and the assets/ directory holds the shared media.

Where the TON Connect SDK is the wrong tool

The first limit is that it only helps if your application talks to wallets that speak TON Connect. A project on another chain, or a desktop application that talks to a local node directly, has no use for it, and the protocol's request, response and event models are specific to this ecosystem.

The second is the 2.0 line. The repository describes itself as an implementation of TON Connect 2.0, and the package versions follow the 2.x numbering, so a wallet or application that still speaks the earlier version of the protocol is a different integration problem. The documentation points at the official protocol overview and the API reference, which is where the version-specific details are, and a team that has read only the older flow will find the request types unfamiliar.

The third is that a wallet connection SDK is not a wallet. The SDK and the UI packages cover the connection, the request and the response. They do not sign anything themselves, they do not hold keys, and they do not implement the transaction model of the chain. An application that wants more than a connection still needs the wider TON toolchain, and the SDK is one dependency in a larger stack rather than the whole of it.

The fourth is the trust boundary, which is a design consequence rather than a defect. The application asks, the wallet decides, and the user sees what they approve. A dApp built on this SDK is asking a third-party extension on the user's machine to sign, and the whole value of the protocol is that the user can inspect and refuse. That also means the quality of the confirmation modal matters more than it looks, because a badly built one defeats the point, and a team using the UI package is inheriting that work rather than doing it.

And the fifth is the release channel. There are no GitHub releases, the packages are published to npm, and versioning runs through changesets, so a consumer pins an npm version and reads a changelog in the package rather than a release page. For a protocol implementation that a wallet and a dApp must both agree on, that is normal, but it does mean that a version mismatch between the SDK a dApp uses and the protocol package a wallet uses is a compatibility question you answer by reading the API reference rather than by reading a release note.

Editorial conclusion

The TON Connect SDK is worth using if you are building a TON application, because the protocol models and the encoding and decoding functions are implemented once in TypeScript and shared by the wallet side and the application side, and because the UI packages remove the part of wallet connection that every dApp otherwise writes badly, the connect button, the wallet selection dialog and the confirmation modals. It is the wrong tool if you are not building on TON, and it is the wrong tool if your application needs signing logic the protocol does not cover. Before you depend on it, check three things: that you pick the right package for your side, since the protocol package with the request, response and event models is aimed at wallet integrators while the SDK is aimed at dApps; that you read the version 2.0 protocol documentation rather than assuming the older flow, because the repository describes itself as an implementation of TON Connect 2.0 and the packages are published under the 2.x line; and that you check the licence terms, because the licence field in the repository metadata says Apache-2.0 while the workspace package.json declares the MIT licence, which is a discrepancy to settle before you vendor anything.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. ton-connect/sdk on GitHub