# 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
        }
    }
}
```