|
| 1 | +--- |
| 2 | +title: "TON" |
| 3 | +description: TON JSON-RPC Methods |
| 4 | +--- |
| 5 | + |
| 6 | +## Network / Chain Information |
| 7 | + |
| 8 | +| CAIP-2 | Chain ID | Name | RPC Endpoint | Namespace | |
| 9 | +|--------|----------|------|--------------|-----------| |
| 10 | +| `ton:-239` | `-239` | TON Mainnet | `https://toncenter.com/api/v2/jsonRPC` | `ton` | |
| 11 | +| `ton:-3` | `-3` | TON Testnet | `https://testnet.toncenter.com/api/v2/jsonRPC` | `ton` | |
| 12 | + |
| 13 | +## RPC Methods |
| 14 | + |
| 15 | +Wallets must support the following JSON-RPC methods over WalletConnect sessions. No events are required. |
| 16 | + |
| 17 | +## ton_sendMessage |
| 18 | + |
| 19 | +Submit one or more transaction messages to the TON network. |
| 20 | + |
| 21 | +### Request |
| 22 | + |
| 23 | +```typescript |
| 24 | +interface TonSendMessageRequest { |
| 25 | + method: 'ton_sendMessage'; |
| 26 | + params: TonSendTransactionParams[]; |
| 27 | +} |
| 28 | + |
| 29 | +interface TonSendTransactionParams { |
| 30 | + valid_until?: number; // optional UNIX timestamp |
| 31 | + from?: string; // optional sender address (TEP-123 format) |
| 32 | + messages: TonTransactionMessage[]; |
| 33 | +} |
| 34 | + |
| 35 | +interface TonTransactionMessage { |
| 36 | + address: string; // recipient in TEP-123 format |
| 37 | + amount: number | string; // value in nanotons |
| 38 | + payload?: string; // optional base64 BoC |
| 39 | + stateInit?: string; // optional base64 BoC |
| 40 | +} |
| 41 | +``` |
| 42 | + |
| 43 | +### Example Request |
| 44 | + |
| 45 | +```json |
| 46 | +{ |
| 47 | + "id": 123, |
| 48 | + "jsonrpc": "2.0", |
| 49 | + "params": { |
| 50 | + "chainId": "ton:-239", |
| 51 | + "request": { |
| 52 | + "method": "ton_sendMessage", |
| 53 | + "params": [ |
| 54 | + { |
| 55 | + "valid_until": 1658253458, |
| 56 | + "from": "EQDmnxDMhId6v1Ofg_h5KR5coWlFG6e86Ro3pc7Tq4CA0-Jn", |
| 57 | + "messages": [ |
| 58 | + { |
| 59 | + "address": "EQBBJBB3HagsujBqVfqeDUPJ0kXjgTPLWPFFffuNXNiJL0aA", |
| 60 | + "amount": "20000000", |
| 61 | + "stateInit": "base64boc..." |
| 62 | + }, |
| 63 | + { |
| 64 | + "address": "EQDmnxDMhId6v1Ofg_h5KR5coWlFG6e86Ro3pc7Tq4CA0-Jn", |
| 65 | + "amount": "60000000", |
| 66 | + "payload": "base64boc..." |
| 67 | + } |
| 68 | + ] |
| 69 | + } |
| 70 | + ] |
| 71 | + } |
| 72 | + } |
| 73 | +} |
| 74 | +``` |
| 75 | + |
| 76 | +### Success Response |
| 77 | + |
| 78 | +```json |
| 79 | +{ |
| 80 | + "jsonrpc": "2.0", |
| 81 | + "id": 123, |
| 82 | + "result": "base64bocEncodedTransaction" |
| 83 | +} |
| 84 | +``` |
| 85 | + |
| 86 | +<Note> |
| 87 | +The `base64bocEncodedTransaction` in the result is a base64 encoded BOC (Bag of Cells) of an external message. |
| 88 | +</Note> |
| 89 | + |
| 90 | +#### Example: Building an External-In Message |
| 91 | + |
| 92 | +```typescript |
| 93 | +// Build external-in message for the result |
| 94 | +const message: Message = { |
| 95 | + info: { |
| 96 | + type: 'external-in', |
| 97 | + src: null, |
| 98 | + dest: Address.parse("<the sender address>"), |
| 99 | + importFee: BigInt(0) |
| 100 | + }, |
| 101 | + init: null, |
| 102 | + body: transfer |
| 103 | +} |
| 104 | + |
| 105 | +const externalMessageCell = beginCell() |
| 106 | + .store(storeMessage(message, { forceRef: true })) |
| 107 | + .endCell() |
| 108 | + |
| 109 | +return externalMessageCell.toBoc().toString('base64') |
| 110 | +``` |
| 111 | + |
| 112 | +### Error Response |
| 113 | + |
| 114 | +```json |
| 115 | +{ |
| 116 | + "jsonrpc": "2.0", |
| 117 | + "id": 123, |
| 118 | + "error": { |
| 119 | + "code": <number>, |
| 120 | + "message": "<error message>" |
| 121 | + } |
| 122 | +} |
| 123 | +``` |
| 124 | + |
| 125 | +## ton_signData |
| 126 | + |
| 127 | +Sign an off-chain payload (text, binary, or cell) for authentication or verification by dApps. |
| 128 | + |
| 129 | +### Request |
| 130 | + |
| 131 | +```typescript |
| 132 | +interface TonSignDataRequest { |
| 133 | + method: 'ton_signData'; |
| 134 | + params: TonSignDataParams[]; |
| 135 | +} |
| 136 | + |
| 137 | +type TonSignDataParams = |
| 138 | + | { type: 'text'; text: string; from?: string } |
| 139 | + | { type: 'binary'; bytes: string; from?: string } |
| 140 | + | { type: 'cell'; schema: string; cell: string; from?: string }; |
| 141 | +``` |
| 142 | + |
| 143 | +### Example Request |
| 144 | + |
| 145 | +```json |
| 146 | +{ |
| 147 | + "id": 123, |
| 148 | + "jsonrpc": "2.0", |
| 149 | + "params": { |
| 150 | + "chainId": "ton:-239", |
| 151 | + "request": { |
| 152 | + "method": "ton_signData", |
| 153 | + "params": [ |
| 154 | + { |
| 155 | + "type": "text", |
| 156 | + "text": "Confirm new 2FA number:\\n+1 234 567 8901", |
| 157 | + "from": "EQDmnxDMhId6v1Ofg_h5KR5coWlFG6e86Ro3pc7Tq4CA0-Jn" |
| 158 | + } |
| 159 | + ] |
| 160 | + } |
| 161 | + } |
| 162 | +} |
| 163 | +``` |
| 164 | + |
| 165 | +### Success Response |
| 166 | + |
| 167 | +```json |
| 168 | +{ |
| 169 | + "jsonrpc": "2.0", |
| 170 | + "id": 123, |
| 171 | + "result": { |
| 172 | + "signature": "base64_signature", |
| 173 | + "address": "raw_wallet_address", |
| 174 | + "timestamp": 1658253458, |
| 175 | + "domain": "yourapp.com", |
| 176 | + "payload": { |
| 177 | + "type": "text", |
| 178 | + "text": "Confirm new 2FA number:\\n+1 234 567 8901" |
| 179 | + } |
| 180 | + } |
| 181 | +} |
| 182 | +``` |
| 183 | + |
| 184 | +### Error Response |
| 185 | + |
| 186 | +```json |
| 187 | +{ |
| 188 | + "jsonrpc": "2.0", |
| 189 | + "id": 123, |
| 190 | + "error": { |
| 191 | + "code": <number>, |
| 192 | + "message": "<error message>" |
| 193 | + } |
| 194 | +} |
| 195 | +``` |
| 196 | + |
| 197 | +## Notes & Considerations |
| 198 | + |
| 199 | +- If `from` is omitted, the wallet should prompt the user to select an address. |
| 200 | +- All requests and responses must comply with JSON-RPC structure (`id`, `jsonrpc`, etc.). |
| 201 | +- Signature verification can be done using `ed25519.verify` on the original bytes. |
| 202 | +- `stateInit` support is needed when your wallet supports contract deployment flows. |
| 203 | +- The `domain` field in responses indicates the originating application (dApp) domain. |
0 commit comments