TON chain, fully known as The Open Network, aims to provide fast and efficient transaction processing capabilities, while supporting smart contracts and decentralized applications. TON uses an innovative design called "multi-chain architecture," enabling high scalability and allowing multiple blockchains to run in parallel, thus improving the throughput and performance of the entire network.
Please ensure that your OKX App is updated to version 6.84.0 or later before integration. To integrate OKX Connect into your DApp, you can install it using npm
:
npm install okxconnect
Before connecting to the wallet, you need to create an object for future operations such as wallet connection and transaction sending.
new OKXTonConnect({metaData: {name, icon}})
Request Parameters
Return Value
Example
import {OKXTonConnect} from "okxconnect";
const okxTonConnect = new OKXTonConnect({
metaData: {
name: "application name",
icon: "application icon url"
}
});
Connect to the wallet to obtain the wallet address, which serves as an identifier and is a necessary parameter for signing transactions.
connect(request): Promise<string>;
Request Parameters
request - object (optional)
tonProof - string (optional): Signature information;
redirect - string (optional): Deeplink to return to the app after the wallet event is processed. For example, in the Telegram environment, this field should pass Telegram's deeplink. After signing is completed in the wallet, the OKX App will use this deeplink to open Telegram;
openUniversalLink - boolean (optional): Whether to invoke the OKX App client through a Universal Link when connecting the wallet. When set to true, the OKX App client will be launched, and a confirmation page will be displayed. If the OKX App client is not installed, it will redirect to the download page;
Return Value
Recommendations
Set openUniversalLink
to true
in mobile browsers or mobile Telegram environments.
Set openUniversalLink
to false
in PC browser environments. Generate a QR code based on the returned universalLink
. Users can scan this QR code with the OKX App client to connect. Once the connection is successful, dismiss the QR code popup.
Example
import {OkxConnectError} from "okxconnect";
try {
okxTonConnect.connect({
tonProof: "signmessage",
redirect: "tg://resolve",
openUniversalLink: true
})
} catch (error) {
if (error instanceof OkxConnectError) {
if (error.code === OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR) {
alert('User reject');
} else if (error.code === OKX_CONNECT_ERROR_CODES.ALREADY_CONNECTED_ERROR) {
alert('Already connected');
} else {
alert('Unknown error happened');
}
} else {
alert('Unknown error happened');
}
}
If the user previously connected a wallet, this method can be called to restore the previous connection state when re-entering or refreshing the page.
restoreConnection(): Promise<void>
Request Parameters
None
Return Value
None
Example
okxTonConnect.restoreConnection()
Disconnect the connected wallet and delete the current session. If you need to switch wallets, disconnect the current wallet first.
Example
import {OKX_CONNECT_ERROR_CODES} from "okxconnect";
try {
await okxTonConnect.disconnect()
} catch (error) {
if (error instanceof OkxConnectError) {
switch (error.code) {
case OKX_CONNECT_ERROR_CODES.NOT_CONNECTED_ERROR:
alert('Not connected');
break;
default:
alert('Unknown error happened');
break;
}
} else {
alert('Unknown error happened');
}
}
Check if the wallet is currently connected.
Example
var connect: boolean = okxTonConnect.connected()
Method to send a message to the wallet:
sendTransaction(transaction, options): Promise<SendTransactionResponse>
Request Parameters
Return Value
Promise - {boc: string}
: Signed result
Example
import {OkxConnectError} from "okxconnect";
let transactionRequest = {
"validUntil": Date.now() / 1000 + 360,
"from": "0:348bcf827469c5fc38541c77fdd91d4e347eac200f6f2d9fd62dc08885f0415f",
"messages": [
{
"address": "0:412410771DA82CBA306A55FA9E0D43C9D245E38133CB58F1457DFB8D5CD8892F",
"amount": "20000000",
"stateInit": "base64bocblahblahblah==" //deploy contract
}, {
"address": "0:E69F10CC84877ABF539F83F879291E5CA169451BA7BCE91A37A5CED3AB8080D3",
"amount": "60000000",
"payload": "base64bocblahblahblah==" //transfer nft to new deployed account 0:412410771DA82CBA306A55FA9E0D43C9D245E38133CB58F1457DFB8D5CD8892F
}
]
}
let requestOptions = {
onRequestSent: () => {
//requestMsgSend
}
}
try {
const result = await okxTonConnect.sendTransaction(transactionRequest, requestOptions);
} catch (error) {
if (error instanceof OkxConnectError) {
switch (error.code) {
case OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR:
alert('You rejected the transaction.');
break;
case OKX_CONNECT_ERROR_CODES.NOT_CONNECTED_ERROR:
alert('Not connected');
break;
default:
alert('Unknown error happened');
break;
}
} else {
alert('Unknown error happened');
}
}
Wallet statuses such as connection success, reconnection success, and disconnection can all be tracked using this method.
onStatusChange( callback: (walletInfo) => void, errorsHandler?: (err) => void ): () => void;
Request Parameters
- callback - (walletInfo) => void: This callback will be triggered when the wallet status changes;
- walletInfo - object
- device - object
- appName - string: Wallet name
- platform - string: Wallet platform (android, iOS)
- appVersion - string: Wallet version number
- maxProtocolVersion - number:
- features - string[]: Supported methods, current version supports sendTransaction
- account - Account
- address - string: TON address in raw form (`0:<hex>`)
- chain - "-239"
- walletStateInit - string: Base64 (not URL safe) encoded stateinit cell for the wallet contract
- publicKey - string: HEX string without 0x
- connectItems - object
- name - string: "ton_proof"
- proof - object
- timestamp - number: Timestamp
- domain - object
- lengthBytes - number: AppDomain Length
- value - string: App domain name (as URL part, without encoding)
- payload - string: Base64-encoded signature
- signature - string: Payload from the request
- errorsHandler - (err: OkxConnectError) => void: This errorsHandler will be called when an error occurs during wallet status changes;
- err - TonConnectError
- code - number
- message - string
Return Value
Example
import {Wallet} from "okxconnect";
const unsubscribe = okxTonConnect.onStatusChange((walletInfo: Wallet | null) => {
console.log('Connection status:', walletInfo);
}, (err: OkxConnectError) => {
console.log('Connection status:', err);
}
)
unsubscribe()
Notifications for corresponding events will be sent when the following events occur. Dapp can add listeners as needed to handle the corresponding logic.
Event List
Event Name | Trigger Timing |
---|---|
OKX_TON_CONNECTION_STARTED | When the user starts connecting to the wallet |
OKX_TON_CONNECTION_COMPLETED | When the user successfully connects to the wallet |
OKX_TON_CONNECTION_ERROR | When the user cancels the connection or an error occurs during the connection process |
OKX_TON_CONNECTION_RESTORING_STARTED | When the dApp starts restoring the connection |
OKX_TON_CONNECTION_RESTORING_COMPLETED | When the dApp successfully restores the connection |
OKX_TON_CONNECTION_RESTORING_ERROR | When the dApp fails to restore the connection |
OKX_TON_DISCONNECTION | When the user starts disconnecting the wallet |
OKX_TON_TRANSACTION_SENT_FOR_SIGNATURE | When the user sends a transaction for signing |
OKX_TON_TRANSACTION_SIGNED | When the user successfully signs the transaction |
OKX_TON_TRANSACTION_SIGNING_FAILED | When the user cancels the transaction signing or an error occurs during the signing process |
Example
import {OKX_TON_CONNECTION_AND_TRANSACTION_EVENT} from "okxconnect";
window.addEventListener(OKX_TON_CONNECTION_AND_TRANSACTION_EVENT.OKX_TON_CONNECTION_STARTED, (event) => {
if (event instanceof CustomEvent) {
console.log('Transaction init', event.detail);
}
});
Example
import {Account} from "okxconnect";
var connect: Account = okxTonConnect.account()
Retrieve Wallet Information
Retrieve the currently connected wallet.
Example
import {Wallet} from "okxconnect";
var connect: Wallet = okxTonConnect.wallet()
Exceptions that may be thrown during connection, transaction, restoring connection, or disconnection processes.
Exceptions
Errorcode | Des |
---|---|
OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR | Unknown error |
OKX_CONNECT_ERROR_CODES.ALREADY_CONNECTED_ERROR | Wallet already connected |
OKX_CONNECT_ERROR_CODES.NOT_CONNECTED_ERROR | Wallet not connected |
OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR | User rejected |
OKX_CONNECT_ERROR_CODES.METHOD_NOT_SUPPORTED | Method not supported |
export enum OKX_CONNECT_ERROR_CODES {
UNKNOWN_ERROR = 0,
ALREADY_CONNECTED_ERROR = 11,
NOT_CONNECTED_ERROR = 12,
USER_REJECTS_ERROR = 300,
METHOD_NOT_SUPPORTED = 400,
}