Search Inscriptions

Search millions of inscriptions for any text. Check if a hash of any data has been inscribed before.

As of January 2024, access to search endpoints are restricted to API Keys and allowlisted domains, if you need access to these endpoints please reach out to us on discord.

All results are as sorted earliest first by inscription numbers, so they can be used to check which inscription is first for a certain hash.

Search all inscriptions for any text value

Text Search

GET https://api.ordinalsbot.com/search

You can search for any text string against all existing inscriptions.

Pagination options can be specified by adding itemsPerPage and page values in the query parameters. Response provides an array of results as well as information on current page, total page numbers and total items available for the search criteria. Response structure:

{ results: [{},{},{},{}], // array of restults count: 0, // number of Ordinals in the current results array currentPage: page, // current page number totalPages: 0, // total pages that can be returned for the current search criteria totalItems: 0 // total items in the database for the current search criteria }

Query Parameters

Name	Type	Description
text*	String	The text you want to search
page	Number	The page number in the list of pages to return by default the first page is returned
itemsPerPage	Number	The number of iterms to return in each page, this defaults to 100

Headers

Name	Type	Description
x-api-key	String	API Key Required if domain is not on allowlist.

200: OK Normal Response

{
    "status":"ok",
    "count": 1,
    "currentPage": 3,
    "totalPages": 3,
    "totalItems": 102
    "itemsPerPage": 100,
    "results":
   [
      {
         "txid":"87a1d452d2dcc89c66018a897c9910629d6c3173820979a740730e195433fd26",
         "inputindex":"0",
         "inscriptionid":"87a1d452d2dcc89c66018a897c9910629d6c3173820979a740730e195433fd26i0",
         "inscriptionnumber":"181258",
         "blockheight":"778281",
         "contentstr":"{\"p\":\"sns\",\"op\":\"reg\",\"name\":\"ordinalsbot.sats\"}",
         "contenttypestr":"text/plain;charset=utf-8",
         "contenthash":"c987a51dc14fb8e9e909b8482c1c62df246904442e851f41d6891e7af3042b23",
         "contentlength":"30",
         "createdat":"2023-03-08T21:05:16.349Z"
      }
   ]
}

200: OK Response with Error

{
    status: 'error', 
    error: 'error reason'
}

500: Internal Server Error Server side error

{
    status: 'error',
    reason: 'server error'
}

Search for an existing Image or File

Use this endpoint to check if a certain image was inscribed before. We call this a "hash check".

Image Search is done by hashing the image file and checking against previous inscriptions' hashes.

To use this endpoint you need to sha256 hash the image file content as below:

const base64encodedimage = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAoElEQVR42u2VMQ6AMAhFe0fT1d3V3cv0ojUxaoBSBEo3Sf7S6n+UIqb0R2BUoHjjnPOrSBAyphqFiOajEJW5F9KrdyMvBL10lK0r+qwJ8GVOIVoAm/26L5eg8bNmPQWbfb1rzq3B+3ADaPZwzQJoukZ7B1qICkD3wgHTTzAVwO1ZOwlBep3DQc1tqimR1Vz8FqSB55qmEmD0fyACmBEuxglnHBu4i1egeQAAAABJRU5ErkJggg=='
const buff = Buffer.from(base64encodedimage.split(";base64,")[1], 'base64');
const imageHash = bitcoin.crypto.sha256(buff).toString('hex')

Search for Image

GET https://api.ordinalsbot.com/search

Check for previous occurrences of an image in inscriptions. Results array will be sorted by ascending block height. Pagination parameters are the same as text search

Query Parameters

Name	Type	Description
hash*	String	sha256 hash of an image buffer in hex
page	Number	The page number in the list of pages to return by default the first page is returned
itemsPerPage	Number	The number of iterms to return in each page, this defaults to 100

Headers

Name	Type	Description
x-api-key	String	API Key Required if domain is not on allowlist.

200: OK Normal Response

{
    "status":"ok",
    "count": 1,
    "currentPage": 3,
    "totalPages": 3,
    "totalItems": 102
    "itemsPerPage": 100,
    "results":
    [
        {
            "txid":"ea0d...a8",
            "inputindex":"0",
            "inscriptionid":"ea0d....8i0",
            "blockheight":"775528",  // use blockheight as timestamp
            "contenttypestr":"image/png",
            "contenthash":"59edca9...a9ca4c80d",
            "contentlength":"217",
            "createdat":"2023-03-08T16:30:38.690Z" // this is when record is parsed - not the block timestamp
        },
        ...
    ]
}

200: OK Error Response with Cause

{
    status: 'error', 
    error: 'error reason'
}

500: Internal Server Error Server side error

{
    status: 'error',
    reason: 'server error'
}