UI#

安装及初始化#

请确保更新OKX App到 6.96.0版本或以后版本，即可开始接入：

将 OKX Connect 集成到您的 DApp 中，可以使用 npm:

npm install @okxconnect/ui
npm install @okxconnect/universal-provider

连接钱包之前，需要先创建一个可以提供UI界面的对象，用于后续连接钱包、发送交易等操作。

OKXUniversalConnectUI.init(dappMetaData, actionsConfiguration, uiPreferences, language)

请求参数

dappMetaData - object
- name - string: 应用名称，不会作为唯一表示
- icon - string: 应用图标的 URL。必须是 PNG、ICO 等格式，不支持 SVG 图标。最好传递指向 180x180px PNG 图标的 url。
actionsConfiguration - object
- modals - ('before' | 'success' | 'error')[] | 'all' 交易过程中的提醒界面展示模式，默认为'before'
- returnStrategy -string 'none' | ${string}://${string}; 针对app 钱包，指定当用户签署/拒绝请求时深层链接的返回策略，如果是在tg中，可以配置tg://resolve
- tmaReturnUrl -string 'back' | 'none' | ${string}://${string}; Telegram Mini Wallet 钱包中，用户签署/拒绝请求时深层链接的返回策略，一般配置back,表示签名后关闭钱包，会自动展示出dapp；none 表示签名后不做处理；默认为back；
uiPreferences -object
- theme - Theme 可以是：THEME.DARK, THEME.LIGHT, "SYSTEM"
language - "en_US" | "ru_RU" | "zh_CN" | "ar_AE" | "cs_CZ" | "de_DE" | "es_ES" | "es_LAT" | "fr_FR" | "id_ID" | "it_IT" | "nl_NL" | "pl_PL" | "pt_BR" | "pt_PT" | "ro_RO" | "tr_TR" | "uk_UA" | "vi_VN"; , 默认为en_US

返回值

OKXUniversalConnectUI

示例

import { OKXUniversalConnectUI } from "@okxconnect/ui";

const okxUniversalConnectUI = await OKXUniversalConnectUI.init({
    dappMetaData: {
        icon: "https://static.okx.com/cdn/assets/imgs/247/58E63FEA47A2B7D7.png",
        name: "OKX Connect Demo"
    },
    actionsConfiguration: {
        returnStrategy: 'tg://resolve',
        modals:"all",
        tmaReturnUrl:'back'
    },
    language: "en_US",
    uiPreferences: {
        theme: THEME.LIGHT
    },
});

连接钱包#

连接钱包去获取钱包地址，作为标识符和用于签名交易的必要参数

okxUniversalConnectUI.connect(connectParams: ConnectParams)

请求参数

connectParams - ConnectParams
- namespaces - [namespace: string]: ConnectNamespace ; 请求连接的可选信息，TRON的key为"tron"，如果请求的链中，有任何一个链钱包不支持的话，钱包会拒绝连接
  - chains: string[]; 链id信息
  - defaultChain?: string; 默认链
- optionalNamespaces - [namespace: string]: ConnectNamespace; 请求连接的可选信息，TRON的key为"tron"，如果对应的链信息钱包不支持，依然可以连接
  - chains: string[]; 链id信息
    - defaultChain?: string; 默认链
- sessionConfig: object
  - redirect: string 连接成功后的跳转参数，如果是Telegram中的Mini App，这里可以设置为Telegram的deeplink: "tg://resolve"

返回值

Promise<SessionTypes.Struct | undefined>
- topic: string; 会话标识
- namespaces: Record<string, Namespace>; 成功连接的namespace 信息
  - chains: string[]; 连接的链信息
  - accounts: string[]; 连接的账户信息
  - methods: string[]; 当前namespace下，钱包支持的方法
  - defaultChain?: string; 当前会话的默认链
- sessionConfig?: SessionConfig
  - dappInfo: object DApp 信息
    - name:string
    - icon:string
  - redirect?:string, 连接成功后的跳转参数示例

var session = await okxUniversalConnectUI.connect({
    namespaces: {
        tron: {
            chains: [
                "tron:mainnet"
            ],
        }
    },
    sessionConfig: {
        redirect: "tg://resolve"
    }
})

准备交易#

首先创建一个OKXTronProvider对象，构造函数传入okxUniversalConnectUI

import { OKXTronProvider } from "@okxconnect/universal-provider";
let okxTronProvider = new OKXTronProvider(okxUniversalConnectUI)

获取账户信息#

okxTronProvider.getAccount(chainId?)

请求参数

chainId: 请求的链，如tron:mainnet

返回值

Object
- address: string 钱包地址

示例

let result = okxTronProvider.getAccount("tron:mainnet")
//返回结构
{
    "address": "THyDJCGXYnwCSYNQeGYW98pptEVSHwaYx7"
}

签署消息#

okxTronProvider.signMessage(message, chainId?)

请求参数

message - string 需要签名的消息
chainId? - string, 请求执行方法的链,如tron:mainnet

返回值

Promise - string 签名结果

示例

let chainId = "tron:mainnet"
let signStr = "data need to sign ..."

let result = okxTronProvider.signMessage(signStr, chainId)
//返回:0xfc9003b1c8e68fdc93409aad911af274de1987130a36516f1c7c9353716463bf42bb400e0d6bffd4adface92dd3a01079ba32f8aebe3db1d5914f084b9f802711c

签署消息V2#

okxTronProvider.signMessageV2(message, chainId?)

请求参数

message - string 需要签名的消息。
chainId - string, 请求执行方法的链,如tron:mainnet

返回值

Promise - string 签名结果

示例

let chainId = "tron:mainnet"
let signStr = "data need to sign ..."

let result = okxTronProvider.signMessageV2(signStr, chainId)
//返回:0xfc9003b1c8e68fdc93409aad911af274de1987130a36516f1c7c9353716463bf42bb400e0d6bffd4adface92dd3a01079ba32f8aebe3db1d5914f084b9f802711c

签署交易 signTransaction#

okxTronProvider.signTransaction(transaction: any, chainId?: string)

请求参数

transaction - object，交易信息按照固定格式签名，可通过TronWeb.transactionBuilder生成
chainId? - string, 请求签名执行的链，如tron:mainnet

返回值

Promise - Object 签名后的交易

示例

let tronWeb = new TronWeb({
"fullHost": 'https://api.trongrid.io',
"headers": {},
"privateKey": ''
})
let address = okxTronProvider.getAccount("tron:mainnet").address
const transaction = await tronWeb.transactionBuilder.sendTrx("TGBcVLMnVtvJzjPWZpPiYBgwwb7th1w3BF", 1000, address);
let res = await okxTronProvider.signTransaction(transaction,"tron:mainnet")

/**返回结果
 {
 "visible": true,
 "txID": "cf93bbfb0152d832fcdb1c65cb12a979eab5a631de1b3d7d6437757e1b16ed40",
 "raw_data": {
 "contract": [{
 "parameter": {
 "type_url": "type.googleapis.com/protocol.TransferContract",
 "value": {
 "amount": 1000,
 "contract_address": "",
 "owner_address": "THyDJCGXYnwCSYNQeGYW98pptEVSHwaYx7",
 "to_address": "TGBcVLMnVtvJzjPWZpPiYBgwwb7th1w3BF"
 }
 },
 "type": "TransferContract"
 }],
 "expiration": 1732073850000,
 "ref_block_bytes": "7ecf",
 "ref_block_hash": "7b3a6bc87d9edb9e",
 "timestamp": 1732073790000
 },
 "raw_data_hex": "0a027ecf22087b3a6bc87d9edb9e40908996bdb4325a66080112620a2d747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5472616e73666572436f6e747261637412310a154157c140be01fa2bbabf7f055ab879d0c05725293c12154144295a45f811a9d595562562a2e27685291a715818e80770b0b492bdb432",
 "signature": ["239b402a7605199c6969f6f4da37a355452bd942c222adfc625721d18a1fff3223f92c1d8eaf5856c0e41ce80761fd2adb80d026276d6710ad183a713af7a78d00"]
 }
 */

签署交易并广播上链 signAndSendTransaction#

okxTronProvider.signAndSendTransaction(transaction, chainId?)

请求参数

transaction - object，交易信息按照固定格式签名，可通过TronWeb.transactionBuilder生成
chainId - string, 请求签名执行的链，如tron:mainnet

返回值

Promise - string 交易hash

示例

let tronWeb = new TronWeb({
    "fullHost": 'https://api.trongrid.io',
    "headers": {},
    "privateKey": ''
})
let address = okxTronProvider.getAccount("tron:mainnet").address
const transaction = await tronWeb.transactionBuilder.sendTrx("TGBcVLMnVtvJzjPWZpPiYBgwwb7th1w3BF", 1000, address); //转账TRX
let res = await okxTronProvider.signAndSendTransaction(transaction, "tron:mainnet")
//返回值：50a47e450024c079510a39433e28de0bcac8406d731aadab7d772998dfce2aab

断开钱包连接#

断开已连接钱包，并删除当前会话，如果要切换连接钱包，请先断开当前钱包

okxUniversalConnectUI.disconnect()

Event事件#

// 生成 universalLink
universalUi.on("display_uri", (uri) => {
  console.log(uri);
});
// session 信息变更会触发该事件；
universalUi.on("session_update", (session) => {
  console.log(JSON.stringify(session));
});
// 断开连接会触发该事件；
universalUi.on("session_delete", ({topic}) => {
  console.log(topic);
});
// 连接并签名时,签名结果会触发该事件;
universalUi.on("connect_signResponse", (signResponse) => {
  console.log(signResponse);
});

错误码#

在连接，交易，断开连接的过程中可能抛出的异常;

异常

错误码	描述
OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR	未知异常
OKX_CONNECT_ERROR_CODES.ALREADY_CONNECTED_ERROR	钱包已连接
OKX_CONNECT_ERROR_CODES.NOT_CONNECTED_ERROR	钱包未连接
OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR	用户拒绝
OKX_CONNECT_ERROR_CODES.METHOD_NOT_SUPPORTED	方法不支持
OKX_CONNECT_ERROR_CODES.CHAIN_NOT_SUPPORTED	链不支持
OKX_CONNECT_ERROR_CODES.WALLET_NOT_SUPPORTED	钱包不支持
OKX_CONNECT_ERROR_CODES.CONNECTION_ERROR	连接异常

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,
    CHAIN_NOT_SUPPORTED = 500,
    WALLET_NOT_SUPPORTED = 600,
    CONNECTION_ERROR = 700
}

签署交易并广播上链 signAndSendTransaction

断开钱包连接

Event事件

错误码