6 min read

Prefer a video walkthrough? Follow along with Sahil to learn how to use the Ordinals and Runes API.

Subscribe to our YouTube channel for more videos!Subscribe

Overview

If you've ever found working with Bitcoin's raw data cumbersome or struggled to implement advanced functionality like tokenization or data inscriptions, QuickNode's Ordinals and Runes API offers a streamlined solution.

This guide introduces developers to the capabilities of Ordinals and Runes on Bitcoin and demonstrates how they can leverage these concepts using QuickNode's Ordinals and Runes API. Whether you're building a marketplace, a tracking tool, or exploring analytics, this guide provides a foundation for getting started.

What You Will Do

• Learn the fundamentals of Ordinals and Runes on Bitcoin
• Explore key functionalities of the Ordinals and Runes API
• Discover practical use cases for building applications

What You Will Need

• Basic knowledge of Bitcoin and blockchain technology
• A QuickNode account with the Ordinals and Runes API add-on enabled
• Familiarity with REST APIs and a development environment set up for making API calls (e.g., Postman, cURL, or a programming language like Python or JavaScript)

Understanding Ordinals and Runes

Bitcoin has always been a powerful yet straightforward blockchain. However, unlocking its potential for creating unique digital assets or tokens has been challenging. Ordinals and Runes solve this by adding advanced capabilities, enabling developers to inscribe data or create tokens directly on Bitcoin.

What Are Ordinals?

Ordinals is a protocol that introduces digital artifacts to Bitcoin by leveraging its smallest unit, satoshi. With Ordinals, you can take any of these satoshis and inscribe them with content - like images, text, or even small programs. It's like turning a regular satoshi into a unique digital artifact that you can send to others. Here's how it actually works briefly:

Technical Implementation

• Each satoshi in Bitcoin is assigned a unique serial number based on the order in which it was mined
• When a new block is mined, satoshis within it are numbered sequentially
• These numbers are "ordinal numbers," hence the name of the protocol

Inscription Process

1. Content Preparation: The digital content (image, text, etc.) is prepared and converted into inscriptionable format
2. Transaction Creation: A special Bitcoin transaction is created that contains the content data in witness section, a part of Bitcoin transactions designed to hold arbitrary data

For example, consider this block explorer link that showcases inscribed satoshis. You can see how each inscription includes details such as the inscription ID, content type, and the block it was mined in.

Satoshi (sat) is a term used to refer to a single unit of Bitcoin. A satoshi, which equals to 1 / 100,000,000 of a Bitcoin, is the smallest unit of value in Bitcoin.

What Are Runes?

While Ordinals are about making unique items, Runes helps you create tokens on Bitcoin. It allows you to make your own digital currency or points system on top of Bitcoin. You can set rules for how many tokens exist, how they're distributed, and how people can use them. By leveraging Runes, you can innovate on Bitcoin while benefiting from its security and decentralization.

It works by leveraging Bitcoin's native scripting capabilities through a process called "etching." When you etch a rune, you create a special Bitcoin transaction that defines the rune's fundamental properties such as its symbol, total supply, and decimal precision. These properties, once etched, become permanently immutable on the blockchain. Runes use Bitcoin's Unspent Transaction Outputs (UTXOs) as their foundation, where each UTXO can contain data about rune balances and transfers.

---

Ordinals and Runes API

Working directly with Bitcoin can be tricky because it requires parsing raw blockchain data, tracking satoshis across transactions, and building custom logic for inscriptions or tokens.

QuickNode's Ordinals and Runes API makes it simple to work with Ordinals and Runes with API calls. For developers, it eliminates the complexity of interacting with raw Bitcoin data, offering tools that accelerate development and help you build faster.

Capabilities Overview

Block & Network Operations:

• Get block information
• Track current block details

Inscription Operations:

• Retrieve inscription content and metadata
• Find inscriptions by block or transaction
• Browse inscription collections
• Get recursive inscription data

Satoshi Management:

• Track specific satoshis and their locations
• Get satoshi data at specific indices
• Retrieve recursive satoshi information

Runes Operations:

• Get individual rune details
• Retrieve all runes data

Commonly Used Methods

• ord_getInscription: Fetch details about a specific inscription by its ID.
• ord_getInscriptionsByBlock: Retrieve all inscriptions within a block.
• ord_getSat: Fetch data about a specific satoshi by its number.
• ord_getRune: Fetch data about a specific Rune by its ID.

With these features, you can build applications that are otherwise difficult to achieve with Bitcoin's native capabilities. In the next section, we'll walk through some practical use cases to help you get started.

Practical Use Cases

1. Building an Inscription Explorer

Objective: Create a platform for users to explore and understand inscriptions.

Key Methods:

• ord_getInscriptions - Fetch available inscription IDs
• ord_getInscription - Get detailed information about specific inscriptions
• ord_getContent - Retrieve inscription content in the form of HTML

Implementation Ideas:

1. Create a paginated view of all inscriptions
2. Enable detailed viewing of inscription metadata, including content type, timestamp, and sat details
3. Implement filtering by content type, block height, or inscription number
4. Show relationships between inscriptions using the children data
5. Display inscription content when supported by the content type

2. Sat Analysis Tool

Objective: Build a tool for analyzing and tracking specific satoshis and their inscriptions.

Key Methods:

• ord_getSat - Get detailed sat information like rarity, cycle, and epoch
• ord_getInscription - Get inscription details

Implementation Ideas:

1. Display comprehensive sat information including rarity, cycle, and epoch
2. Show all inscriptions associated with a specific sat
3. Create visualizations of sat distribution across blocks
4. Enable searches by sat name or number
5. Show historical context of the sat based on its block timestamp

3. Block-based Inscription Analytics

Objective: Analyze inscription patterns and trends across blocks.

Key Methods:

• ord_getInscriptionsByBlock - Retrieve inscriptions for specific blocks
• ord_getInscription - Get detailed inscription information

Implementation Ideas:

1. Generate statistics about inscription density per block
2. Create visualizations showing inscription type distribution
3. Track common patterns in inscription content types
4. Analyze fee patterns for inscriptions
5. Generate reports about inscription value distributions

4. Rune Management Dashboard

Objective: Create a detailed view of rune activity and statistics.

Key Methods:

• ord_getRunes - Get the list of all runes with details
• ord_getRune - Get details of a specific rune

Implementation Ideas:

1. Display all active runes with their key metrics like supply, burns, and mints
2. Show distribution of rune supply and burns
3. Track rune minting patterns
4. Create visualizations of rune activity over time
5. Enable filtering by rune characteristics (divisibility, supply, etc.)

5. Inscription Relationship Visualizer

Objective: Create a tool to explore and visualize relationships between inscriptions.

Key Methods:

• ord_getChildren - Get child inscriptions
• ord_getInscription - Get inscription details

Implementation Ideas:

1. Build a graph visualization of parent-child relationships
2. Track inscription hierarchies
3. Analyze patterns in inscription relationships
4. Enable exploration of inscription families
5. Show metadata differences between related inscriptions

6. Collection Explorer and Analytics

Objective: Create a platform for discovering and analyzing ordinal collections.

Key Methods:

• ord_getCollections - Get the list of collection IDs

Implementation Ideas:

1. Build a collection browser with pagination support
2. Create collection statistics and analytics dashboards
3. Enable filtering collections by various metadata attributes

Each of these use cases can be implemented as standalone tools or combined into a comprehensive platform for Ordinals and Runes analysis. The API provides rich data that can be used to create valuable insights and tools for the Ordinals ecosystem.

Check out our sample apps repository to get some inspiration for your project.

Setting Up Your Environment

In order to use the Ordinals and Runes API, you need to set up your environment. This involves signing up for a QuickNode account, getting your endpoint, and setting up API requests.

1. Log in to your QuickNode account
2. Create a new Bitcoin Mainnet endpoint if you haven't already
3. Enable the Ordinals and Runes API add-on
4. Copy your Bitcoin endpoint URL with the API enabled
5. Check our QuickNode API documentation for detailed method descriptions and examples
6. Use a tool like Postman or a programming language to send API requests

Conclusion

The Ordinals and Runes API opens new possibilities for developers to innovate on Bitcoin. From marketplaces to monitoring tools, its capabilities enable a wide range of applications. Dive into the API documentation to explore more methods and unleash the potential of Bitcoin inscriptions and Runes in your projects.

If you have any questions or need help, feel free to reach out to us on our Discord or Twitter.

We ❤️ Feedback!

Let us know if you have any feedback or requests for new topics. We'd love to hear from you.

Resources

• QuickNode Bitcoin Developer Resources
• QuickNode Bitcoin Documentation
• Ordinals and Runes API Add-On