Reading and writing addresses

On this page, the main issues of interaction with the addresses are described:

• how to create and parse;
• how to check the validity;
• how to convert from one format to another.

Using online converter

The best user-friendly online parser and address converter in TON blockchain is TON Address tool. If the address is entered in any format, the system will provide all possible formats for the address, provided that it is entered correctly. Otherwise, a warning will be displayed indicating that the address is invalid.

Using SDK

There are at least four SDKs for interacting with TON blockchain, written in

• TypeScript;
• Java;
• Go;
• Python.

You can use any of them, including for working with addresses. However, we focus here on the most used one: the one written in TypeScript. Namely, we examine ton-core address module.

The internal addresses are represented as instances of the Address class. You can access it in your favorite IDE using the following import.

import { Address } from "@ton/core";

readonly workChain: number;
readonly hash: Buffer;

As for the external addresses, they are represented as instances of the ExternalAddress class. Similarly, you can access it as follows.

import { ExternalAddress } from "@ton/core";

readonly value: bigint;
readonly bits: number;

Create, parse, and convert addresses

The creation is simple.

// There is a hash validation check inside the Address constructor.
const internalAddress = new Address(some_wc, some_valid_hash);

const externalAddress = new ExternalAddress(some_value, some_bits);

You can parse the internal addresses string and then convert from one format to another as follows.

const address1 = Address.parse('EQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPrHF');
const address2 = Address.parse('0:ca6e321c7cce9ecedf0a8ca2492ec8592494aa5fb5ce0387dff96ef6af982a3e');
// or via its convenient wrapper
// const address1 = address('EQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPrHF');

// const address2 = address('0:ca6e321c7cce9ecedf0a8ca2492ec8592494aa5fb5ce0387dff96ef6af982a3e');

// these two addresses are equal
console.log(address1.equals(address2)); // true

// toString arguments: urlSafe    {true means using '-' and '_' instead of '+' and '/'; false means the opposite};
//                     bounceable {true means the address is bounceable; false means non-bounceable};
//                     testOnly   {true means the address is for Testnet; false means for Mainnet}.
// default values: true, true, false.

console.log(address1.toString()); // EQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPrHF
console.log(address1.toString({urlSafe: false})) // EQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff+W72r5gqPrHF
console.log(address1.toString({bounceable: false})) // UQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPuwA
console.log(address1.toString({testOnly: true})) // kQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPgpP
console.log(address1.toString({bounceable: false, testOnly: true})) // 0QDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPleK

// output the address in raw format
console.log(address1.toRawString()); // 0:ca6e321c7cce9ecedf0a8ca2492ec8592494aa5fb5ce0387dff96ef6af982a3e

// returns a Buffer with the user‑friendly format address
address1.toStringBuffer();

// the same for address2
console.log(address2.toString()); // EQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPrHF
console.log(address2.toRawString()); // 0:ca6e321c7cce9ecedf0a8ca2492ec8592494aa5fb5ce0387dff96ef6af982a3e

// returns a Buffer with the raw format address
address2.toStringBuffer();

If you are sure that your string accurately represents the address in raw or user-friendly format, you can also use the following methods.

const address1 = Address.parseFriendly('EQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPrHF');
const address2 = Address.parseRaw('0:ca6e321c7cce9ecedf0a8ca2492ec8592494aa5fb5ce0387dff96ef6af982a3e');

However, there is no separate method for parsing external addresses from a string.

Validate addresses

The validity of the address is checked at the time of its parsing. An attempt to parse an invalid address will result in an error. However, you can check separately whether a string is a valid address in raw or user-friendly formats.

console.log(Address.isFriendly('EQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPrHF')) // true
console.log(Address.isRaw('EQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPrHF')) // false

console.log(Address.isFriendly('0:ca6e321c7cce9ecedf0a8ca2492ec8592494aa5fb5ce0387dff96ef6af982a3e')) // false
console.log(Address.isRaw('0:ca6e321c7cce9ecedf0a8ca2492ec8592494aa5fb5ce0387dff96ef6af982a3e')) // true