LogoLogo
Back to AppHelp Center
  • Getting Started
    • Welcome
  • OrdinalsBot API
    • Overview
    • Libraries
    • Template-App
    • Signet
    • Testnet
    • Fractal
    • Getting Prices
      • Getting Prices (Legacy)
    • Create a Direct Inscription Order
    • Create a Managed Inscription Order
    • Get Order Status
    • Create a Collection
    • Create a Collection Order
    • Create Text Inscription Order
    • Search Inscriptions
    • Check Rare Sats Inventory
    • Referral Scheme
    • Transaction Accelerator
    • Burning Assets
    • Webhooks
    • Order States
    • Order Types
  • Runes
    • Etch
    • Mint
    • Direct Mint
      • 1. Generate Direct Mint PSBT
      • 2. Direct Rune Mint Process PSBT
    • Launchpad
      • Create
      • Mint
      • Get Launchpad
    • Airdrop
  • Token Pay
    • What is TokenPay?
    • API Docs
      • API reference
        • Order
        • Create payment psbt
        • Create burn rune psbt
        • Validate burn rune tx
        • Create burn inscription psbt
        • Utils
          • Checktx
          • Submittx
          • Finalize psbt
        • User
          • Withdrawal
          • Order
            • Rune
          • Account
            • Withdraw
            • Balance
      • Specification
  • Marketplace
    • User Guide: Pre-Inscribed Launchpad API
    • API Docs
    • Editions Launchpad
  • Launchpad API
    • Create Marketplace
    • Create a new Launchpad
    • Retrieve Launch PSBT
    • Confirm Launch
    • Check Allocation
    • Check for Padding Outputs
    • Setup Padding Outputs
    • Create buy offer
    • Confirm buy offer
    • Get Launch Info
  • Sat Scanner API
    • Find Special Ranges
    • Find Special Ranges UTXO
    • Supported Satributes
  • Sat Extractor
    • Extract
  • BRC20 / BRC2.0PROG
    • OPI API
    • Bitcoin Remix
  • SNS API
    • SNS API
  • Mempool API
    • Mempool API
  • TAP PROTOCOL
    • Tap Reader API
  • UTXO
    • Split
  • User Guide
    • Inscribe your first Ordinal
    • Receiving Payments
  • Knowledge Base
    • Ordinals
      • What is an Ordinal?
      • Satoshi Rarity
      • What are BRC-20 Tokens?
      • Image Optimisation
      • Pixel Art
    • Bitcoin
      • Unspent Transaction Output (UTXO)
  • Official Links
    • Twitter
    • Discord
Powered by GitBook
On this page
  • POST a new rune order
  • Create Rune
  1. Runes

Etch

PreviousOrder TypesNextMint

Last updated 25 days ago

Use this endpoint to create a rune as defined in

  • Runes are available on testnet only until block height 840000.

  • Currently rune etching requires inscribing a file, file can be anything and has no impact on the etched rune.

  • Rune names become available over time. Refer to for details.

  • Rune supply must equal premine + terms.cap * terms.amount

  • After the order is paid an etchingTx object will apper. The object will have a commit and a reveal field: commit is the txid of the commit transaction, reveal is the the txid of the reveal transaction

  • Rune orders take six blocks due to the commit-reveal protocol. After a rune is committed, the order will enter state waiting-reveal, six blocks later when the reveal is broadcast the order will be in state completed

POST a new rune order

Create Rune

POST https://api.ordinalsbot.com/runes/etch

Request Body

Name
Type
Description

rune*

String

Rune name

supply*

Number

Supply of the rune token

symbol*

String

Single letter symbol for the rune

divisibility*

Number

Number of decimal points one unit of rune can be divided into.

premine*

Number

Number of rune tokens the etching mints for the etcher.

files*

Array

An array of objects that includes:

Mandatory

name:string; => name of the file including extension.

size:number; => size of the file in bytes

url:string; => file URL hosted on OrdinalsBot buckets

Optional

metadataUrl:string; => metadata json file URL hosted on OrdinalsBot buckets

metadataSize:number; => size of the metadata file in bytes

metaprotocol:string; => Metaprotocol field to be included in the inscription data

Note: you can send any dataURL text/json/image/video data in a parameter called dataURL instead of url for files

metadataDataURL instead of metadataUrl for metadata json files "files" or "delegates" array is mandatory.

delegates*

Array

An array of objects that includes:

Mandatory

delegateId:string; => inscription ID of the delegate that will be inscribed.

Optional

metadataUrl:string; => metadata json file URL hosted on OrdinalsBot buckets

metadataSize:number; => size of the metadata file in bytes

metaprotocol:string; => Metaprotocol field to be included in the inscription data

receiveAddress*

String

A single Bitcoin address to receive the inscriptions for the whole order

terms

Object

Required only if premine !== supply

If supplied, supply must equal premine + terms.cap * terms.amount

An object that includes: amount: (number, required) amount of runes each mint transaction receives cap: (number, required) allowed number of mints

offset: (object, optional) object with required fields start and end

height: (object, optional) object with required fields start and end

turbo

Boolean

True by default. This flag indicates whether the rune opts-in for protocol changes, whatever they might be.

fee

Number

Miner fee that will be paid while inscribing the ordinals in sats/byte.

(default=2 sats/byte)

referral

String

Referral code to earn up to %15 of the order service fee.

additionalFee

Number

Amount of satoshis to charge extra for this order that will be added to "referral" account.

Needs to be used together with "referral" parameter.

Note: additionalFee is added PER FILE!

{
    "runeProperties": {
        "rune": "ORDINALSBOTD",
        "supply": 100000,
        "symbol": "$",
        "divisibility": 8,
        "premine": 0,
        "terms": {
            "cap": 1,
            "amount": 100000
        }
    },
    "fee": 8,
    "files": [
        {
            "url": "https://ordinalsbot-dev.s3.amazonaws.com/",
            "size": 860,
            "name": "somerandomfilename.jpg",
            "type": "image/jpeg"
        }
    ],
    "charge": {
        "id": "1c1b9327-e3ed-4315-91f6-97eccd746986",
        "address": "2MvLE2pRLFymaXmJBc3bee2By21jD4CSKGj",
        "metadata": {},
        "chain_invoice": {
            "address": "2MvLE2pRLFymaXmJBc3bee2By21jD4CSKGj"
        },
        "uri": "bitcoin:2MvLE2pRLFymaXmJBc3bee2By21jD4CSKGj?amount=0.00010501&label=1c1b9327-e3ed-4315-91f6-97eccd746986&lightning=lntb105010n1pnpppp3pp5uesfwexnaerj76dy9raa3m9q2ret6qwkru3kjufugnu79dqcrs2qdp6x93nzc3exverwtt9xdjkgtf5xvcn2tfex9nrvtfexajkxcmyxu6rvwfcxccqzzsxqy8ayqsp5kfdggyth6qawlzv43qzt9mmqc0mjdd5nh6p958ke4rnm8zy2kkus9qyyssq6z0v0z90gc2ng2wsvxa75tjy6svgaynvnnxqwvwpynwlpwgfg0f32wf2gtdhdd95n4z2t8nscug4s3638vn237up0sa9hyp2vs9l8gqpad3h7g",
        "ttl": 4320,
        "lightning_invoice": {
            "expires_at": 1712617650,
            "payreq": "lntb105010n1pnpppp3pp5uesfwexnaerj76dy9raa3m9q2ret6qwkru3kjufugnu79dqcrs2qdp6x93nzc3exverwtt9xdjkgtf5xvcn2tfex9nrvtfexajkxcmyxu6rvwfcxccqzzsxqy8ayqsp5kfdggyth6qawlzv43qzt9mmqc0mjdd5nh6p958ke4rnm8zy2kkus9qyyssq6z0v0z90gc2ng2wsvxa75tjy6svgaynvnnxqwvwpynwlpwgfg0f32wf2gtdhdd95n4z2t8nscug4s3638vn237up0sa9hyp2vs9l8gqpad3h7g"
        }
    },
    "chainFee": 7232,
    "serviceFee": 3269,
    "additionalFee": null,
    "receiveAddress": "tb1qwejhagpav9rkrwpk55ul6pes6f89glpkpds487",
    "baseFee": 2000,
    "rareSatsFee": 0,
    "postage": 546,
    "id": "1c1b9327-e3ed-4315-91f6-97eccd746986",
    "orderType": "rune-etch",
    "state": "waiting-payment",
    "createdAt": {
        ".sv": "timestamp"
    }
}
{
    status: 'error',
    error: 'error reason'
}

Supported file extensions may change. If you include any unsupported files order creation will fail.

Currently Supported files: 'apng', 'flac', 'gif', 'html', 'jpg','jpeg', 'mp3', 'pdf', 'png', 'svg', 'txt', 'wav', 'webm', 'webp', 'mp4', 'stl', 'glb', 'avif', 'yaml' , 'yml', 'asc', 'json', 'js', 'css', 'gz'

// Here's a sample payload you can POST to create a rune order
{
    "files": [
        {
            "url": "https://ordinalsbot-dev.s3.amazonaws.com/7b7b3b37-792b-4f29-bd37-7436fd461453",
            "size": 860,
            "name": "btc-skull-2.jpg",
            "type": "image/jpeg"
        }
    ],
    "rune": "SHIT•MEGA•COIN",
    "supply": 100000,
    "symbol": "$",
    "divisibility": 8,
    "fee": 8,
    "premine": 50000,
    "receiveAddress": "tb1pqwh3dxhg3k4szt9zm5kt8p0m97nl7k7zlmplehmr6alc4ut8xd5qams63p",
    "terms": {
        "amount": 1,
        "cap": 50000,
        "offset": {
            "start": 1,
            "end": 10000
        }
    }
}

https://docs.ordinals.com/runes.html
official documentation