# Etch

Use this endpoint to create a rune as defined in <https://docs.ordinals.com/runes.html>

{% hint style="info" %}

* 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 [official documentation](https://docs.ordinals.com/runes/specification.html#executing-the-runestone) 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`
  {% endhint %}

### `POST` a new rune order

## Create Rune

<mark style="color:green;">`POST`</mark> `https://api.ordinalsbot.com/runes/etch`

#### Request Body

<table><thead><tr><th width="168">Name</th><th width="106">Type</th><th>Description</th></tr></thead><tbody><tr><td>rune<mark style="color:red;">*</mark></td><td>String</td><td>Rune name</td></tr><tr><td>supply<mark style="color:red;">*</mark></td><td>Number</td><td>Supply of the rune token</td></tr><tr><td>symbol<mark style="color:red;">*</mark></td><td>String</td><td>Single letter symbol for the rune</td></tr><tr><td>divisibility<mark style="color:red;">*</mark></td><td>Number</td><td>Number of decimal points one unit of rune can be divided into.</td></tr><tr><td>premine<mark style="color:red;">*</mark></td><td>Number</td><td>Number of rune tokens the etching mints for the etcher.</td></tr><tr><td>files<mark style="color:red;">*</mark></td><td>Array</td><td><p>An array of objects that includes:</p><p></p><p><strong>Mandatory</strong></p><p><strong>name</strong>:string; => name of the file including extension.</p><p><strong>size</strong>:number; => size of the file in bytes</p><p><strong>url</strong>:string; => file URL hosted on OrdinalsBot buckets</p><p></p><p><strong>Optional</strong></p><p><strong>metadataUrl</strong>:string; => metadata json file URL hosted on OrdinalsBot buckets</p><p><strong>metadataSize</strong>:number; => size of the metadata file in bytes</p><p><strong>metaprotocol</strong>:string; => Metaprotocol field to be included in the inscription data</p><p></p><p><em><strong>Note:</strong> you can send any dataURL text/json/image/video data in a parameter called <strong><code>dataURL</code></strong> instead of <strong>url</strong> for files</em></p><p><em><strong><code>metadataDataURL</code></strong> instead of <strong>metadataUrl</strong> for metadata json files</em><br><br><em><strong>"files" or "delegates" array is mandatory.</strong></em></p></td></tr><tr><td>delegates<mark style="color:red;">*</mark></td><td>Array</td><td><p>An array of objects that includes:</p><p></p><p><strong>Mandatory</strong></p><p><strong>delegateId</strong>:string; => inscription ID of the delegate that will be inscribed.</p><p></p><p><strong>Optional</strong></p><p><strong>metadataUrl</strong>:string; => metadata json file URL hosted on OrdinalsBot buckets</p><p><strong>metadataSize</strong>:number; => size of the metadata file in bytes</p><p><strong>metaprotocol</strong>:string; => Metaprotocol field to be included in the inscription data</p></td></tr><tr><td>receiveAddress<mark style="color:red;">*</mark></td><td>String</td><td>A single Bitcoin address to receive the inscriptions for the whole order</td></tr><tr><td>terms</td><td>Object</td><td><p>Required only if <code>premine !== supply</code></p><p></p><p>If supplied, <code>supply</code> must equal <code>premine + terms.cap * terms.amount</code></p><p></p><p>An object that includes:<br><strong>amount</strong>: <em>(number, required)</em> amount of runes each mint transaction receives<br><strong>cap</strong>: <em>(number, required)</em> allowed number of mints<br></p><p><strong>offset</strong>: <em>(object, optional)</em> object with required fields <code>start</code> and <code>end</code></p><p></p><p><strong>height:</strong> <em>(object, optional)</em> object with required fields <code>start</code> and <code>end</code></p></td></tr><tr><td>turbo</td><td>Boolean</td><td>True by default. This flag indicates whether the rune opts-in for protocol changes, whatever they might be.</td></tr><tr><td>fee</td><td>Number</td><td><p>Miner fee that will be paid while inscribing the ordinals in sats/byte.</p><p></p><p>(default=2 sats/byte)</p></td></tr><tr><td>referral</td><td>String</td><td>Referral code to earn up to %15 of the order service fee.</td></tr><tr><td>additionalFee</td><td>Number</td><td><p>Amount of satoshis to charge extra for this order that will be added to "referral" account.</p><p>Needs to be used together with "referral" parameter.</p><p></p><p><mark style="color:red;"><strong>Note: additionalFee is added PER FILE!</strong></mark></p></td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "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"
    }
}
```

{% endtab %}

{% tab title="500: Internal Server Error " %}

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

{% endtab %}

{% tab title="400: Bad Request " %}

{% endtab %}
{% endtabs %}

{% hint style="success" %}
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'`
{% endhint %}

```json
// 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
        }
    }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ordinalsbot.com/runes/etch.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.