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-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 first 6 bits of the address encode its type, 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.

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

Encoding

The 36-byte structure is encoded into a 48-character string using either standard base64 or URL-safe base64. 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 addresses such as mywallet.ton can be used as alternatives to raw and user-friendly addresses. These DNS addresses encapsulate user-friendly address data along with all necessary flags, allowing developers to retrieve the complete address configuration directly from the TON domain's DNS records.

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 invalid, 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 Address.spec.ts in the ton-core library for the conversion examples.
  It's also possible to make use of similar mechanisms through other SDKs.

Armored base64 representations

Additional binary data related to TON Blockchain employs similar armored base64 user-friendly address representations. These differentiate from one another depending on the first 4 characters of their byte tag. For example, 256-bit Ed25519 public keys are represented by first creating a 36-byte sequence using the process below in order:

• A single byte tag using the 0x3E format denotes a public key.
• A single byte tag using the 0xE6 format denotes a Ed25519 public key.
• 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?