Internal address formats

Accordingly to TEP 0002 there exist two internal address formats on TON Blockchain:

• raw;
• user-friendly.

Every internal address can be represented in each of these formats. However, these representations are equivalent: refer to exactly one address, although visually differ greatly from each other. For a detection how wallets and other applications use these formats, see the adresses workflow page.

Raw format

The raw format is the canonical, on-chain representation of the address of a smart contract. It is this format that is used by developers of smart contracts in the manual creation of messages and is inspired by the corresponding TL-B schemes.

Structure

In existent workchains, the raw format 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 that is derived from a smart contract state_init.

Example: 0:ca6e321c7cce9ecedf0a8ca2492ec8592494aa5fb5ce0387dff96ef6af982a3e

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

Drawbacks

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: for instance, each smart contract can be deployed on both Testnet and Mainnet, in which it will have the same address. An attempt to send real funds to the Testnet variant will result in their loss. It is desirable to have a flag in the address that prevents users from such a mistake.

User-friendly format

The main purpose of the user-friendly format is to help prevent users from accidentally losing their funds due to a small mistake in the raw format or unwise use of the bounce flag and from having to manually compose a message when they interact with the intended recipient through wallet applications (for instance, Tonkeeper).

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

Nota bene: this format can be applied only to addresses that are described according to the addr_std TL-B scheme, see addresses general info subpage.

Structure

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

1. Flags (1 byte): metadata that changes the handling of messages in the wallet application. 0x11 for sending bounceable messages, 0x51 for non-bounceable, add the 0x80 summand if that address should not be accepted by software running in Mainnet.
2. workchain_id (1 byte): an 8-bit signed integer.
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 8 bits of the user-friendly format encode the handling of messages, as defined in TEP 0002:

Address prefix	Binary form	Bounceable	Testnet-only
E...	00010001	Yes	No
U...	01010001	No	No
k...	10010001	Yes	Yes
0...	11010001	No	Yes

As we can see, there are 4 variants of the handling:

• send a bounceable message to a Mainnet address;
• send a non-bounceable message to a Mainnet address;
• send a bounceable message to a Testnet address;
• send a non-bounceable message to a Testnet address;

Encoding

The 36-byte structure is encoded into a 48-character non-space string using either standard base64 (i.e., with digits, upper- and lowercase Latin letters, / and +) or URL-safe base64 (with _ and - instead of / and +). Both encodings are valid and must be supported by applications.

Examples:

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

Nota bene: the same encoding is used for the so-called armored versions of public keys and ADNL addresses.

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 user-friendly format forms 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.

Drawbacks

• Public key extraction: it is impossible to extract the public key from the address, which is needed for some tasks (for example, to send an encrypted message to this address). Thus, until the smart contract is deployed for this address, there is no way to get the public key on-chain.
• UI: most OS do not allow you to select an address with double click because of _, -, /, + base64 symbols.

Summary

• Raw format is for system-level use and lack safety features.
• User-friendly format is for application-level use, include flags and a checksum.

Next steps

For more technical details, refer to:

• Account statuses: how addresses evolve (active, frozen, etc.).