Address formats

This article specifies the two standard address formats used on TON Blockchain:

• Raw format
• User-friendly format

The format you choose affects security and message processing.

Raw address

The raw address is the canonical, on-chain representation of a smart contract. It is designed for system-level use where precision is crucial, and UX features are not necessary.

Structure

A raw address consists of two components separated by a colon:

• workchain_id: a signed 32-bit integer identifying the WorkChain.
  Examples: -1 for the MasterChain and 0 for the BaseChain.
• account_id: a 256-bit identifier, represented as 64 hexadecimal characters.

Example: 0:ca6e321c7cce9ecedf0a8ca2492ec8592494aa5fb5ce0387dff96ef6af982a3e

note

Uppercase letters (A–F) may be used in address strings instead of their lowercase counterparts (a-f).

Limitations

Raw addresses lack built-in safety features, making them unsuitable for general use:

• No error detection: the format includes no checksum.
  A single-character mistake can cause irreversible loss of funds.
• No metadata: flags like isBounceable are unsupported, limiting control over message handling.

Due to these limitations, raw addresses should not be exposed to end-users.

User-friendly address

The user-friendly address format is a secure, base64/base64url-encoded wrapper around the raw address. It adds metadata flags and a checksum to prevent common errors and provide greater control over message routing.

Structure

A user-friendly address is a 36-byte structure with the following components:

1. Flags (1 byte): metadata that modifies message handling.
2. workchain_id (1 byte): an 8-bit signed integer (-1 for MasterChain is 0xff).
3. account_id (32 bytes): the 256-bit (big-endian) account identifier.
4. Checksum (2 bytes): a CRC16-CCITT checksum of the preceding 34 bytes.

The checksum mechanism in user-friendly addresses is similar to the Luhn algorithm, providing a first-line defense against input errors by validating format integrity upfront.

Flag definitions

The flags byte encodes bounce behavior and test-only options; its top 6 bits determine the first base64 character, as defined in TEP-2:

Address prefix	Binary form	Bounceable	Testnet-only
E...	000100.01	Yes	No
U...	010100.01	No	No
k...	100100.01	Yes	Yes
0...	110100.01	No	Yes

Key flags:

• isBounceable:
  • true (0x11): messages to non-existent/uninitialized contracts are returned.
  • false (0x51): funds are credited to the uninitialized account.
• isTestnetOnly:
  • true (0x80): address is valid only on the testnet. mainnet applications must reject such addresses.

Hex flag values per TEP‑2; see also the Cookbook section on flags in user-friendly addresses.

Learn more about non-bounceable messages and their use cases.

Encoding

The 36-byte structure is encoded into a 48-character string using either base64 or base64url. Both encodings are valid and must be supported by applications.

Examples:

• Bounceable: EQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPrHF
• Non-bounceable: UQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPuwA
• Bounceable-Testnet: kQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPgpP
• Testnet-only: 0QDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPleK

DNS address flags

In TON, DNS names such as mywallet.ton resolve to the underlying smart contract address. Applications choose bounceable/non-bounceable and test-only flags when serializing user-friendly addresses; DNS records do not store these flags.

Custom address safety

When developing custom solutions on TON Blockchain, it is critical to implement proper address handling logic. First, always verify whether the recipient address is initialized before sending funds to prevent unintended losses.

For address type selection: use bounceable addresses for user smart contracts with custom logic to ensure funds are returned if the contract is uninitialized or non-existent, and non-bounceable addresses for wallets to guarantee funds are credited even if the recipient is uninitialized.

Address conversion

Tools for converting between raw and user-friendly formats are essential for development and debugging.

• Online converter: ton.org/address
• APIs:
  • dton.io
  • toncenter.com
• SDKs: see conversion examples in the Cookbook and the SDKs page. For reference, see Address.spec.ts in ton-core: https://github.com/ton-org/ton-core/blob/main/src/address/Address.spec.ts

Armored base64 representations

TON also employs similar armored base64 representations, inspired by the user-friendly address format; these payloads are not addresses. For example, 256-bit Ed25519 public keys are represented by first creating a 36-byte sequence consisting of:

• Two one-byte tags: 0x3E (public key) followed by 0xE6 (Ed25519).
• 32 bytes containing the standard binary representation of the Ed25519 public key.
• 2 bytes containing the CRC16-CCITT checksum of the previous 34 bytes.

The resulting 36-byte sequence is converted into a 48-character base64 or base64url string in the standard fashion. For example, the Ed25519 public key E39ECDA0A7B0C60A7107EC43967829DBE8BC356A49B9DFC6186B3EAC74B5477D (usually represented by a sequence of 32 bytes such as: 0xE3, 0x9E, ..., 0x7D) presents itself through the armored representation as follows:

Pubjns2gp7DGCnEH7EOWeCnb6Lw1akm538YYaz6sdLVHfRB2

Summary

• Raw addresses are for system-level use and lack safety features.
• User-friendly addresses are for application-level use and include flags and a checksum.
• The isBounceable flag is critical for preventing fund loss when interacting with uninitialized contracts.
• Always use appropriate tools for address conversion.

Next steps

For more technical details, refer to:

• Address states: how addresses evolve (active, frozen, etc.).

Was this article useful?