NAV

Introduction

Welcome to the Chisel API! You can use this API to submit individual or bulk inscriptions, and monitor their status.

Inscriptions

Create Inscription

// boilerplate
const data = new FormData();
data.append('fee_rate', 80);
data.append('postage', 700);
data.append('ordinal_receive_address', 'bc1qdr06k926axngldcpz48fe7vg72085muzxcsfzgp3eajnptnjlk5s5yz38y');
data.append('return_address', 'bc1qguzk63exy7h5uygg8m2tcenca094a8t464jfyvrmr0s6wkt74wls3zr5m3');

// add plaintext file
const blob = new Blob(['Hello World'], {type: 'text/plain'});
data.append('inscriptions', blob, `inscription_0.txt`);

// submit inscription
await fetch('https://chisel.xyz/api/inscribe', {
    method: 'POST',
    body: data
});

The above command returns JSON structured like this:

{
    "id": "b6a430e3-fa9b-48b6-81c4-28dfede1a5f0",
    "destination": "bc1qdr06k926axngldcpz48fe7vg72085muzxcsfzgp3eajnptnjlk5s5yz38y",
    "fee_rate": 80,
    "status": "awaiting-funding",
    "address": "bc1pfrf029j2wcgf3uq9sa9p79knveeq23gasruwa34rku6mzsuaxgzsyv5jx4",
    "service_fee": 11669,
    "amount": 66350,
    "size": 720,
    "expiration": 1703542167784
}

In the below code snippet we create multiple delegate inscriptions:

const data = new FormData();

// set a fee rate of 1.3 s/vB
data.append('fee_rate', 13);
data.append('fee_rate_decimals', 1);

data.append('postage', 700);
data.append('ordinal_receive_address', 'bc1qdr06k926axngldcpz48fe7vg72085muzxcsfzgp3eajnptnjlk5s5yz38y');
data.append('return_address', 'bc1qguzk63exy7h5uygg8m2tcenca094a8t464jfyvrmr0s6wkt74wls3zr5m3');

// specify the 800 delegates and their metadata
const delegateId = '8edc1d578a0864ec099b4a8f3a7ef3d2f741fd70b2cf0cd3911a171b54b5e9a4i10';
for (let i = 0; i < 800; i++) {
    const currentMetadata = {foo: 'bar', hello: 'world', context: 'Chisel Developer API'};

    formData.append('metadata', new Blob([Buffer.from(JSON.stringify(currentMetadata), 'utf-8')], {type: 'application/json'}));
    formData.append('delegates[]', delegateId);

    // optionally specify an explicit mime type to be added to the delegating inscription
    formData.append('mime_types[]', 'text/html;charset=utf-8');
}

// submit inscription
await fetch('https://chisel.xyz/api/inscribe', {
    method: 'POST',
    body: data
});

Create one or multiple new inscriptions.

HTTP Request

POST https://chisel.xyz/api/inscribe

Form Encoding

multipart/form-data

Request Body Parameters

Parameter Type Necessity Description
inscriptions File[] Required Files to be inscribed.
ordinal_receive_address String Required Address to send the inscriptions to.
fee_rate Integer Required Fee rate in satoshis per virtual byte.
fee_rate_decimals Integer Optional Number of decimals to interpret the fee_rate parameter. For example, if fee_rate is 128 and fee_rate_decimals is 1, the fee rate is interpreted as 12.8, and if fee_rate_decimals was 2, it would be interpreted as 1.28.
split_revelations Boolean Optional Should each inscription have a separate revelation transaction?
inscribe_provided_own_ordinal Boolean Optional Set to true to enable bringing own satoshi.
parent_inscription_ids[] String[] Optional Array of inscription ID strings that the new inscriptions will become children of.
skip_mime_check Boolean Optional Allow any mime type, including those not yet supported by ord.
postage Integer Optional Value of each inscription's revelation output. Default: 10000.
compress brotli | gzip (String) Optional Compress data using either Brotli (brotli) or Gzip (gzip).
locktime Integer Optional Add a locktime to the revelation transactions. May not be used in conjunction with grind_ambifix.
grind_ambifix String Optional Grind a 1-to-4-character-ambifix for the revelation transactions, making them either start or end with the ambifix. Must be hexadecimal. May not be used in conjunction with locktime.
return_address String Optional Address whereto refunds would be sent. If used in conjunction with parent inscription IDs, all parent inscriptions will be sent here.
delegates[] String[] Optional Array of inscription IDs to use as delegates. Cannot be used in conjunction with the inscriptions field. When used, no content or (by default) mime type* gets inscribed.
mime_types[] String[] Optional Array of MIME types to use with delegate inscriptions only. Length must match delegates.
metaprotocols[] String[] Optional Array of strings to use as the metaprotocol for each file. Length must match inscriptions.
metadata File[] Optional Array of JSON files to mark as metadata corresponding to each inscription. Length must match inscriptions. null indicates no metadata for the inscription at the given index.
titles String[] Optional Array of strings to use as the title for each inscription. Empty strings are allowed, thus to be distinguishable from untitled inscriptions, length must not exceed inscriptions, but needs not match it.
inscription_traits File[] Optional Array of JSON files to use as traits for each inscription. Length must match inscriptions. null indicates no traits for the inscription at the given index.
gallery GalleryItem[] Optional Array of objects each containing an inscription_id field and an optional title field.
gallery_traits File[] Optional Array of JSON files to use as traits for each gallery item. Length must match gallery. null indicates no traits for the gallery item at the given index.
destination_address_overrides[] String[] Optional Array of destination address overrides. Length must match inscriptions. Empty string indicates no destination override for the inscription at the given index.
parent_inscription_id_overrides[][] String[][] Optional Array of parent inscription ID array overrides. Length must match inscriptions. Single-element array containing the null-string indicates no parent inscription ID override for the inscription at the given index. Single-element array containing an empty string indicates an override 0 parent inscriptions for the inscription at the given index. This must be used in conjunction with parent_inscription_ids. All override array elements must be contained within parent_inscription_ids.
unbounds[] Integer[] Optional Array of inscription indices that should be marked as unbound.
allow_nonstandard Boolean Optional Allow the revelation transactions to be non-standard, i.e. change their weight limit to 3.9MB. You will not be able to broadcast your non-standard transaction using the standard relay network!
allow_duplicate_parents Boolean Optional Allow parent inscription IDs to be duplicated.
rune[operation] String Optional Either etch or mint, depending on the intended rune operation.

Each gallery item is an object with an inscription_id field and an optional title field. Gallery creation is only supported with a single inscription.

Parameter Type Necessity Description
inscription_id String Required Inscription ID of the gallery item. Example: 6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799i0.
title String Optional A title for the gallery item.

Rune Parameters

All Rune parameters are sent within a rune field. So name would correspond to rune[name], etc. When doing rune operations, the inscriptions field is no longer required.

Etching

To etch a rune in conjunction with an inscription, simply keep the inscriptions or delegates field from the submission parameters.

Parameter Type Necessity Description
name String Required Ticker symbol of the rune to be etched. Use periods for spacers. Example: HELLO.WORLD.
symbol Character Optional Single character point string.
divisibility Integer Optional Number of decimals to format rune tokens with. Cannot exceed 38.
premine Integer Optional Number of atomic rune tokens to premine.
cap Integer Optional Maximum number of rune minting operations. *Must be used with amount.
amount Integer Optional Number of rune tokens to issue per each mint operation. *Must be used with cap.
height_start Integer Optional Absolute block height at which the rune should first become mintable.
height_end Integer Optional Absolute block height at which the rune should stop being mintable.
offset_start Integer Optional Relative block offset from the rune's etching at which the rune should stop being mintable.
offset_end Integer Optional Relative block offset from the rune's etching at which the rune should stop being mintable.

Minting

When minting runes, no inscriptions may be specified in the submission parameters.

Parameter Type Necessity Description
id String Required ID of the rune to be minted. Must be in the form <block>:<tx>.
count Integer Required Numer of rune tokens to mint.

Get Inscription Status

curl "https://chisel.xyz/api/inscription/b6a430e3-fa9b-48b6-81c4-28dfede1a5f0/status"

This endpoint returns JSON structured like this:

{
    "id": "b6a430e3-fa9b-48b6-81c4-28dfede1a5f0",
    "destination": "tb1pufcu7ap75f333lxk8juv3e8ad2cmxxwckvg66fd3vkkn50pspgpsphqn5q",
    "fee_rate": 80,
    "status": "awaiting-funding",
    "funding_address": "tb1pc8ug6pv4s9he0me75zhu0w6m7hrx6lcca5wyypc6t9j523fsfxaqk0gssk",
    "service_fee": 11669,
    "amount": 66350,
    "size": 720,
    "expiration": 1703542167784
}

Obtain a specific inscription's status.

HTTP Request

GET https://chisel.xyz/api/inscription/<ID>/status

URL Parameters

Parameter Description
ID The ID of the inscription whose status is to be retrieved.

Response Body Values

Parameter Type Description
id String ID of the inscription. It can be accessed via https://chisel.xyz/order/<id>
destination String Bitcoin address where the inscription(s) and, if applicable, parent(s) will be sent.
fee_rate Integer The fee rate the Chisel-generated transactions will have.
status Enum One of awaiting-funding, awaiting-ordinal, broadcasting, awaiting-confirmation, and confirmed.
size Integer The aggregate byte size of all the inscriptions.
funding_address String Funding address where bitcoin (amount satoshis) must be sent to fund the inscription.
amount Integer Amount on satoshis of the necessary total fee to be sent to the funding address (address)
parent_receptacle_address String Applicable with parent/child. Address where the parent(s) must be sent. Only shown after the inscription is funded.
ordinal_receptacle_address String Applicable with BYO. Address where the user's ordinal must be sent. Only shown after the inscription is funded and, if applicable, after all parents are received.
parent_inscription_id String The id of the parent inscription that is currently expected to be sent next to ordinal_receptacle_address. When Chisel is expecting a BYO ordinal, this field will be absent.
parent_inscription_ids String[] The id of all the parent inscriptions the children will have.
received_ordinal_count Integer The total number of BYO ordinals and parents that have been registered as received so far. The parents fill up first, and the BYO ordinal comes last.
expiration Integer Unix timestamp in milliseconds by which the funding must be received. Otherwise, the order will expire.

Boost Inscription Fee Rate

const data = new URLSearchParams();
data.append('fee_rate', 80);
data.append('commit', false);

// submit inscription
await fetch('https://chisel.xyz/api/inscription/b6a430e3-fa9b-48b6-81c4-28dfede1a5f0/boost', {
    method: 'POST',
    body: data
});

This endpoint returns JSON structured like this:

{
    "id": "b6a430e3-fa9b-48b6-81c4-28dfede1a5f0",
    "destination": "tb1pufcu7ap75f333lxk8juv3e8ad2cmxxwckvg66fd3vkkn50pspgpsphqn5q",
    "fee_rate": 80,
    "status": "awaiting-funding",
    "funding_address": "tb1pc8ug6pv4s9he0me75zhu0w6m7hrx6lcca5wyypc6t9j523fsfxaqk0gssk",
    "service_fee": 11669,
    "amount": 66350,
    "size": 720,
    "expiration": 1703542167784
}

Boost a specific inscription. This will return a new order with its own funding address and funding amount.

HTTP Request

POST https://chisel.xyz/api/inscription/<ID>/boost

URL Parameters

Parameter Description
ID The ID of the inscription whose status is to be retrieved.

Request Body Parameters

Parameter Type Description
fee_rate Integer The fee rate to which the inscription(s) should be boosted.
commit Boolean Should the request be submitted, or should only a price estimate be calculated?