@okxweb3/marketplace-runes NPM

@okxweb3/marketplace-runes

@okxweb3/marketplace-runes is an SDK designed for Runes trading. It provides a comprehensive set of tools and interfaces to facilitate interaction with the OKX Runes marketplace.

Installation

Install the SDK using npm:

npm i @okxweb3/marketplace-runes

Usage

Initialization

import OkxRunesSDK from @okxweb3/marketplace-runes and new it. Pass in the required parameters as well.

To generate the necessary parameters, please refer to the OKX Developer Management Platform. Here's a usage example:

import { OkxRunesSDK, ADDRESS_TYPE } from '@okxweb3/marketplace-runes'

const sdk = new OkxRunesSDK({
    privateKey: '',  // Your wallet private key for signing transactions
    apikey: '',      // API Key obtained from your application
    secretKey: '',   // Secret Key obtained from your application
    passphrase: '',  // Passphrase created during key application
    addressType: ADDRESS_TYPE.SEGWIT_TAPROOT,  // Wallet address type for buying runes
    projectId: '',   // Project ID created during project application
    requestBaseUrl: '' // okx other website eg: https://www.ouyicn.com/, default is http://www.okx.com/
})

Parameter Details:

Field Name	Type	Required	Description
apikey	String	Yes	API Key from your application. See how to generate it here.
secretKey	String	Yes	Secret Key from your application. See how to generate it here.
passphrase	String	Yes	Passphrase created during key application. See how to generate it here.
projectId	String	Yes	Project ID created during project application. See how to generate it here.
privateKey	String	Yes	Your wallet private key used for signing transactions.
addressType	String	Yes	Wallet address type for buying runes.You can import `ADDRESS_TYPE` from `@okxweb3/marketplace-runes` and use it.
requestBaseUrl	String	NO	The domain name used to request the api.okx other website eg: https://www.ouyicn.com/, default is http://www.okx.com/

Buying Runes

The SDK supports automatic assembly of purchase transactions, allowing you to obtain the transaction hash (txHash) and network fee. Here's how you can use it:

const buyRunes = async () => {
  const { txHash, networkFee } = await sdk.buy({
     orderIds: [orderId1, orderId2],  // OKX Runes order IDs, you can get orderId by sdk.api.getOrders()
     paymentUtxos: [{                 // UTXOs for transaction assembly
       "txid": "ca79143aea5e22f6cfe8d57c5af6be39fecc7afd5ee931a2060f3fef8754ee15",
       "vout": 3,
       "value": 175136,
     }],
     networkFeeRate: 5,  // Desired network fee rate
   });
}
await buyRunes();

Parameter Details:

Field Name	Type	Required	Description
orderIds	Array	Yes	Runes order id list
paymentUtxos	Array	Yes	UTXOs used to assemble the purchase transaction. Ensure they contain no other assets and that the total amount covers the order and network fees.You can get your address utxo from here
networkFeeRate	Number	Yes	The desired network fee rate.

sell runes

Sell runes assets to the OKX marketplace. The detailed response interface can be found in Runes API. Here's demo:

const requestApi = async () => {
  const { result } = await sdk.sell({
    assets: [{
        utxoTxHash: 'ce302f5c946ff3ef502eade58405d64b545d59de9fcd731314b88ddadf709ca6',
        utxoValue: 546,
        utxoVout: 0, 
        unitPrice: 1000000,
        amount: 100
    }],
    runesId: '840000:3'
  })

// data structure demo

// {
//    "result": [
//       {
//          "utxo": "txHash:vout", 
//           "orderId": 123,    // orderid
//           "errMsg": "xxxxx"   // if errMsg，sell fail
//        }
//     ]
// }

}
await requestApi();

Parameter Details:

Field Name	Type	Required	Description
runesId	String	Yes	Unique identifier for the Runes token
utxoVout	number	Yes	runes assets utxo location vout
utxoTxHash	String	Yes	runes assets utxo location
utxoValue	number	Yes	runes assets utxo value, unit: sats
unitPrice	number	Yes	runes assets unit price, unit: sats
amount	String	Yes	runes assets amount
makerFee	number	No	MakerFee charged by a pending source If a makerFee is charged, the totalPrice shall include the makerFee, unit: BTC

Cancel Runes Orders

The SDK supports automatic assembly of off-shelf transactions, allowing multiple orders to be canceled at the same time. Here's how you can use it:

await sdk.cancelSell({
  orderIds: [orderId1, orderId2],  // OKX Runes order IDs, you can get orderId by sdk.api.getOrders()
});

Parameter Details:

Field Name	Type	Required	Description
orderIds	Array	Yes	Runes order id list

API

The SDK provides several APIs to query transaction-related information. For detailed parameter usage, please refer to the Runes API.

getOrders

Retrieve orders from the OKX marketplace using this API. The detailed response interface can be found in Runes API. Here's demo:

import { ORDERS_SORT_RULES } from '@okxweb3/marketplace-runes'

const requestApi = async () => {
  const data = await sdk.api.getOrders({
    runesId: '840000:3',  // Desired Runes ID
    sortBy: ORDERS_SORT_RULES.UNIT_PRICE_ASC  // Sorting rule
  });

  // data structure demo, you can get orderId

  // {
  //     "cursor": "1",
  //     "items": [
  //         {
  //           "amount": "889806",
  //           "orderId": 201268,
  //           "ticker": "DOG•GO•TO•THE•MOON",
  //           "tickerId": "840000:3",
  //           "totalPrice": {
  //               "price": "0.05472306",
  //               "satPrice": "5472306",
  //           },
  //           "unitPrice": {
  //               "price": "0.0000000615",
  //               "satPrice": "6.15",
  //           },
  //         }
  //     ]
  //   }

}
await requestApi();

Parameter Details:

Field Name	Type	Required	Description
runesId	String	Yes	Unique identifier for the Runes token
cursor	String	No	Cursor for retrieving order sequence numbers (max 1000)
limit	Number	No	Page size, default 10, max 100. Specifies the maximum number of orders returned.
sortBy	String	No	Sorting rule, default is ascending by unit price.Options include: unitPriceAsc, unitPriceDesc, totalPriceAsc, totalPriceDesc, listedTimeAsc, listedTimeDesc. You can import`ORDERS_SORT_RULES` from `@okxweb3/marketplace-runes` and use it.

getSellersPsbt

Use this API to obtain seller PSBTs for OKX marketplace orders. Note that the PSBTs do not include the seller's signature. The detailed response interface can be found in Runes API. Here's demo:

const requestApi = async () => {
  // you can get orderId by sdk.api.getOrders()
  const data = await sdk.api.getSellersPsbt([orderId1, orderId2]);

  // data structure demo, you can get seller PSBT from sellerPSBT

  // {
  //   "orderInfos":[
  //     {
  //       "orderId": 11111,
  //       "sellerPSBT": "cHNidP8BAPW+W04EtAAAAAA="，
  //       "orderSource": 34,   //34 - OKX  82-Xverse
  //       "makerFeeAddress": "feeAddress", //platform makerFee address
  //       "makerFee": "0.003", // 0.003 BTC
  //       "takerFeeAddress": "feeAddress", //platform takerFee address
  //       "takerFee": "0.003", // 0.003 BTC
  //     }
  //   ],
  // }

}
await requestApi();

Parameter Details:

Field Name	Type	Required	Description
orderIds	Array	Yes	Order IDs

sendTransations

Broadcast Runes purchase transactions with this API to obtain the transaction hash (txHash). The detailed response interface can be found in Runes API. Here's demo:

const requestApi = async () => {
  const data = await sdk.api.sendTransations({ 
    buyerPSBT: psbt, 
    fromAddress: address, 
    orderIds 
  });
  // data structure demo, you can get buy transation txHash

  // {
  //   "txHash": "1",
  // }
}
await requestApi();

Parameter Details:

Field Name	Type	Required	Description
fromAddress	String	Yes	Buyer's payment address
orderIds	Array	Yes	IDs of the orders to purchase
buyerPSBT	String	Yes	Signed buyer PSBT, must be in base64 format, and assembled according to the specified transaction structure

getOwnedAsserts

Get the runes assets from the OKX marketplace using this API. The detailed response interface can be found in Runes API. Here's demo:

const requestApi = async () => {
  const data = await sdk.api.getOwnedAsserts({
    runesId: '840000:3',  // Desired Runes ID
  });

  // data structure demo

  // {
  //   "cursor": "1",
  //   "items": [
  //     {
  //       "amount": "500000",
  //       "assetId": "28912795273673038",
  //       "chain": 0,
  //       "confirmations": null,
  //       "inscriptionNum": "",
  //       "listTime": 1714399069,
  //       "name": "DOG•GO•TO•THE•MOON",
  //       "orderId": 201296,
  //       "ownerAddress": "bc1p3fj806enwnmz04444mpm42ykgdcta9p5mvzx46hp8wmg2knpwxpq0k46x9",
  //       "status": 1,
  //       "symbol": "🐕",
  //       "ticker": "DOG•GO•TO•THE•MOON",
  //       "tickerIcon": "https://static.coinall.ltd/cdn/web3/currency/token/1714125941761.png/type=png_350_0",
  //       "tickerId": "840000:3",
  //       "tickerType": 4,
  //       "totalPrice": {
  //       "currency": "BTC",
  //       "currencyUrl": "https://static.coinall.ltd/cdn/nft/4834651a-7c4e-4249-91c1-cf680af39dc0.png",
  //       "price": "0.031895",
  //       "satPrice": "3189500",
  //       "usdPrice": "1979.7003235"
  //     },
  //       "txHash": "",
  //       "unavailable": null,
  //       "unitPrice": {
  //       "currency": "BTC",
  //       "currencyUrl": "https://static.coinall.ltd/cdn/nft/4834651a-7c4e-4249-91c1-cf680af39dc0.png",
  //       "price": "0.00000006379",
  //       "satPrice": "6.379",
  //       "usdPrice": "0.003959400647"
  //     },
  //       "utxoTxHash": "ce302f5c946ff3ef502eade58405d64b545d59de9fcd731314b88ddadf709ca6",
  //       "utxoValue": "546",
  //       "utxoVout": 2
  //     }
  //   ]
  // }

}
await requestApi();

Parameter Details:

Field Name	Type	Required	Description
runesId	String	Yes	Unique identifier for the Runes token

sellRunes

Sell runes assets to the OKX marketplace using this API. The detailed response interface can be found in Runes API. Here's demo:

const requestApi = async () => {
  const { result } = await sdk.api.sellRunes({
    items: [{
        utxo: 'ce302f5c946ff3ef502eade58405d64b545d59de9fcd731314b88ddadf709ca6:0',
        totalPrice: 0.1,
        psbt: 'cHNidP8BALICAAAAAgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD/////uiAcc6RHA+aers8xRS3pcg6QslcZrjUYkUDOf0F0aJAAAAAAAP////8CAAAAAAAAAAAiUSDBJU2tQKrqEh5T4M7AmYY2L2zUIieW0ZSMlHkbNSgctbi5ZQAAAAAAIlEgOalwW0bhaMYRYpVC76AtqEx3l3po000r2GHSSfEYIhIAAAAAAAEBKwAAAAAAAAAAIlEgwSVNrUCq6hIeU+DOwJmGNi9s1CInltGUjJR5GzUoHLUBAwQBAAAAARcgYW4nMjhA7gwq5DTZmCZ/gRcJiLqUd/eNzQD8JHon20AAAQErSgEAAAAAAAAiUSA5qXBbRuFoxhFilULvoC2oTHeXemjTTSvYYdJJ8RgiEgEDBIMAAAABE0Hc/KUEmP4rXEeBdm7pJk2MtthYBFWG5TuVYI0Vcg85JshzH5hTxhJCsJBYI12FgMSDw7MSzBxIaZ4IEPI8qCj+gwEXIOHNunNxyMsNjrfkS7IpiwDSn9zL1jV8kgNEu4MLntyoAAABBSDhzbpzccjLDY635EuyKYsA0p/cy9Y1fJIDRLuDC57cqAA=';
        unitPrice: 1000000
    }],
    runesId: '840000:3',
    walletAddress: 'bc1p3fj806enwnmz04444mpm42ykgdcta9p5mvzx46hp8wmg2knpwxpq0k46x9'
  })

  // data structure demo

// {
//    "result": [
//       {
//          "utxo": "txHash:vout", 
//           "orderId": 123,    // orderid
//           "errMsg": "xxxxx"   // if errMsg，sell fail
//        }
//     ]
// }

}
await requestApi();

Parameter Details:

Field Name	Type	Required	Description
runesId	String	Yes	Unique identifier for the Runes token
walletAddress	String	Yes	wallet address
utxo	String	Yes	runes assets utxo location
totalPrice	number	Yes	runes assets total price, unit: BTC
unitPrice	number	Yes	runes assets unit price, unit: sats
psbt	String	Yes	runes assets sell psbt
makerFee	number	No	MakerFee charged by a pending source If a makerFee is charged, the totalPrice shall include the makerFee, unit: BTC

Middleware

Middleware allows you to access wallet addresses derived from the private key and public key for transaction assembly. It also provides pre-purchase parameters and post-purchase results, enabling actions throughout the purchase lifecycle.

import { OkxRunesSDK } from '@okxweb3/marketplace-runes'

const sdk = new OkxRunesSDK()

// Register middleware
sdk.use(async (ctx, next) => {
  console.log(`Calling ${ctx.type} with params: `, ctx)
  await next()
  console.log(`Result of ${ctx.type}: `, ctx)
})

OKX runes SDK marketplace bitcoin nft node typescript javascript

@okxweb3/coin-bitcoin @okxweb3/marketplace-core @okxweb3/marketplace-library @okxweb3/marketplace-onchain @scure/base @scure/btc-signer crypto

9 months ago

11 months ago

11 months ago

11 months ago