okx
介绍
什么是连接钱包支持的网络
连接App或Mini钱包
接入前提
EVM 兼容链
Bitcoin 兼容链
Solana
TON
SUI
Aptos/Movement
SDKUI
Cosmos 系/Sei
Tron
Starknet
常见问题
连接浏览器插件钱包
接入前提
EVM 兼容链
Bitcoin 兼容链
Tron
Solana
TON
Aptos/Movement
Cosmos 系/Sei
SUI
Stacks
Starknet
Cardano
Nostr
NEAR
WAX
设置图标
连接App或Mini钱包

UI#

在 SDK 的基础上，我们也提供了 UI 界面。如果选择通过UI接入，若DApp运营在 Telegram内，则用户可以选择唤起移动端App钱包或者停留在Telegram并唤起欧易 Telegram Mini 钱包。

安装及初始化#

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

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

npm install @okxconnect/ui
npm install @okxconnect/aptos-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 钱包，指定当用户签署/拒绝请求时深层链接的返回策略，如果是在telegram中，可以配置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"
    },
    language: "en_US",
    uiPreferences: {
        theme: THEME.LIGHT
    },
});

连接钱包#

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

okxUniversalConnectUI.openModal(connectParams: ConnectParams)

请求参数

  • connectParams - ConnectParams
    • namespaces - [namespace: string]: ConnectNamespace ; 请求连接的必要信息，EVM系的key为"eip155"，Aptos系的key为"aptos" ，如果请求的链中，有任何一个链钱包不支持的话，钱包会拒绝连接；
      • chains: string[]; 链id信息,
      • defaultChain?: string; 默认链
    • optionalNamespaces - [namespace: string]: ConnectNamespace; 请求连接的可选信息， EVM系的key为"eip155"，，Aptos系的key为"aptos" ，如果对应的链信息钱包不支持，依然可以连接；
      • 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.openModal({
    namespaces: {
        aptos: {
            chains: ["aptos:mainnet", // aptos mainnet
                  // "movement:testnet",// movement testnet
            ],
        }
    },
    sessionConfig: {
        redirect: "tg://resolve"
    }
})

连接钱包并签名#

连接钱包获取钱包地址，并对数据进行签名；签名结果会在"connect_signResponse"的event中回调；

await okxUniversalConnectUI.openModalAndSign(connectParams: ConnectParams, signRequest: RequestParams[])

请求参数

  • connectParams - ConnectParams
    • namespaces - [namespace: string]: ConnectNamespace ; 请求连接的必要信息，Aptos系的key为"aptos" ，如果请求的链中，有任何一个链钱包不支持的话，钱包会拒绝连接；
      • chains: string[]; 链id信息,
      • defaultChain?: string; 默认链
    • optionalNamespaces - [namespace: string]: ConnectNamespace; 请求连接的可选信息，Aptos系的key为"aptos" ，如果对应的链信息钱包不支持，依然可以连接；
      • chains: string[]; 链id信息,
      • defaultChain?: string; 默认链
    • sessionConfig: object
      • redirect: string 连接成功后的跳转参数，如果是Telegram中的Mini App，这里可以设置为Telegram的deeplink: "tg://resolve"
  • signRequest - RequestParams[]; 请求连接并签名的方法, 同时最多只能支持一个方法；
    • method: string; 请求的方法名称, Aptos系支持的方法有："aptos_signMessage"；
    • chainId: string; 执行方法所在的链的ID, 该chainId必须包含在上面的namespaces中；
    • params: unknown[] | Record<string, unknown> | object | undefined; 请求的方法对应的参数；

返回值

  • 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

示例

// 先添加签名结果监听
okxUniversalConnectUI.on("connect_signResponse", (signResponse) => {
  console.log(signResponse);
});
var session = await okxUniversalConnectUI.openModalAndSign({
        namespaces: {
            aptos: {
                chains: ["aptos:mainnet", // aptos mainnet
                 // "movement:testnet",// movement testnet
                ],
            }
        },
        sessionConfig: {
            redirect: "tg://resolve"
        }
    },
    [
        {
            chainId: "aptos:mainnet",
            method: "aptos_signMessage",
            params: {
                address: true,
                application: true,
                chainId: true,
                message: "Hello Aptos",
                nonce: "1234"
            }
        }
])

判断钱包是否已连接#

获取当前是否有连接钱包;

返回值

  • boolean

示例

okxUniversalConnectUI.connected()

准备交易#

首先创建一个OKXAptosProvider对象，构造函数传入OKXUniversalProvider

import { OKXAptosProvider } from "@okxconnect/aptos-provider";
let okxAptosProvider = new OKXAptosProvider(okxUniversalConnectUI)

获取钱包地址及publicKey#

okxAptosProvider.getAccount(chain)

请求参数

  • chain: string, 获取钱包地址的链id,不传则默认取第一个连接的aptos系地址

返回值

  • Object
    • address: string 钱包地址
    • publicKey: string 公钥

签名#

okxAptosProvider.signMessage(message, chain)

请求参数

  • message - object
    • address?: boolean; // Should we include the address of the account in the message
    • application?: boolean; // Should we include the domain of the DApp
    • chainId?: boolean; // Should we include the current chain id the wallet is connected to
    • message: string; // The message to be signed and displayed to the user
    • nonce: string; // A nonce the DApp should generate
  • chain: string, 请求签名执行的链，建议传递此参数；连接多条链时为必传参数；

返回值

  • Promise - object
    • address: string;
    • application: string;
    • chainId: number;
    • fullMessage: string; // The message that was generated to sign
    • message: string; // The message passed in by the user
    • nonce: string;
    • prefix: string; // Should always be APTOS
    • signature: string; // The signed full message

签单笔交易#

okxAptosProvider.signTransaction(transaction, chain)

请求参数

  • transaction - object | SimpleTransaction 交易数据对象
  • chain: string, 请求签名执行的链，建议传递此参数；连接多条链时为必传参数；

返回值

  • Promise - Buffer 签名结果;

签多笔交易并上链#

okxAptosProvider.signAndSubmitTransaction(transactions, chain)

请求参数

  • transactions - object | SimpleTransaction 交易数据对象
  • chain: string, 请求签名执行的链，建议传递此参数；连接多条链时为必传参数；

返回值

  • Promise - string 交易hash;

示例

//签名消息
let data = {
    address:true,
    application:true,
    chainId:true,
    message:"Hello OKX",
    nonce:"1234"
}


let provider = new OKXAptosProvider(okxUniversalConnectUI)
let message = await provider.signMessage(data, "aptos:mainnet")

//返回值 {"address":"0x2acddad65c27c6e5b568b398f0d1d01ebb8b55466461bbd51c1e42763a92fdfe","application":"http://192.168.101.13","chainId":"aptos:mainnet","fullMessage":"APTOS\naddress: 0x2acddad65c27c6e5b568b398f0d1d01ebb8b55466461bbd51c1e42763a92fdfe\napplication: http://192.168.101.13\nchainId: aptos:mainnet\nmessage: 123 签名测试!\nnonce: 1234","message":"123 签名测试!","nonce":"1234","prefix":"APTOS","signature":"0xef4e587f537b80a2f4e424079984b80e130c92d939a92225764be00ed36486521e8857b8a222de4023c5f4d2e9fd2f62c26ca8a43694660583c8a5d4328da303","verified":true}

//签名交易并上链
const config = new AptosConfig({ network: Network.MAINNET });
const aptos = new Aptos(config);
//支持通过@aptos-labs/ts-sdk创建的交易
const transaction = await aptos.transaction.build.simple({
    sender: "0x07897a0496703c27954fa3cc8310f134dd1f7621edf5e88b5bf436e4af70cfc6",
    data: {
        function: "0x80273859084bc47f92a6c2d3e9257ebb2349668a1b0fb3db1d759a04c7628855::router::swap_exact_coin_for_coin_x1",
        typeArguments: ["0x1::aptos_coin::AptosCoin", "0x111ae3e5bc816a5e63c2da97d0aa3886519e0cd5e4b046659fa35796bd11542a::stapt_token::StakedApt", "0x0163df34fccbf003ce219d3f1d9e70d140b60622cb9dd47599c25fb2f797ba6e::curves::Uncorrelated", "0x80273859084bc47f92a6c2d3e9257ebb2349668a1b0fb3db1d759a04c7628855::router::BinStepV0V05"],
        functionArguments: ["10000", ["9104"], ["5"], ["true"]],
    },
});
let result1 = await provider.signAndSubmitTransaction(transaction, "aptos:mainnet")

//同时支持下方数据格式的交易
let transactionData = {
  "arguments": ["100000",["0","0","10533"],["10","5","5"],["false","false","true"]],
  "function": "0x80273859084bc47f92a6c2d3e9257ebb2349668a1b0fb3db1d759a04c7628855::router::swap_exact_coin_for_coin_x3",
  "type": "entry_function_payload",
  "type_arguments": ["0x1::aptos_coin::AptosCoin","0x73eb84966be67e4697fc5ae75173ca6c35089e802650f75422ab49a8729704ec::coin::DooDoo","0x53a30a6e5936c0a4c5140daed34de39d17ca7fcae08f947c02e979cef98a3719::coin::LSD","0xf22bede237a07e121b56d91a491eb7bcdfd1f5907926a9e58338f964a01b17fa::asset::USDC","0x80273859084bc47f92a6c2d3e9257ebb2349668a1b0fb3db1d759a04c7628855::router::CurveV1","0x0163df34fccbf003ce219d3f1d9e70d140b60622cb9dd47599c25fb2f797ba6e::curves::Uncorrelated","0x0163df34fccbf003ce219d3f1d9e70d140b60622cb9dd47599c25fb2f797ba6e::curves::Uncorrelated","0x54cb0bb2c18564b86e34539b9f89cfe1186e39d89fce54e1cd007b8e61673a85::bin_steps::X80","0x80273859084bc47f92a6c2d3e9257ebb2349668a1b0fb3db1d759a04c7628855::router::BinStepV0V05","0x80273859084bc47f92a6c2d3e9257ebb2349668a1b0fb3db1d759a04c7628855::router::BinStepV0V05"]
}
let result2 = await provider.signAndSubmitTransaction(transactionData, "movement:testnet")

断开钱包连接#

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

okxUniversalConnectUI.disconnect()

Event事件#

// 生成 universalLink
okxUniversalConnectUI.on("display_uri", (uri) => {
  console.log(uri);
});
// session 信息变更会触发该事件；
okxUniversalConnectUI.on("session_update", (session) => {
  console.log(JSON.stringify(session));
});
// 断开连接会触发该事件；
okxUniversalConnectUI.on("session_delete", ({topic}) => {
  console.log(topic);
});
// 连接并签名时,签名结果会触发该事件;
okxUniversalConnectUI.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
}
目錄