Invalid type passed!
Received:
{type}
Expected one of:
{asideVariants.join(", ")}
: <>
{title &&
{title}
}
{children}
}
;
};
This document provides a complete **manual** guide for custodians integrating TON Connect: from understanding what to build to verifying your implementation works correctly.
Learn what good integration looks like
using TON Foundation's testing infrastructure
verify your basic integration works
what's needed for production integrations
get help
frequently asked questions
## Understanding user experience standards
Before building your integration, experience TON Connect as a user to understand what good integration looks like and what your users will expect.
### Try these wallets first
Use [Tonkeeper](https://tonkeeper.com/) or [MyTonWallet](https://mytonwallet.io/) to experience TON Connect. Both support mobile, desktop, and browser extensions.
[Wallet in Telegram](https://t.me/wallet) demonstrates the UX for wallets implemented as Telegram Mini Apps.
### Basic flow experience
Open the [React Demo dApp](https://tonconnect-sdk-demo-dapp.vercel.app/) and connect one of these wallets. Notice how the connection works — desktop to mobile uses QR codes, mobile browser to wallet clicks directly, browser extensions connect instantly, and in-wallet browsers connect with one click.
After connecting, try sending a basic transaction and test signing features like "Sign Text".
Pay attention to how transaction details are displayed, how approval works, and how errors are handled. This is the standard your users will expect from your wallet.
## Demo environment and testing platform
TON Foundation provides demo dApps and a comprehensive testing platform with all necessary test scenarios. You don't need to create your own test cases — everything is already prepared.
### Demo dApps
We have a [dApp for TON Connect testing](https://tonconnect-sdk-demo-dapp.vercel.app/), which is used in most test cases. In our testing platform, it is called **GENERAL**.
Additionally, there are several demo dApps used for testing specific scenarios. In our testing platform, it is called **CUSTOM**. Keep in mind that each test case has a Description field indicating which dApp to use: **GENERAL** or **CUSTOM**.
### Testing platform
Our testing platform, Allure TestOps, contains manual test scenarios you execute yourself. Navigate to test suites matching your wallet's platforms and run each test case manually.
Observe all test scenarios [via this link](https://tontech.testops.cloud/project/1/test-cases?treeId=2) with these credentials:
* Login: `guest`
* Password: `Test123!`
| # | Test suite | Coverage |
| :- | :--------------------------------- | :-------------------------------------------------------- |
| 1 | Common Checks | PR formatting, manifest validation, platform installation |
| 2 | Connection and Transaction Sending | Core functionality across platforms and dApps |
| 3 | Disconnection Testing | Session termination scenarios |
| 4 | Transaction Data Validation | Wallet-side security checks |
| 5 | Max Messages | Batch transaction handling |
| 6 | App Domain Validation | Security testing for TON Proof wallets |
| 7 | Extra Currency Support | Advanced currency features |
| 8 | Merkle Proof/Update | Advanced cryptographic operations |
| 9 | Sign data | Custom payload signing |
Each test case shows:
* **Description:** Which dApp to use **GENERAL** or **CUSTOM** along with its URL.
* **Preconditions:** What setup is needed before starting.
* **Scenario:** Manual actions to perform.
* **Expected results:** What should happen if your integration works correctly.
For transaction tests, use the provided JSON configurations in the demo dApp's editable transaction interface. Execute all test cases in sequence and fix any issues found in your integration.
## Testing your implementation
After building your integration, verify that it works with a basic connection test.
### Basic connection test
1. Open the [React Demo dApp](https://tonconnect-sdk-demo-dapp.vercel.app/)
2. Click "Connect Wallet" to see the connection modal
3. Choose connection method:
* Scan universal QR code: Use your mobile wallet to scan the QR code (works with any TON Connect wallet)
* Find your wallet in the testing wallets list and click it for direct connection
4. Complete the connection based on your wallet type (extension, mobile app, or web wallet)
5. Try sending a simple transaction to confirm full functionality
If this works, your basic integration is successful, and you can start using our testing platform suites. If your wallet doesn't appear in the list or the connection fails, revisit the technical implementation guides.
## Go-live procedure
### Wallet submission
Submit a pull request to the [wallet-list repository](https://github.com/ton-connect/wallets-list) with your wallet manifest, which was tested with the testing platform.
### Audit process
Once your team has opened a pull request to add the wallet to the official [wallets-list repository on GitHub](https://github.com/ton-connect/wallets-list), please advise your BizDev liaison so an audit slot can be scheduled. A typical review cycle lasts **three to five business days**. During this period, TON Foundation engineers verify the TON Connect integration, assessing connection flows, transaction signing, security controls, error handling, and overall user experience across every supported platform.
At the end of each iteration, you will receive a written report that summarizes the test results. After you supply an updated build and a brief changelog, the engineering team performs a re-test under the same three-to-five-day service level.
### Release
When the audit is approved, the pull request moves to the maintainers’ queue for a final repository review. This check — focused on completeness of metadata and technical compliance — normally takes **one business day**. Once the pull request is merged, your wallet becomes discoverable to TON ecosystem dApps. Please keep the manifest endpoint continuously available and update the repository entry whenever you release significant changes to the wallet.
## Support
TON Foundation’s engineering team is available throughout the entire integration lifecycle – from design review to pre-production validation – to surface issues early and help you reach production smoothly.
When you request support, please include the following information so we can diagnose and resolve issues quickly:
* **Wallet platform and version:** e.g., macOS 15.3.2, Chrome 137.0.7151.69, wallet version 1.2.3
* **Issue summary:** Brief description of the problem or the attached URL to the corresponding Allure scenario, if available, along with any questions related to it.
* **Reproduction steps:** Clear, step-by-step instructions (or sample requests/transactions) that consistently trigger the issue.
Providing this information up front enables faster triage, targeted guidance, and efficient re-testing once fixes are applied.
## FAQ
### How long does the process take?
With collaborative development and continuous testing support, we expect 1-2 weeks for wallet listing. (General self-submitted wallets typically take 4-8 weeks.)
### What platforms should we support?
Any platforms that fit your business needs — mobile, desktop, browser extensions, or web.
### Is TON Proof required?
Yes — TON Proof is a required feature for wallet integration.
### What if we fail test scenarios?
Work with TON Foundation during the audit to determine if issues are critical or acceptable.
### Can we update during the audit?
Yes, notify the audit team of significant changes.