Quick start#

In this guide, we will show you how to create an ordinals listing on OKX. Note: Doing the steps below at a lower price point will lower the current listing price to the new request. This process includes:

Get valid inscription data
Get UTXO information
Get the PSBT signed
Submit ordinals listing

1. Make request to get valid inscription data#

First you need to get the available Bitcoin NFT/inscription in order to create a listing on OKX platform. Refer to Retrieve valid inscriptions for more details.

Step 1: Create header

const apiBaseUrl = 'https://www.okx.com';
const requestUrl = '/api/v5/mktplace/nft/ordinals/get-valid-inscriptions'; //
const originalMessage = JSON.stringify({
    slug: 'BTC Ordinals',
    walletAddress: 'bc1qek7lal8ghnmus3dw897atlpgvmv27zgdgqfawx',
    limit: '10',
    isBrc20: false // true for brc20 tokens.  Note: Default value is true if not included
});

const apiRequestUrl = getRequestUrl(apiBaseUrl, requestUrl);

const headersParams = {
  'Content-Type': 'application/json',
  'OK-ACCESS-KEY': apiKey,
  'OK-ACCESS-SIGN': cryptoJS.enc.Base64.stringify(
    cryptoJS.HmacSHA256(timestamp + 'POST' + '/api/v5/mktplace/nft/ordinals/get-valid-inscriptions' + originalMessage , secretKey)
  ),
  'OK-ACCESS-TIMESTAMP': timestamp,
  'OK-ACCESS-PASSPHRASE': passphrase,
};

Step 2: Make the request

return fetch(apiRequestUrl, {method: 'post', headers: headersParams, body: originalMessage})
    .then((res) => {
        console.log(res)
        return res.json()
    }
).then((res) => {
    console.log(JSON.stringify(res))
    return res;
});

{
    "code": 0,
    "data": {
        "cursor": "MTY5MDQ1NzA3NTE2OToxNj...FwOW5wa3Z3Z2xjbWo4dGg0cXF6amVxbGtweXVxbGp3Y3AyMDh4MzM3ZmV4cDI2cDBteHA4cXQ4MjB4ZA==",
        "inscriptionInfos": [
            {
                "amount": "1",
                "inscriptionId": "08ea6e794016c8f11dd...f85222561c15ba29a6f54d3c75fd184a9i0",
                "nftId": "16514...22585458",
                "ticker": "",
                "tickerId": ""
            },
            {
                "amount": "1",
                "inscriptionId": "0c3020593597d1f5818...cf23cbcb91d9b7fb8e3e0cefa0b2dfi0",
                "nftId": "2105134...1490",
                "ticker": "",
                "tickerId": ""
            }
        ]
    },
    "msg": ""
}

2. Get UTXO information#

In order to get PSBT of the transaction, it would need to match UTXO. Therefore, it is necessary to get UTXO of the inscription. You would need inscriptionId at this stage. Refer to query UTXO for more details.

Step 1: Create a new header and body to retrieve UTXO information

const apiBaseUrl = 'https://www.okx.com';
const requestUrl = '/api/v5/waas/transaction/get-utxo'; // this endpoint is to get UTXO information of the inscription
const utxoRequestBody = JSON.stringify({
    chainId:0,
    utxoRequests: [
        {
            address: "bc1p9npkvwglc...ljwcp208x337fexp26p0mxp8qt820xd", // the wallet that holds the inscription
            coinAmount: 0,  // use default value 0
            serviceCharge: 0, // use default value 0
            utxoType: 2, // default type 2 for utxo inscription check
            nftId: "1803359c...cfeb15d1aa6ade40i0" // this is inscription ID
        }
    ]
})
const apiRequestUrl = getRequestUrl(apiBaseUrl, requestUrl);

const headersParams = {
  'Content-Type': 'application/json',
  'OK-ACCESS-KEY': apiKey,
  'OK-ACCESS-SIGN': cryptoJS.enc.Base64.stringify(
    cryptoJS.HmacSHA256(timestamp + 'POST' + requestUrl + utxoRequestBody , secretKey)
  ),
  'OK-ACCESS-TIMESTAMP': timestamp,
  'OK-ACCESS-PASSPHRASE': passphrase,
};

Step 2: Collect UTXO information

return fetch(apiRequestUrl, {method: 'post', headers: headersParams, body: utxoRequestBody})
    .then((res) => {
        console.log(res)
        return res.json()
    }
).then((res) => {
    console.log(JSON.stringify(res))
    return res;
});

Then you will get the below UTXO information

{
    "address": "bc1pt5w9...2m8cky8qxjn3rg",
    "canTransferAmount": "0",
    "utxoType": 2,
    "totalUtxoNum": 0,
    "utxoList": [
        {
            "txHash": "02ecbe7ef51...87a7c6e64409883f66f4e3036",
            "vout": 0,
            "coinAmount": 546,
            "confirmations": 3548,
            "utxoType": 2,
            "status": 1,
            "utxoBizStatus": 0,
            "hasNft": true,
            "hasCheckNftExist": true,
            "nftLocaltionVOs": [
                {
                    "nftId": "02ecbe7ef5143...3f3de87a7c6e64409883f66f4e3036i0",  // this is inscriptionId
                    "nftLocation": "02ecbe7ef51431...fccb83f3de87a7c6e64409883f66f4e3036:0:0",
                    "nftType": 2,
                    "brc20Nft": true
                }
            ],
            "key": "02ecbe7ef514311523d0e7f...3f3de87a7c6e64409883f66f4e3036-0",
            "dummy": false,
            "spending": false
        }
    ]
}

3. Get PSBT information#

Next, we need to set the listing price and get PSBT with the listing price. Refer to wallet SDK for more details.

NOTE

For lowering listing price - If the price is higher than current listing price, it will throw exception. For both lowering listing price and new listing - Exception will be thrown if the total amount is below 0.00001 BTC.

Step 1: Create a message for PSBT data

import { generateSignedListingPsbt, networks } from '@okxweb3/coin-bitcoin';
const listingData = {
  nftAddress: 'bc1pt5w9...2m8cky8qxjn3rg',
  nftUtxo: {
    txHash: '02ecbe7ef51...87a7c6e64409883f66f4e3036',
    vout: 0,
    coinAmount: 546,
    rawTransaction: undefined
  },
  receiveBtcAddress: 'bc1p9npkvwglcmj8th4q...cp208x337fexp26p0mxp8qt820xd', // your btc wallet address
  price: 10000 // total price in Satoshi unit
}

Step 2: Using OKT wallet SDK will allow us to get psbt data

const psbt = generateSignedListingPsbt(listingData, privateKey, networks.bitcoin);
console.log(psbt);

4. Submit ordinals listing to OKX platform#

With the PSBT signature and pricing information set this to the end point and you will be able to list the ordinals to OKX.

Step 1: Create setup new endpoint information and create header information for submit listing

NOTE

unitPrice will vary for BRC-20 or BTC NFT. For BTC NFT it will be the same as totalPrice since BTC NFT amount is 1, but for BRC-20, the unitPrice will be totalPrice divided by the number of shares given. For example, totalPrice is 10000 sats and the number of inscriptions is 50, then the unitPrice would be 10000/50 = 200.

const apiBaseUrl = 'https://www.okx.com';
const requestUrl = '/api/v5/mktplace/nft/ordinals/okx/make-orders'; // this endpoint is to get UTXO information of the inscription
const submitListingBody = JSON.stringify({
    brc20: false,
    items: [
      {
        inscriptionId: inscriptionId,
        nftId: nftId, // get this data part 1 step 2 by mapping it to inscriptionId
        orderType: 2,
        totalPrice: 100000,  // this price should match part 3 step 1
        unitPrice: 100000, // this price will varies for BRC20 or btc NFT.  Check out NOTE on unitPrice
        psbt: 'cHNidP8BAP0GAQIAAAADAAAAAAAA...ZUDTZKgR6mGJSkBSJuPsgb2gGCekW+W04EtAAAAAA=',
      }
    ],
    tickerId: ''
  })
const apiRequestUrl = getRequestUrl(apiBaseUrl, requestUrl);

const headersParams = {
  'Content-Type': 'application/json',
  'OK-ACCESS-KEY': apiKey,
  'OK-ACCESS-SIGN': cryptoJS.enc.Base64.stringify(
    cryptoJS.HmacSHA256(timestamp + 'POST' + requestUrl + submitListingBody , secretKey)
  ),
  'OK-ACCESS-TIMESTAMP': timestamp,
  'OK-ACCESS-PASSPHRASE': passphrase,
};

Step 2: Request to submit listing

return fetch(apiRequestUrl, {method: 'post', headers: headersParams, body: submitListingBody})
    .then((res) => {
        console.log(res)
        return res.json()
    }
).then((res) => {
    console.log(JSON.stringify(res))
    return res;
});

At the end you will get success message as shown below.

{
    "result": [
        {
            "nftID": 20824...473273458,  // should be the same nftId as part 4 step 1
            "errorMsg": "",
            "success": true,
        }
    ]
}

Marketplace API

Ordinals API

Marketplace API

Create listing to OKX

Table of contents

1. Make request to get valid inscription data

2. Get UTXO information

3. Get PSBT information

4. Submit ordinals listing to OKX platform