Wallet API

搭建铭文钱包

搭建铭文钱包#

Wallet API 已支持主流 BRC-20、Runes、ARC-20 和 SRC-20 、Ordinals_NFT 五种热门的铭文资产。

请确保已完成了准备工作，接着可直接通过此案例，熟悉铭文数据的查询、铭文交易的构建和广播。

第一步：生成钱包助记词及地址#

你可以使用我们提供的签名 SDK 创建钱包助记词及地址。

npm install#

首先需要安装到最新的签名 SDK 版本，以 BTC 网络为例：

npm install @okxweb3/crypto-lib
npm install @okxweb3/coin-base
npm install @okxweb3/coin-bitcoin

本地构建#

下载项目源码

git clone https://github.com/okx/js-wallet-sdk.git

运行构建脚本

sh build.sh

以 BTC 网络为例，可以依照下述代码，使用签名 SDK 创建一个 BTC 钱包对象，并且推导出所对应地址。

import { BtcWallet,MessageTypes} from "@okxweb3/coin-bitcoin";
// btc wallet
let wallet = new BtcWallet()

// get mnemonic
let mnemonic = await getMnemonic(128);
let param = {
  mnemonic: mnemonic,
  hdPath: "m/44'/0'/0'/0/0"
};
// get derived key
let privateKey = await wallet.getDerivedPrivateKey(param);


// get new address
import { BtcWallet } from "@okxweb3/coin-bitcoin";

let wallet = new BtcWallet()

// legacy address
let params: NewAddressParams = {
  privateKey: "L22jGDH5pKE4WHb2m9r2MdiWTtGarDhTYRqMrntsjD5uCq5z9ahY"
};
let address = await wallet.getNewAddress(params);

// native segwit address
let params2: NewAddressParams = {
  privateKey: "L22jGDH5pKE4WHb2m9r2MdiWTtGarDhTYRqMrntsjD5uCq5z9ahY",
  addressType: "segwit_native",
};
let address2 = await wallet.getNewAddress(params2);

// nested segwit address
let params3: NewAddressParams = {
  privateKey: "L22jGDH5pKE4WHb2m9r2MdiWTtGarDhTYRqMrntsjD5uCq5z9ahY",
  addressType: "segwit_nested",
};
let address3 = await wallet.getNewAddress(params3);

// taproot segwit address
let params4: NewAddressParams = {
  privateKey: "L22jGDH5pKE4WHb2m9r2MdiWTtGarDhTYRqMrntsjD5uCq5z9ahY",
  addressType: "segwit_taproot",
};
let address4 = await wallet.getNewAddress(params4);

// get the public key
let publicKey = newAddress.publicKey;
console.log("the corresponding public key:", publicKey);

演示程序#

我们准备了一个开源演示程序，用于展示我们上述涉及到签名 SDK 的功能。获取演示程序源码点击这里。

第二步：创建账户#

你在上一步，已经生成了助记词和地址。现在你可以创建账户 (AccountId) 来聚合多个地址，进行批量查询代币余额和交易历史。

说明

通常情况，Web3 钱包有三个概念：

- 钱包，谁拥有助记词，谁就拥有钱包。
- 账户，基于 BIP-44 规范，一套助记词下可以派生多个账户。
- 地址，每个账户下的每个链，对应一个地址。

调用接口来创建钱包账户。

例如，创建一个支持不同地址类型的 BTC 钱包账户：

//定义你的参数
const addresses = [
    {
        "chainIndex":"0",
        "address":"bc1peqgjr3cwl09mmsh6kvjsvv3ffu4waha00x7xrqrt85wt3zgdwphs72ctnu",
    },
    {
        "chainIndex":"0",
        "address":"18u8nvU5rx1drgwiT4M9sGTD9JX8r53KM9",
    }
];

const getCreateAccountBody = {
    addresses: addresses,
    signMessage: '1717062864123', // UNIX Timestamp in millisecond
};

//定义辅助函数
const getCreateAccountData = async () => {
    const apiRequestUrl = getRequestUrl(
      apiBaseUrl,
      '/api/v5/wallet/account/create-wallet-account'
    );
    return fetch(apiRequestUrl, {
      method: 'post',
      headers: headersParams,
      body: JSON.stringify(getCreateAccountBody),
    })
      .then((res) => res.json())
      .then((res) => {
        return res;
    });
};

const { data: createAccountData } = await getCreateAccountData();

第三步：构建并发送铭文交易#

获取签名所需信息#

首先，调用 POST /api/v5/wallet/pre-transaction/sign-info 接口，查询签名所需要的一些数据，例如 BTC 链的费率、铭文大小输出等。

//定义你的参数
// BTC
const postSignInfoBody = {
    chainIndex: '0',
    fromAddr: 'bc1psnr548clz3f4fz6jmpnw5eqzj2v2musk082wp8fvq5ac3p5ete6qg05u8u',
    toAddr: 'bc1psnr548clz3f4fz6jmpnw5eqzj2v2musk082wp8fvq5ac3p5ete6qg05u8u',
    txAmount: '0',
    extJson: {
    }
};

//定义辅助函数
const signInfoData = async () => {
    const apiRequestUrl = getRequestUrl(
        apiBaseUrl,
        '/api/v5/wallet/pre-transaction/sign-info'
    );
    return fetch(apiRequestUrl, {
         method: 'post',
         headers: headersParams,
         body: JSON.stringify(postSignInfoBody),
    })
    .then((res) => res.json())
    .then((res) => {
        return res;
    });
  };

const { data: signInfoData } = await signInfoData();

当查询到相关信息后，你将收到如下的响应：

{
    "code": "0",
    "msg": "success",
    "data": [
        {
            "normalFeeRate": "5",
            "maxFeeRate": "5",
            "minFeeRate": "5",
            "inscriptionOutput": "546",
            "minOutput": "546",
            "normalCost": "1800",
            "maxCost": "3600",
            "minCost": "600"
        }
    ]
}

获取全量 UTXO#

调用 GET /api/v5/wallet/utxo/utxo 接口，查询当前地址下所有可用的 UTXO

//定义你的参数
// BTC
const postSignInfoBody = {
    chainIndex: '0',
    fromAddr: 'bc1psnr548clz3f4fz6jmpnw5eqzj2v2musk082wp8fvq5ac3p5ete6qg05u8u',
    toAddr: 'bc1psnr548clz3f4fz6jmpnw5eqzj2v2musk082wp8fvq5ac3p5ete6qg05u8u',
    txAmount: '0',
    extJson: {
    }
};

//定义辅助函数
const signInfoData = async () => {
    const apiRequestUrl = getRequestUrl(
        apiBaseUrl,
        '/api/v5/wallet/pre-transaction/sign-info'
    );
    return fetch(apiRequestUrl, {
         method: 'get',
         headers: headersParams,
         body: JSON.stringify(postSignInfoBody),
    })
    .then((res) => res.json())
    .then((res) => {
        return res;
    });
  };

const { data: signInfoData } = await signInfoData();

获取 UTXO 上铭文资产详情#

调用 POST /api/v5/wallet/utxo/utxo-detail 接口，查询 UTXO 上的铭文详情。

//定义你的参数
// BTC
const postSignInfoBody = {
    chainIndex: '0',
    fromAddr: 'bc1psnr548clz3f4fz6jmpnw5eqzj2v2musk082wp8fvq5ac3p5ete6qg05u8u',
    toAddr: 'bc1psnr548clz3f4fz6jmpnw5eqzj2v2musk082wp8fvq5ac3p5ete6qg05u8u',
    txAmount: '0',
    extJson: {
    }
};

//定义辅助函数
const signInfoData = async () => {
    const apiRequestUrl = getRequestUrl(
        apiBaseUrl,
        '/api/v5/wallet/pre-transaction/sign-info'
    );
    return fetch(apiRequestUrl, {
         method: 'post',
         headers: headersParams,
         body: JSON.stringify(postSignInfoBody),
    })
    .then((res) => res.json())
    .then((res) => {
        return res;
    });
  };

const { data: signInfoData } = await signInfoData();

验证地址构建交易#

使用签名 SDK 先验证地址合法性再构建交易

// Verify address
let valid = await wallet.validAddress({
    address: newAddress.address
});
console.log("verify address isValid:", valid.isValid);

// Sign a transaction
let signParams = {
    privateKey: derivePrivateKey,
    data: {
        to: newAddress.address,
        value: new BigNumber(0),
        nonce: 5,
        gasPrice: new BigNumber(100 * 1000000000),
        gasLimit: new BigNumber(21000),
        chainId: 42
    }
};

let signedTx = await wallet.signTransaction(signParams);
console.log("signed tx:", signedTx);

广播交易#

调用接口，交易广播到链上。

//定义你的参数
const postSendTransactionBody = {
    signedTx: "02000000000101a92808fb32063058e3c752ad2c4a0a6f8957e858dd01483ccff504d4f5ca791d0500000000fdffffff02c405000000000000225120728b5d2f0cf833264adac833e997931155b4aec3020bc87c32fa91509bb2abe61f71080000000000225120f0513064fe1e5b5c31bedff43b943f2f1211d14ab2891687241b138d214888e30140393a287212d5c7341a5d44ba2409dda5db95a854e500475ec8bf2ea0f7f63d35c849102c0f906f48d1833f3b5b7a7ca726e14fc2d715b4cbbecb8488e028baab00000000"
    accountId:"c79e7775-9e78-4a2d-b27f-9021f3bf5fca",
    address: "bc1p7pgnqe87red4cvd7ml6rh9pl9ufpr522k2y3dpeyrvfc6g2g3r3s3ae9dr",
};

//定义辅助函数
const sendTransactionData = async () => {
    const apiRequestUrl = getRequestUrl(
        apiBaseUrl,
        'api/v5/wallet/pre-transaction/broadcast-transaction'
    );
    return fetch(apiRequestUrl, {
        method: 'post',
        headers: headersParams,
        body: JSON.stringify(postSendTransactionBody),
    })
    .then((res) => res.json())
    .then((res) => {
        return res;
    });
  };

const { data: sendTransactionData } = await sendTransactionData();

广播后，你将收到如下的响应：

{
    "code": 0,
    "msg": "success",
    "data": [{
        "orderId": "469356614923743232"
    }]
}

说明

点击查看 orderId 的定义

第五步：查询铭文交易详情#

当发送交易后，使用 GET /api/v5/wallet/post-transaction/inscription-transaction-detail-by-txhash 接口并通过 txhash 来获取铭文交易详情信息。

//定义你的参数
const params = {
    accountId: '13886e05-1265-4b79-8ac3-b7ab46211001',
    orderId: '469356614923743232',
    chainIndex: '1'
  };

//定义辅助函数
const getTransactionDetailData = async () => {
    const apiRequestUrl = getRequestUrl(
        apiBaseUrl,
        '/api/v5/wallet/post-transaction/transaction-detail-by-ordid',
        params
    );
    return fetch(apiRequestUrl, {
        method: 'get',
        headers: headersParams,
    })
    .then((res) => res.json())
    .then((res) => {
        return res;
    });
  };

const { data: transactionDetailData } = await getTransactionDetailData();

查询详情成功后，你将收到如下的响应：

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "chainIndex": "1",
            "orderId": "469356614923743232",
            "txhash": "0xcbf411766d65f3cf92839ababa73c4afec69a83442e8b67a68b5104b50a04ejb",
            "blockHash" : "0x3ee63382b883fc40e35da6023fb341dd01cd2ec011f992bb54cf312f517740c9",
            "blockHeight" : "19235519",
            "blockTime" : "1708026551000",
            "feeUsdValue" : "138.846919",
            "fees" : "49102595635945621",
            "gasLimit" : "2000000",
            "gasPrice" : "87504603347",
            "gasUsed" : "561143",
            "txType": "0",  
            "txTime": "0", 
            "txStatus": "0",
            "txDetail": [
                {
                    "iType" : "0",  
                    "txAmount": "0",
                    "tokenAddress":""
                    "contractCall" : true,
                    "fromAddr" : "0x3ee63382b883fc40e35da6023fb341dd01cd2ec011f992bb54cf312f517740c9",
                    "toAddr" : "0x3ee63382b883fc40e35da6023fb341dd01cd2ec011f992bb54cf312f517740c9",
                    "logIndex" : "-1",
                    "status" : "SUCCESS"
                }
            ]
        }
    ]
}

此外，你还可以通过订阅 Webhook，实时准确地了解交易发送后的状态，查看详情。

到这里，你基本上已经实现了开发一款铭文钱包所需的部分基础功能。

此外，Wallet API 提供了丰富接口，全方位满足 Web3 钱包开发者的需求，具体请查看下方其他章节。