OKX Connect sdk
Installation via cdn
You can add the following code to the HTML file, or replace "latest" with a specific version number, such as "1.3.7".
Once introduced, OKXTonConnectSDK will be available as a global object that can be directly referenced.
Using npm
``
npm install @okxconnect/tonsdk
new OKXTonConnect({metaData: {name, icon}})
Request Parameters
- metaData - object
- name - string: Application name (not unique).
- icon - string: URL for the application icon (PNG, ICO formats; best as 180x180px PNG).
Return Value
- okxTonConnect - OKXTonConnect
Example
`typescript
import { OKXTonConnect } from "@okxconnect/tonsdk";
const okxTonConnect = new OKXTonConnect({
metaData: {
name: "application name",
icon: "application icon url"
}
});
`
connect(request): Promise
Request Parameters
- request - object (optional)
- tonProof - string (optional): signature information；
- redirect - string (optional) : After processing the wallet event, the app will return the required deeplink, e.g. in Telegram environment, this field needs to pass the Telegram deeplink, when the wallet signing is done, OKX App will open the Telegram program through this deeplink, it is not recommended to set it in non-Telegram environment;
- openUniversalLink - boolean (可选) : When connecting to the wallet, whether to call up the OKX App client via Universal link; if set to true, when the user initiates the connection to the wallet, the OKX App client will be pulled up and a confirmation page will pop up, and if the OKX App client is not installed on the cell phone, it will be redirected to the download page;
Return Value
- Promise - string: PC web side can generate QR code according to this field, OKX App client can scan the generated QR code in web3 and connect to DApp;
Recommendations
- Set openUniversalLink to true in your mobile browser or mobile Telegram environment;
- Set openUniversalLink to false in PC browser environment, and generate QR code according to the returned universalLink, you can use OKX App client to scan the code to connect to it, and cancel the QR code pop-up window after successful connection;
Example
`typescript
import { OKXConnectError } from "@okxconnect/tonsdk";
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 has previously connected their wallet, use this method to restore the connection state:
restoreConnection(): Promise
Request parameters
None
Return Value
None
Example
`typescript`
okxTonConnect.restoreConnection()
Disconnects the connected wallet and deletes the current session. If you want to switch connected wallets, disconnect the current wallet first.
Example
`typescript
import { OKX_CONNECT_ERROR_CODES } from "@okxconnect/tonsdk";
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');
}
}
`
Get whether there is currently a connected wallet
Example
`typescript`
var connect: boolean = okxTonConnect.connected()
Method for sending a message to a wallet:
sendTransaction(transaction, options): Promise
Request parameters
- transaction - object
- validUntil - number :unix timestamp. The transaction will be invalid after this point
- from - string (optional): address of the sender to which the DApp is sending the transaction, defaults to the currently connected wallet address;
- messages - object[] : (array of messages): 1-4 output messages from the wallet contract to other accounts. All messages are sent out in order, but the
The wallet cannot guarantee that the messages will be delivered and executed in the same order.
- address - string : the destination of the message
- amount - string : The amount to be sent.
- stateInit - string (optional) : The original cell BoC encoded in Base64.
- payload - string (optional) : Base64 encoded raw cell BoC.
- options - object
- onRequestSent - () => void : This method is called when a signature request is sent;
Return value
- Promise - {boc: string}: signed result
Example
`typescript
import { OKXConnectError } from "@okxconnect/tonsdk";
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');
}
}
`
The wallet statuses are: successful connection, successful restoration of connection, disconnection, etc. You can use this method to get the status.
onStatusChange(
callback: (walletInfo) => void,
errorsHandler?: (err) => void
): () => void;
Request Parameters
- callback - (walletInfo) => void : This callback is called when the wallet state changes;
- walletinfo - object
- device - object
- appName - string : the name of the wallet
- platform - string : the platform of the wallet, (android,ios)
- appVersion - string : the version number of the wallet
- maxProtocolVersion - number : the version of the wallet, (android,ios)
- features - string[] : supported methods, current version is sendTransaction
- account - Account
- address - string : TON address raw (0:)
- 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 is called when an exception occurs due to a change in the wallet state;
- err - TonConnectError
- code - number
- message - string
Return Value
- () => void : Execute this method to save resources when there is no longer a need to listen for updates.
Example
`typescript
import { Wallet } from "@okxconnect/tonsdk";
const unsubscribe = okxTonConnect.onStatusChange((walletInfo: Wallet | null) => {
console.log('Connection status:', walletInfo);
}, (err: OKXConnectError) => {
console.log('Connection status:', err);
}
)
`
Call unsubscribe to save resources when you no longer need to listen for updates.
`typescript`
unsubscribe()
When the following events occur, corresponding event notifications will be sent, and the Dapp can add listeners as needed to handle the corresponding logic;
event
| event name | trigger timing |
|----------------------------------------|----------------------|
| OKX_TON_CONNECTION_STARTED | When the user starts to connect to the wallet |
| OKX_TON_CONNECTION_COMPLETED | When the user successfully connects to the wallet |
| OKX_TON_CONNECTION_ERROR | When the user canceled the connection or there was an error during the connection process |
| OKX_TON_CONNECTION_RESTORING_STARTED | When the dApp starts to resume 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 to disconnect from the wallet |
| OKX_TON_TRANSACTION_SENT_FOR_SIGNATURE | When the user sends a transaction for signature |
| OKX_TON_TRANSACTION_SIGNED | When the user successfully signs a transaction |
| OKX_TON_TRANSACTION_SIGNING_FAILED | When the user canceled the transaction signing or there was an error during the signing process |
Example
`typescript
import { OKX_TON_CONNECTION_AND_TRANSACTION_EVENT } from "@okxconnect/tonsdk";
window.addEventListener(OKX_TON_CONNECTION_AND_TRANSACTION_EVENT.OKX_TON_CONNECTION_STARTED, (event) => {
if (event instanceof CustomEvent) {
console.log('Transaction init', event.detail);
}
});
`
Get the currently connected account
example
`typescript
import { Account } from "@okxconnect/tonsdk";
var connect: Account = okxTonConnect.account()
`
Get the currently connected wallet
Example
`typescript
import { Wallet } from "@okxconnect/tonsdk";
var connect: Wallet = okxTonConnect.wallet()
`
Exceptions that may be thrown during connection, transaction, resumption of connection, and disconnection.
Exception
| Error Code | description |
|-------------------------------------------------|-------|
| OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR | Unknown Exception |
| OKX_CONNECT_ERROR_CODES.ALREADY_CONNECTED_ERROR | Wallet 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 |
`typescript``
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,
}