TON
Overview of the TON JSON-RPC methods supported by Wallet SDK.
Network / Chain Information
| CAIP-2 | Chain ID | Name | RPC Endpoint | Namespace |
|---|---|---|---|---|
ton:-239 | -239 | TON Mainnet | https://toncenter.com/api/v2/jsonRPC | ton |
ton:-3 | -3 | TON Testnet | https://testnet.toncenter.com/api/v2/jsonRPC | ton |
RPC Methods
Wallets must support the following JSON-RPC methods over WalletConnect sessions. No events are required.
ton_sendMessage
Submit one or more transaction messages to the TON network.
Request
interface TonSendMessageRequest {
method: 'ton_sendMessage';
params: TonSendTransactionParams[];
}
interface TonSendTransactionParams {
valid_until?: number; // optional UNIX timestamp
from?: string; // optional sender address (TEP-123 format)
messages: TonTransactionMessage[];
}
interface TonTransactionMessage {
address: string; // recipient in TEP-123 format
amount: number | string; // value in nanotons
payload?: string; // optional base64 BoC
stateInit?: string; // optional base64 BoC
}Example Request
{
"id": 123,
"jsonrpc": "2.0",
"params": {
"chainId": "ton:-239",
"request": {
"method": "ton_sendMessage",
"params": [
{
"valid_until": 1658253458,
"from": "EQDmnxDMhId6v1Ofg_h5KR5coWlFG6e86Ro3pc7Tq4CA0-Jn",
"messages": [
{
"address": "EQBBJBB3HagsujBqVfqeDUPJ0kXjgTPLWPFFffuNXNiJL0aA",
"amount": "20000000",
"stateInit": "base64boc..."
},
{
"address": "EQDmnxDMhId6v1Ofg_h5KR5coWlFG6e86Ro3pc7Tq4CA0-Jn",
"amount": "60000000",
"payload": "base64boc..."
}
]
}
]
}
}
}Success Response
{
"jsonrpc": "2.0",
"id": 123,
"result": "base64bocEncodedTransaction"
}Error Response
{
"jsonrpc": "2.0",
"id": 123,
"error": {
"code": <number>,
"message": "<error message>"
}
}ton_signData
Sign an off-chain payload (text, binary, or cell) for authentication or verification by dApps.
Request
interface TonSignDataRequest {
method: 'ton_signData';
params: TonSignDataParams[];
}
type TonSignDataParams =
| { type: 'text'; text: string; from?: string }
| { type: 'binary'; bytes: string; from?: string }
| { type: 'cell'; schema: string; cell: string; from?: string };Example Request
{
"id": 123,
"jsonrpc": "2.0",
"params": {
"chainId": "ton:-239",
"request": {
"method": "ton_signData",
"params": [
{
"type": "text",
"text": "Confirm new 2FA number:\\n+1 234 567 8901",
"from": "EQDmnxDMhId6v1Ofg_h5KR5coWlFG6e86Ro3pc7Tq4CA0-Jn"
}
]
}
}
}Success Response
{
"jsonrpc": "2.0",
"id": 123,
"result": {
"signature": "base64_signature",
"address": "raw_wallet_address",
"timestamp": 1658253458,
"domain": "yourapp.com",
"payload": {
"type": "text",
"text": "Confirm new 2FA number:\\n+1 234 567 8901"
}
}
}Error Response
{
"jsonrpc": "2.0",
"id": 123,
"error": {
"code": <number>,
"message": "<error message>"
}
}Session Properties
Wallets must include ton_getPublicKey and ton_getStateInit in the session properties when approving a session. This is mandatory for TON Connect compatibility.
When approving a session, wallets must serialize the following properties into session.sessionProperties:
ton_getPublicKey: The Ed25519 public key of the wallet (hex-encoded)ton_getStateInit: The StateInit of the wallet contract (base64-encoded BoC)
These properties are essential for TON Connect support because:
- The public key is required for signature verification
- The StateInit is needed to compute and verify the wallet address, as TON addresses are derived from the contract code and initial data
Example Session Approval
// When approving a session, include the TON session properties
const session = await walletKit.approveSession({
id: proposal.id,
namespaces: approvedNamespaces,
sessionProperties: {
ton_getPublicKey: "a1b2c3d4e5f6...", // hex-encoded Ed25519 public key
ton_getStateInit: "te6cckEBAQEA..." // base64-encoded StateInit BoC
}
});This allows dApps to consume an active session without requiring additional requests to retrieve the wallet's public key and state initialization data.
Notes & Considerations
- If
fromis omitted, the wallet should prompt the user to select an address. - All requests and responses must comply with JSON-RPC structure (
id,jsonrpc, etc.). - Signature verification can be done using
ed25519.verifyon the original bytes. stateInitsupport is needed when your wallet supports contract deployment flows.- The
domainfield in responses indicates the originating application (dApp) domain.