Skip to main content
TON (The Open Network) is the blockchain behind Telegram. This guide covers TON-specific features when using Dfns wallets.

​
Wallet architecture

On TON, wallets are smart contracts. Dfns uses wallet contract version 4 (v4), which provides a good balance of features and gas efficiency.

​
Wallet lifecycle

  1. Address generation: When you create a TON wallet in Dfns, an address is derived from the public key
  2. Receiving funds: You can receive native TON immediately at this address
  3. First outbound transfer: The wallet contract is deployed on-chain when you make your first outbound transfer
You don’t need to manually deploy the wallet - Dfns handles this automatically on your first outbound transaction.
If you use the Broadcast Transaction endpoint directly, you must include the wallet deployment message in the payload for the first transaction. The automatic deployment only applies to the Transfer API.

​
Jetton tokens (TEP-74)

TON uses Jettons for fungible tokens, following the TEP-74 standard. Each token you hold is stored in a separate Jetton Wallet - a dedicated contract derived from your main wallet address. You cannot interact with Jetton Wallets directly; transfers go through your main wallet.

​
Transferring Jettons

Use the Transfer Asset endpoint with kind: Tep74 and the token’s master contract address.

​
How Jetton transfers work

  1. You send an “external IN” message to your wallet contract
  2. Your wallet sends a transfer request to your Jetton Wallet
  3. Your Jetton Wallet transfers tokens to the recipient’s Jetton Wallet
  4. The recipient’s Jetton Wallet sends a notification to the recipient’s main wallet
  5. Excess TON (from fees) is returned to you
Dfns includes 0.1 TON with all Jetton transfers to cover fees along the message chain. Any excess is returned to your wallet.
If you see a skipped_all_actions error, it means the transaction didn’t have enough TON to pay fees for all messages in the chain. The compute phase succeeded, but the action phase couldn’t execute because funds ran out. Ensure your wallet has sufficient TON balance.

​
Indexing behavior

Dfns relies on notification messages to index inbound Jetton transfers. If a sender omits the notification (to save fees), the transfer may not appear in your transaction history until a subsequent transaction triggers a balance update. Similarly, Dfns does not index all bounce messages. If a transaction fails and bounces, the balance will be updated on your next successful transaction.

​
Transfers

Use the Transfer Asset endpoint for TON transfers:
  • Native TON: Use kind: Native with amount in nanoTON (1 TON = 1,000,000,000 nanoTON)
  • Jettons: Use kind: Tep74 with the token’s master contract address
Both transfer types support an optional memo field.

​
Address formats

TON addresses come in two formats:
FormatPrefixDescription
BounceableEQ...For smart contracts; failed transactions bounce back
Non-bounceableUQ...For regular wallets; failed transactions don’t bounce
Dfns wallet addresses are non-bounceable by default.
When sending to a bounceable address, ensure the recipient exists and can process the message. Otherwise, consider using the non-bounceable version.

​
Fee structure

TON has a complex fee model where you pay fees when:
  • Sending messages
  • Receiving messages (deducted from the message value)
  • Storing data on-chain
Some fees can even be negative (you receive a refund). Dfns abstracts this complexity - you only need to ensure your wallet has enough TON for gas.

​
Fee sponsorship

TON wallet v5 supports fee payers (gasless transactions), but Dfns currently uses wallet v4. The Dfns Fee Sponsor feature is not available for TON at this time.

​
SDK integration

For full transaction control, use the Dfns SDK with @ton/ton. See the TON integration example.