| Name | Type | Description |
|---|---|---|
| order* | Object | The order request you would send to /order, /inscribe or any other priced endpoint. |
| type* | string | The type of your order, see all types in the table at Order Types |
| Name | Type | Description |
|---|---|---|
| size* | Number | Total size of all files to be inscribed in bytes |
| fee* | Number | Miner fee that will be paid while inscribing the ordinal in sats/byte. (default=2 sats/byte) |
| count | Number | Number of files to be inscribed (default=1) |
| rareSats | String | Inscribe on a rare, exotic, early sat. Options: block9 | block78 | pizza | uncommon | random (default=random) check |
| type | Enum | The order type "bulk" for Broken link |
| batchMode | String | "separate-outputs" or "shared-output" if requesting price calculation for a batch inscription. |
| additionalFee | Number | Additional fee(in satoshis) to be added to order total and passed to your referral code. |
| postage | Number | Set custom postage for the order's asset: minimum 330 sats, maximum 10,000 sats. (default=546) |
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
see below for sample payload.
| | delegates | Array |An array of objects that includes:
Mandatory
delegateId: string; => the delegate inscription id
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
Array of parent objects that will become parents to the inscriptions
Mandatory
inscriptionId: string; => the inscription id of the parent
returnAddress: string; => where to return this parent inscription
value: number; => amount of sats in the parent inscription utxo
Miner fee that will be paid while inscribing the ordinals in sats/byte.
(default=2 sats/byte)
| | postage | Number |Set custom postage for the order's asset: minimum 330 sats, maximum 10,000 sats.
(default=546)
| | allowedSatributes | Array |Array of satributes that this inscription will be allowed to be inscribed on.
List of supported satributes are available at /pages/O6XMHFThv8zYGGJtV2KO
Amount of satoshis to charge extra for this order that will be added to "referral" account.
Needs to be used together with "referral" parameter.
| | inscriptionIdPrefix | string |We will grind an inscription id prefix if this option is specified. All inscriptions in the order will have this prefix.
Maximum: 4 hex characters i.e. "b1fd"
Will make the inscription envelope valid as per rules before jubilee to make the resulting inscription output not "cursed" hence, "not vindicated" (aka "blessed")
Refer to ordinals docs for details.
NOTE: Some BRC20 indexers are strict about this and some are not...
| | webhookUrl | String |webhook url to receive a POST payload for order updates.
Refer to /pages/JTttvvY9TijDbZ3AzmDH for format of the webhook payload
| {% tabs %} {% tab title="200: OK " %} ```json { status: 'ok', id: 'c411ca33-53dd-4d4f-b959-6c6dffcc88e5', ..., // input parameters charge: { // The payment address will appear with a short delay // Do a GET /order?id={id} to get the charge address amount: 1218725 }, chainFee: 718725 // in satoshis serviceFee: 2000, // in satoshis orderType: 'direct', createdAt: 1675785959855, // timestamp in ms, } ``` {% 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 an order with metadata { "files": [ { "size": 10, "type": "plain/text", "name": "my-text-inscription-file.txt", "dataURL": "data:plain/text;base64,dGVzdCBvcmRlcg==", "metadataDataURL": "data:application/json;base64,ewogICAgImluc2NyaWJlZF9ieSI6ICJPcmRpbmFsc0JvdCIKfQ==", "metadataSize": 37 } ], "postage": 546, "receiveAddress": "", "fee": "11" } ``` ## Example of parent/child order with a delegate *Inscription properties:* * one delegate inscription of 0426b1e763be8f7b6cff7bc05640534f506d174dc6f14b57ce146bc37a553b06i0 * three parents * chosen prefix "00" *Result:*The address to which the PSBT will send funds.
Note: This address would come from /pages/IPVBmJE53CGxMwVlIQap
UTXO that contains the special/rare sat that will inscribed on. This should be in txid:vout format for example:bab2074844dbf62264e2bcf4298ee90d135973e2fe43ae7e33923e7e0c2d1884:0
| Name | Type | Description | | -------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | orderId\* | String | The ID of the parent child order. The PSBT will be created to pay the bitcoin fee as well as to transfer the parent inscriptions for this order | | paymentAddress\* | String | Bitcoin payment address where common sats for fees and postage will be paid from. | | paymentPublicKey\* | String | Bitcoin payment public key where where common sats for fees and postage will be paid from. | | ordinalAddress\* | String | Address for holding ordinals which is usually a taproot address for inscriptions, runes and BRC20. | | ordinalPublicKey\* | String | The public key for the ordinals address which is a taproot address for inscriptions, runes or BRC20. | | feeRate\* | Number | Target Fee rate that should be used in sats/vB | | specialSatsOutput | String |
(Optional) Special sat utxo you want to use for the inscription itself.
This utxo will be placed after parents, before any fee utxo pulled from your payment address.
| {% hint style="info" %} Get in touch for any feedback regarding this service in **#developers** channel on our discord: [https://discord.ordinalsbot.com](https://discord.ordinalsbot.com/) {% endhint %} {% tabs %} {% tab title="200: OK Normal Response" %} ```json { // PSBT to be signed and published by user's wallet "psbtBase64": "cHNi...AAAAA", // same PSBT in hex format (for leather wallet) "psbtHex": "70736274ff01...47dc200000000", // Payment inputs to sign with the payment address "paymentInputIndices": [ 1 ] // Ordinal inputs to sign with the ordinal address "ordinalInputIndices": [ 0 ] } ``` {% endtab %} {% tab title="200: OK Error Response with Cause" %} ``` { status: 'error', error: 'error reason' } ``` {% endtab %} {% tab title="500: Internal Server Error Server side error" %} ``` { status: 'error', reason: 'unable to check data' } ``` {% endtab %} {% endtabs %} **Below is an example of creating the PSBT and singing it using XVerse wallet:** ```javascript /** * Create a PSBT for signing the transaction by calling /create-parent-child-psbt * API. * This returns a base64-encoded PSBT, PSBT Hex, sender ordinal, and * payment and ordinal inputs that need to be signed. */ const { psbtBase64, paymentInputIndices, ordinalInputIndices, psbtHex } = await axios({ method: "post", url: "https://api.ordinalsbot.com/create-parent-child-psbt", data: { orderId, // The ID of the order for which to create the PSBT. paymentAddress, // The user's payment address. paymentPublicKey, // The user's payment address public key. ordinalAddress, // The user's ordinal address. ordinalPublicKey, // The user's ordinal address public key. feeRate, // The fee rate selected by the user in sats/vB. }, }); // input to sign const inputsToSign = [ { address: ordinalsAddress, signingIndexes: ordinalInputIndices, }, { address: paymentAddress, signingIndexes: paymentInputIndices, }, ]; // When using XVerse Wallet // Create the payload for signing the transaction const payload = { network: { type: "Mainnet" }, message: "Sign Transaction", psbtBase64: psbtBase64, // PSBT returned by the API broadcast: true, inputsToSign: inputsToSign, }; // Make signing request await signTransaction({ payload, onFinish: async (response) => { try { console.log({ response }); console.log(`Payment successful: ${response?.txId}`); } catch (saveError) { console.error("Error Payment:", saveError); } }, onCancel: () => console.log("Payment canceled"), }); ``` ## Order States Direct inscription orders go through below states, note that some of them are optional. ```json 'prep' // commit address is being generated 'waiting-parent' // optional - order is waiting for the parent inscription to hit the wallet 'waiting-payment' // order is waiting for a payment to be detected 'mempool' // payment tx is seen and reveal tx is broadcasted into the mempool 'completed' // reveal tx received 1 confirmation, order is finalized. ``` # Get Order Status Use this endpoint to check the status of an order. {% hint style="warning" %} The GET /order endpoint has a rate limit of maximum 300 requests a minute. {% endhint %} ## Get Order Status `GET` `https://api.ordinalsbot.com/order` Check an inscription order status. #### Query Parameters | Name | Type | Description | | ------------------------------------ | ------ | ---------------------------------------------- | | id\* | String | Order ID returned by the `/bulkorder` endpoint | {% tabs %} {% tab title="200: OK Normal Response" %} ```json { status: 'ok', paid: true, // order payment successfully received underpaid: true, // order is underpaid => user needs to complete the payment. expired: true, // order payment is not received in the allocated time, tx: { "commit": "edc...be9", "fees": 157840, "inscription": "dff...5i0", "reveal": "dff...0c5" }, // inscription data as returned by ord wallet sent: '4axxxdeadbeef', // order is inscribed and sent to the provided address } ``` {% endtab %} {% tab title="200: OK Error Response with Cause" %} ```json { status: 'error', error: 'error reason' } ``` {% endtab %} {% tab title="500: Internal Server Error Server Side Error" %} ```json { status: 'error', reason: 'unable to save data' } ``` {% endtab %} {% endtabs %} # Create a Collection Use these endpoints to create a collection that other users will be able to create orders on and inscribe on demand. {% hint style="warning" %} All collections must be approved by the ordinalsbot.com team before they go live. Collections with over 1000 items need to be manually uploaded. Get in touch with us on [Discord](https://discord.ordinalsbot.com). The `/order` endpoint has a rate limit of 2 requests per 10 seconds.A {% endhint %} ## Create Collection `POST` `https://api.ordinalsbot.com/collection-create` Use this method to create a collection, if your files are already on a publicly accessible URL. #### Headers | Name | Type | Description | | ------------ | ------ | ---------------- | | Content-Type | String | application/json | #### Request Body| Name | Type | Description |
|---|---|---|
| files | Object | An array of objects that includes: name:string; => name of the file including extension. size:number; => size of the file in bytes url:string; => publicly accessible image URL You can also provide files manually after contacting us. |
| id* | String | URL safe unique collection slug. Will be used as mint URL. |
| name* | String | Collection Display Name |
| description* | String | Collection description |
| creator* | String | Collection creator |
| totalCount* | Number | Max supply of the collection. |
| price | Number | Inscription price per file (for collection creator) set to 0 for free mints |
| altPrices | Object | Price item in collection with rune tokens. Any rune token can be used. Parameters: rune price object => token example: |
| String | Collection twitter account | |
| website | String | Collection website |
| banner | String | Collection banner image URL |
| cover | String | Collection cover image URL |
| creator-address | String | Bitcoin address to receive payouts from inscriptions |
| allowList | Object | allowList object in this format { "address1": { "allocation": 5 }, "address2": { "allocation": 3 }, } |
| Name | Type | Description |
|---|---|---|
| id* | String | URL safe unique collection ID of the collection on OrdinalsBot |
| onchainFormat | Boolean | Set to true if you prefer to have the collection json in EVM friendly format. |
API Key
Required if no turnstile token is present.
| #### Request Body | Name | Type | Description | | | | | | | | -------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- | -------- | ----- | ------- | --------------------------------------------------------------------------------------------------------------------- | | collection\* | Object |Object including
id: Collection slug to be inscribed
count: number of inscriptions being ordered.
| | | | | | | | receiveAddress | String | Bitcoin address to receive the inscriptions for the whole order | | | | | | | | token\* | String |Cloudflare turnstile token
Required if no x-api-key header is present.
| | | | | | | | rareSats | String |One of following options:
block9 | block78 | pizza | uncommon | black | vintage | random
Check /inventory endpoint for all available options and their current availability.
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!
| | | | | | | | referral | String | Referral code to earn up to %15 of the order service fee. | | | | | | | | timeout | Number |Order timeout in minutes. Must be a multiple of 10.
Generated payment invoice will be valid for this duration only. Payments that are sent after this will not be processed.
Refrain from using too short timeout values and instead use #cancel-an-order
(default=4320)
| | | | | | | | webhookUrl | String |webhook url to receive a POST payload for order updates
Refer to /pages/JTttvvY9TijDbZ3AzmDH for format of the webhook payload
| | | | | | | {% tabs %} {% tab title="200: OK " %}{
status: 'ok',
..., // input parameters
charge: {
...
"id": "815xxx-xxx-xxx-xxx79",
"address": "3P...Vu",
"amount": 1218725,
"lightning_invoice": {
"expires_at": 1675786558,
"payreq": "lnbc1218...7qz9v"
},
"created_at": 1677176476,
},
paylink: {
"id": "66xxx16", // visit https://app.hel.io/pay/66xxx16 to pay
},
chainFee: 718725 // in satoshis
serviceFee: 100000, // in satoshis
orderType: 'bulk',
createdAt: 1675785959855, // timestamp in ms,
}
{
status: 'ok',
..., // input parameters
charge: {
...
"id": "815xxx-xxx-xxx-xxx79",
"address": "3P...Vu",
"amount": 1218725,
"lightning_invoice": {
"expires_at": 1675786558,
"payreq": "lnbc1218...7qz9v"
},
"created_at": 1677176476,
},
chainFee: 718725 // in satoshis
serviceFee: 100000, // in satoshis
orderType: 'bulk',
createdAt: 1675785959855, // timestamp in ms,
}
The text you want to search
Note: text field can also accept a list of comma separated strings such that it will do a search where ALL of these strings exist in the inscription content.
?text=some,random,words
API Key
Required if domain is not on allowlist.
| {% tabs %} {% tab title="200: OK Normal Response" %} ```json { "status":"ok", "count": 1, "currentPage": 3, "totalPages": 3, "totalItems": 102 "itemsPerPage": 100, "results": [ { "txid":"87a1d452d2dcc89c66018a897c9910629d6c3173820979a740730e195433fd26", "inputindex":"0", "inscriptionid":"87a1d452d2dcc89c66018a897c9910629d6c3173820979a740730e195433fd26i0", "inscriptionnumber":"181258", "blockheight":"778281", "contentstr":"{\"p\":\"sns\",\"op\":\"reg\",\"name\":\"ordinalsbot.sats\"}", "contenttypestr":"text/plain;charset=utf-8", "contenthash":"c987a51dc14fb8e9e909b8482c1c62df246904442e851f41d6891e7af3042b23", "contentlength":"30", "metadatastr": "{\"integer\":123,\"float\":123.456,\"string\":\"hello world\",\"array\":[1,2,3],\"object\":{\"key1\":\"value1\",\"key2\":\"value2\"},\"boolean\":true,\"null\":null,\"undefined\":\"undefined\",\"byteString\":\"48656c6c6f20576f726c64\",\"taggedData\":{\"tag\":1,\"value\":\"2022-12-31T23:59:59Z\"}}", "createdat":"2023-03-08T21:05:16.349Z" } ] } ``` {% endtab %} {% tab title="200: OK Response with Error" %} ``` { status: 'error', error: 'error reason' } ``` {% endtab %} {% tab title="500: Internal Server Error Server side error" %} ``` { status: 'error', reason: 'server error' } ``` {% endtab %} {% endtabs %} ### Search for an existing Image or File Use this endpoint to check if a certain image was inscribed before. We call this a "hash check". {% hint style="info" %} Image Search is done by hashing the image file and checking against previous inscriptions' hashes. To use this endpoint you need to sha256 hash the image file content as below: {% endhint %} ```javascript const base64encodedimage = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAoElEQVR42u2VMQ6AMAhFe0fT1d3V3cv0ojUxaoBSBEo3Sf7S6n+UIqb0R2BUoHjjnPOrSBAyphqFiOajEJW5F9KrdyMvBL10lK0r+qwJ8GVOIVoAm/26L5eg8bNmPQWbfb1rzq3B+3ADaPZwzQJoukZ7B1qICkD3wgHTTzAVwO1ZOwlBep3DQc1tqimR1Vz8FqSB55qmEmD0fyACmBEuxglnHBu4i1egeQAAAABJRU5ErkJggg==' const buff = Buffer.from(base64encodedimage.split(";base64,")[1], 'base64'); const imageHash = bitcoin.crypto.sha256(buff).toString('hex') ``` ## Search for Image `GET` `https://api.ordinalsbot.com/search` Check for previous occurrences of an image in inscriptions. Results array will be sorted by ascending block height.\ \ Pagination parameters are the same as text search #### Query Parameters| Name | Type | Description |
|---|---|---|
| hash* | String | sha256 hash of an image buffer in hex |
| page | Number | The page number in the list of pages to return by default the first page is returned |
| itemsPerPage | Number | The number of iterms to return in each page, this defaults to 100 |
API Key
Required if domain is not on allowlist.
| {% tabs %} {% tab title="200: OK Normal Response" %} ```json { "status":"ok", "count": 1, "currentPage": 3, "totalPages": 3, "totalItems": 102 "itemsPerPage": 100, "results": [ { "txid":"ea0d...a8", "inputindex":"0", "inscriptionid":"ea0d....8i0", "blockheight":"775528", // use blockheight as timestamp "contenttypestr":"image/png", "contenthash":"59edca9...a9ca4c80d", "contentlength":"217", "createdat":"2023-03-08T16:30:38.690Z" // this is when record is parsed - not the block timestamp }, ... ] } ``` {% endtab %} {% tab title="200: OK Error Response with Cause" %} ``` { status: 'error', error: 'error reason' } ``` {% endtab %} {% tab title="500: Internal Server Error Server side error" %} ``` { status: 'error', reason: 'server error' } ``` {% endtab %} {% endtabs %} ### Search all inscriptions for any metadata value ## Metadata Search `GET` `https://api.ordinalsbot.com/indexer/metadata` You can search for any text inside metadata fields of all existing inscriptions. Pagination options can be specified by adding `itemsPerPage` and `page`\ values in the query parameters. Response provides an array of results as well as information on current page, total page numbers and total items available for the search criteria.\ \ Response structure: `{` \ `results: [{},{},{},{}], // array of restults` \ `count: 0, // number of Ordinals in the current results array`\ `currentPage: page, // current page number` \ `totalPages: 0, // total pages that can be returned for the current search criteria` \ `totalItems: 0 // total items in the database for the current search criteria` \ `}` #### Query Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | text\* | String |The text you want to search inside metadata fields of all inscriptions.
This can be a list of strings separated by comma if you want to search for multiple strings at once (AND search) i.e.:
?text=donot,trust,verify
| | page | Number | The page number in the list of pages to return by default the first page is returned | | itemsPerPage | Number | The number of iterms to return in each page, this defaults to 100 | #### Headers | Name | Type | Description | | --------- | ------ | ------------------------------------------------------------ | | x-api-key | String |API Key
Required if domain is not on allowlist.
| {% tabs %} {% tab title="200: OK Normal Response" %} ```json { "status":"ok", "count": 1, "currentPage": 3, "totalPages": 3, "totalItems": 102 "itemsPerPage": 100, "results": [ { "txid":"87a1d452d2dcc89c66018a897c9910629d6c3173820979a740730e195433fd26", "inputindex":"0", "inscriptionid":"87a1d452d2dcc89c66018a897c9910629d6c3173820979a740730e195433fd26i0", "inscriptionnumber":"181258", "blockheight":"778281", "contentstr":"{\"p\":\"sns\",\"op\":\"reg\",\"name\":\"ordinalsbot.sats\"}", "contenttypestr":"text/plain;charset=utf-8", "contenthash":"c987a51dc14fb8e9e909b8482c1c62df246904442e851f41d6891e7af3042b23", "contentlength":"30", "metadatastr": "{\"integer\":123,\"float\":123.456,\"string\":\"hello world\",\"array\":[1,2,3],\"object\":{\"key1\":\"value1\",\"key2\":\"value2\"},\"boolean\":true,\"null\":null,\"undefined\":\"undefined\",\"byteString\":\"48656c6c6f20576f726c64\",\"taggedData\":{\"tag\":1,\"value\":\"2022-12-31T23:59:59Z\"}}", "createdat":"2023-03-08T21:05:16.349Z" } ] } ``` {% endtab %} {% tab title="200: OK Response with Error" %} ``` { status: 'error', error: 'error reason' } ``` {% endtab %} {% tab title="500: Internal Server Error Server side error" %} ``` { status: 'error', reason: 'server error' } ``` {% endtab %} {% endtabs %} ## Search for Inscription ID `GET` `https://api.ordinalsbot.com/indexer/inscription` Check for an inscription in our indexer. This endpoint allows you to see if an inscription is indexed by our indexer and will return content hash and content string. #### Query Parameters| Name | Type | Description |
|---|---|---|
| id* | String | Inscription id i.e. 98e0f396ecff2eef7914e35a90a44e3bb7601c7071985cfacfd2d5f29c5207e7i0 |
API Key
Required if domain is not on allowlist.
| {% tabs %} {% tab title="200: OK Normal Response" %} ```json { "status": "ok", "results": [ { "txid": "98e0f396ecff2eef7914e35a90a44e3bb7601c7071985cfacfd2d5f29c5207e7", "inputindex": "0", "inscriptionid": "98e0f396ecff2eef7914e35a90a44e3bb7601c7071985cfacfd2d5f29c5207e7i0", "inscriptionnumber": "45652", "blockheight": "222945", "contenttypestr": "video/mp4", "owner": null, "content": "000000206674797069736f6d0000020069736f6d69736f32617663316d703431000000086672656500000a756d646174000002ae0605ffffaadc45e9bde6d948b7962cd820d923eeef78323634202d20636f7265203136342072333130382033316531396639202d20482e3236342f4d5045472d342041564320636f646563202d20436f70796c65667420323030332d32303233202d20687474703a2f2f7777772e766964656f6c616e2e6f72672f783236342e68746d6c202d206f7074696f6e733a2063616261633d31207265663d33206465626c6f636b3d313a303a3020616e616c7973653d3078333a3078313133206d653d686578207375626d653d37207073793d31207073795f72643d312e30303a302e3030206d697865645f7265663d31206d655f72616e67653d3136206368726f6d615f6d653d31207472656c6c69733d31203878386463743d312063716d3d3020646561647a6f6e653d32312c313120666173745f70736b69703d31206368726f6d615f71705f6f66667365743d2d3220746872656164733d34206c6f6f6b61686561645f746872656164733d3120736c696365645f746872656164733d30206e723d3020646563696d6174653d3120696e7465726c616365643d3020626c757261795f636f6d7061743d3020636f6e73747261696e65645f696e7472613d3020626672616d65733d3320625f707972616d69643d3220625f61646170743d3120625f626961733d30206469726563743d3120776569676874623d31206f70656e5f676f703d3020776569676874703d32206b6579696e743d323530206b6579696e745f6d696e3d3235207363656e656375743d343020696e7472615f726566726573683d302072635f6c6f6f6b61686561643d34302072633d637266206d62747265653d31206372663d32332e302071636f6d703d302e36302071706d696e3d302071706d61783d3639207170737465703d342069705f726174696f3d312e34302061713d313a312e30300080000002ab658884003bfffef74ebf029b45976a0392570af6caa42659fdd28e1d9e92a8270e6d6aa52ce3d7a7b04aa00b6ca6d7c4f54315dcd164242960764aafcbb4cf97b20af1ad3ead8dcd324c4de45ceb06e413cf3c164dc1daeac2e391af678e58f356bccaf8bfe8280c04a65bff52bc3b29eeb7cb3a7608263f7fcf7279e79b29637d8583f62d4e42a791ed8b548ec2e1557ec559e331565a1712da253fb44e77fa99939ac26ed85a6bc9c43edc44e70ea395ac81d2a27e108ea4333146d2c4303202f3f700a70fbbf9fc9b2e7fa9571d307fe3f959ac8bf1f6da68ea7c5c1d1b57b456af389bbea3708deb9508ea98a0d47430df81dd035cd2d49a646450bb2c18f05cc97747763874faf95c0e22ce353b1211a126a1cdace2b3857578e54958a598b656a855485d2756a95bd2b866b4bae2c0697bb8651d0e295a12beba927da9b39d099d6319669a84c1e9e4bd5cc29785b429f13153d1cd778e86f0175fc96d43d40bea19343bf9629a487f22f62e949283bca903809ee912a1b34ef3191dd1365f81d46a8898d83fd90191d820c0beb550617d24dee16bcc3f96b1afdf059e72a84ff1f745e121d294610f4241af5a1c4b4b6280e119c0bb2aabc0c5eca9e037bd55274bf196344c4bc52ee57daa3aba56cfcb51c6af8f07bc48a506e451dcc3fe66a6d0dc495aed3c98aaae1f08ff2167e284bd45f96c6e2629599a8eddf6f96f3ea7bf896a4997f692c033e34479d7b480f8c5ac1df57cb8e322c43f6349c9e0adfbdd7e4e199309cae86fd5845b362d9be8549066e3cef64e0ec9eb13e9946f56b497d8752c457088b8939cc2eb3dcd25c31f62088e14ea32663d815ea1c4628f35a918ae2998eabeb2dec22ec33f1286cf5305b7e554d53afb4a2edf21a1f34c820a44f77ae49daf71f1bf42b61dbde8fa73688e13b389040ed1bf6fe978dd096f218120fa06aa7700000011419a246c43bffea996085f105a5dd90e38000000c1419e4278857fd55ff9141fffc7f55189ce22c8a1caf384806e209d74d9c176c6a5a29aef5d3f2bcc83b2d40093725db545277faf66bfd0206d86e5f82884fb3d2dd0eff79eee0be90ec51854bf2baee2c5c80094af36e5cd006dfd97de760bb5843f9a424c5ce6e4737c59f6b1c15deb6f31d5652cd0e65486f54cbacb5e390e07873e96aeca2d3bce44dc4d08734ffb5934aa43c27edf02c09547e55bcfc9e083d947ca2fc694d744e8c01ce265e180bc4ecec7ea72f672de9ff4584b534aeb3b00000010019e6174427ff75f20c0653681ea8cf000000021019e636a427ff5f690916542f15dc8dafb0d7b38b0f35db5ac4726a711d55a285d00000012419a6849a84168994c0877fffea99600c48100000024419e8645112c2bfff64427732d9057f588a36bfc7ef8ca25c45db97faf353dfd151cd6290000000d019ea574427ff75f20bde7f57d0000000b019ea76a427ff5f690588400000012419aac49a8416c994c0877fffea99600c4800000000e419eca45152c2bfff64427692d810000000d019ee974427ff75f20bde7f57d0000000b019eeb6a427ff5f690588400000012419af049a8416c994c0877fffea99600c4810000000e419f0e45152c2bfff64427692d810000000d019f2d74427ff75f20bde7f57d0000000b019f2f6a427ff5f690588400000012419b3449a8416c994c0877fffea99600c4800000000e419f5245152c2bfff64427692d810000000d019f7174427ff75f20bde7f57d0000000b019f736a427ff5f690588400000012419b7849a8416c994c0877fffea99600c4810000000e419f9645152c2bfff64427692d800000000d019fb574427ff75f20bde7f57d0000000b019fb76a427ff5f690588500000012419bbc49a8416c994c0877fffea99600c4800000000e419fda45152c2bfff64427692d810000000d019ff974427ff75f20bde7f57d0000000b019ffb6a427ff5f690588500000012419be049a8416c994c0877fffea99600c4810000000e419e1e45152c2bfff64427692d800000000d019e3d74427ff75f20bde7f57d0000000b019e3f6a427ff5f690588500000012419a2449a8416c994c0877fffea99600c4800000000e419e4245152c2bfff64427692d810000000d019e6174427ff75f20bde7f57d0000000b019e636a427ff5f690588500000011419a6849a8416c994c086ffffea78401830000000e419e8645152c2bfff64427692d810000000d019ea574427ff75f20bde7f57d0000000b019ea76a427ff5f690588400000011419aac49a8416c994c086ffffea78401830000000e419eca45152c2bfff64427692d810000000d019ee974427ff75f20bde7f57d0000000b019eeb6a427ff5f690588400000011419af049a8416c994c086ffffea78401830000000e419f0e45152c2bfff64427692d810000000d019f2d74427ff75f20bde7f57d0000000b019f2f6a427ff5f690588400000011419b3449a8416c994c086ffffea78401830000000e419f5245152c2bfff64427692d810000000d019f7174427ff75f20bde7f57d0000000b019f736a427ff5f690588400000011419b7849a8416c994c085ffffe8cb005ed0000000e419f9645152c2bfff64427692d800000000d019fb574427ff75f20bde7f57d0000000b019fb76a427ff5f690588500000017419bbb4ba842105b208c06f1101bc80213fffdf10037a000000010419fd945152c27fff5f6905ef0c731810000000d019ffa6a427ff34920bdd584e7000005f06d6f6f760000006c6d766864000000000000000000000000000003e8000007d000010000010000000000000000000000000100000000000000000000000000000001000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000020000051b7472616b0000005c746b68640000000300000000000000000000000100000000000007d000000000000000000000000000000000000100000000000000000000000000000001000000000000000000000000000040000000008000000080000000000024656474730000001c656c73740000000000000001000007d00000040000010000000004936d646961000000206d64686400000000000000000000000000003c000000780055c400000000002d68646c72000000000000000076696465000000000000000000000000566964656f48616e646c6572000000043e6d696e6600000014766d68640000000100000000000000000000002464696e660000001c6472656600000000000000010000000c75726c2000000001000003fe7374626c000000ae7374736400000000000000010000009e61766331000000000000000100000000000000000000000000000000008000800048000000480000000000000001144c61766336312e332e313030206c69627832363400000000000000000000000018ffff00000034617663430164000bffe100176764000bacd942046840000003004000000f03c50a658001000668ebe3cb22c0fdf8f800000000146274727400000000000029b4000029b4000000187374747300000000000000010000003c000002000000001473747373000000000000000100000001000001e863747473000000000000003b00000001000004000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a00000000010000040000000001000000000000000100000200000000010000080000000002000002000000001c737473630000000000000001000000010000003c00000001000001047374737a00000000000000000000003c0000056100000015000000c500000014000000250000001600000028000000110000000f0000001600000012000000110000000f0000001600000012000000110000000f0000001600000012000000110000000f0000001600000012000000110000000f0000001600000012000000110000000f0000001600000012000000110000000f0000001600000012000000110000000f0000001500000012000000110000000f0000001500000012000000110000000f0000001500000012000000110000000f0000001500000012000000110000000f0000001500000012000000110000000f0000001b0000001400000011000000147374636f0000000000000001000000300000006175647461000000596d657461000000000000002168646c7200000000000000006d6469726170706c0000000000000000000000002c696c737400000024a9746f6f0000001c6461746100000001000000004c61766636312e312e313030", "contentstr": "", "contenthash": "9de52e1e280173e07081ec095b675e4d7b8854b705bc195037b3574cdc016082", "contentlength": "4237", "createdat": "2024-11-21T05:39:39.230Z" } ] } ``` {% endtab %} {% endtabs %} # Check Rare Sats Inventory Use this endpoint to check any rare, special, vintage sats available to be used in individual or collection inscriptions. ## Check Rare Sats Inventory `GET` `https://api.ordinalsbot.com/inventory` Check for available special sats that are available to be inscribed on. This endpoint will return their available count, price and max file size that can be handled. Each property can be used as input when creating inscription orders, for instance: `rareSats: block9` {% tabs %} {% tab title="200: OK Normal Response" %} ```json { "black": { "amount": 42609880, "baseFee": 40000, "commonCount": 135, "count": 152, "maxSize": 5000000, "minSize": 546 }, "block286": { "amount": 24424386, "baseFee": 1000, "commonCount": 110, "count": 58, "maxSize": 5000000, "minSize": 1003 }, "block78": { "amount": 50639419, "baseFee": 5000, "commonCount": 116, "count": 61, "maxSize": 5000000, "minSize": 865 }, "block9": { "amount": 44980304, "baseFee": 10000, "commonCount": 156, "count": 49, "maxSize": 5000000, "minSize": 1003 }, "block9450x": { "amount": 107593233, "baseFee": 10000, "commonCount": 136, "count": 76, "maxSize": 5000000, "minSize": 1001 }, "block999": { "amount": 61977315, "baseFee": 10000, "commonCount": 169, "count": 52, "maxSize": 5000000, "minSize": 400 }, "hitman": { "amount": 60275513, "baseFee": 5000, "commonCount": 199, "count": 138, "maxSize": 5000000, "minSize": 586 }, "jpeg": { "amount": 34628652, "baseFee": 5000, "commonCount": 98, "count": 94, "maxSize": 5000000, "minSize": 543 }, "legacy": { "amount": 10500000, "baseFee": 5000, "commonCount": 44, "count": 0, "maxSize": 5000000, "minSize": 100000 }, "nakamoto": { "amount": 61662759, "baseFee": 5000, "commonCount": 185, "count": 524, "maxSize": 5000000, "minSize": 553 }, "pizza": { "amount": 107901654, "baseFee": 2500, "commonCount": 379, "count": 156, "maxSize": 5000000, "minSize": 839 }, "silkroad": { "amount": 11011389, "baseFee": 5000, "commonCount": 48, "count": 10, "maxSize": 5000000, "minSize": 1000 }, "uncommon": { "amount": 75441924, "baseFee": 80000, "commonCount": 98, "count": 2, "maxSize": 5000000, "minSize": 546 }, "vintage": { "amount": 75494656, "baseFee": 9000, "commonCount": 136, "count": 65, "maxSize": 5000000, "minSize": 878 } } ``` {% endtab %} {% tab title="200: OK Error Response with Cause" %} ``` { status: 'error', error: 'error reason' } ``` {% endtab %} {% tab title="500: Internal Server Error Server side error" %} ``` { status: 'error', reason: 'server error' } ``` {% endtab %} {% endtabs %} # Referral Scheme ## Getting Referral Earnings {% hint style="success" %} Remember you can always earn referral commissions without using the API. Just share your referral linkArray of transaction outputs to be accelerated in the following format
\[ "430901147831e41111aced3895ee4b9742cf72ac3cffa132624bd38c551ef379:0"
]
Utxo that includes the inscription to be burned at the 0th sat location.
- For BRC20, this would be a transfer inscription
- For BRC20PROG, this would be a contract deploy inscription
Transaction output should be in the following format"507d20a8db517abff4a3558e15f392ac4a7774f7d25c02fe6ec5ff6ca9df4ad2:0"asd
Note: Ensure utxo being burned has enough postage to cover the burn transaction fees + changeAmount. Recommended size: 10000 sats.
Amount of sats being burned in the OP\_RETURN outputmin: 1, max: 10000
Amount of sats being sent back to "paymentAddress" in the burn transaction.min: 330
Burned Rune and Inscription with Metadata
| 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
|
| 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 If supplied, An object that includes: offset: (object, optional) object with required fields height: (object, optional) object with required fields |
| 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! |
| Name | Type | Description |
|---|---|---|
| rune* | String | Rune name |
| receiveAddress* | String | A single Bitcoin address to receive the rune balance for the whole order |
| fee* | Number | Miner fee that will be paid while inscribing the ordinals in sats/byte. |
| numberOfMints | Number | Number of times provided rune should be minted to receive address. (default=1) |
| 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. |
| postage | Number | Set custom postage for the order's asset: minimum 330 sats, maximum 10,000 sats. (default=546) |
| Name | Type | Description |
|---|---|---|
| runeName* | String | Rune name to mint |
| minterAddress* | String | A Bitcoin address to pay order and receive the rune balance |
| feeRate* | Number | Miner fee that will be paid while inscribing the ordinals in sats/byte. |
| mintCount* | Number | Number of times provided rune should be minted to receive address. |
| sendAddress | String | (Optional) Address that will receive the rune mint. If not set minterAddress is the default value |
| simulateFee | Boolean | (Optional) If true, only fee information will be returned and no order will be created. Default is false |
| Name | Type | Description |
|---|---|---|
| orderId* | String | Order id obtained in the previous step |
| psbt* | String | base64 string containing a fully signed PSBT |
| Name | Type | Description |
|---|---|---|
| id* | String | Human-readable launchpad id |
| rune* | String | The name of rune you want to sell (with spacers) |
| creatorAddress* | String | The bitcoin address where we will send the proceeds from the sale |
| saleSize* | Number | We will sell this many tokens per batch (equivalent to terms.amount in runestone) |
| salesCap* | Number | The number of available batches for sale (equivalent to terms.cap in runestone) |
| totalTokensForSale* | Number | The total amount of tokens that are available for sale on the launchpad. Must equal saleSize * salesCap |
| price* | Number | Price per token |
| splittingFee* | Number | Chain fee in sat/vb for the splitting transaction required before starting the launchpad |
| publicAllocation | Number | Publicly available allocation of tokens |
| allowList | Object | The allowlist |
| accessRules | Array | Array of objects that set rules on who can claim tokens from the launchpad. e.g. [{"api": "brc20", "token": "TRIO", "allocation":10}] This will check user address balance for brc20 TRIO tokens and allow them to claim 10 rune launchpad tokens per TRIO they hold. |
| metadata | Object | Any metatada you wish for your collection you can pass it as any type of JS object here. Max size 10kb. |
| Name | Type | Description |
|---|---|---|
| id* | String | The launchpad id |
| count* | Number | How many items you want to mint |
| fee* | Number | The chain fee per vbyte for the order |
| receiveAddress* | String | Address to send the minted runes |
| referral | String | Referral code to earn up to %15 of the order base 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 saleMultiplier. |
| webhookUrl | String | Webhook URL to receive a POST payload for order updates. Refer to Webhooks for format of the webhook payload. |
| postage | Number | Set custom postage for the order's asset: minimum 330 sats, maximum 10,000 sats. (default=546) |
{
"runeName": "RuneName",
"psbts": [
"cHNidP8BAHECAAAAAfPQ0OTWpSxwRJK..."
],
"orderType": "rune-airdrop",
"id": "76d1a25b-1e56-4476-8a98-d248f1ab5f95",
"status": "ok",
"state": "queued",
"createdAt": {
".sv": "timestamp"
}
}
### `POST` Create a new marketplace ## Create Marketplace `POST` `https://api.ordinalsbot.com/marketplace/create-marketplace` API Key is required in the header: `headers: { 'x-api-key': '
Fees that will be charged to the buyer when an ordinal is sold on the marketplace. Fees should be specified in basis points for example 10% would be 1000
| | btcFeePayoutAddress | String | The address for paying out marketplace fees | | name\* | String | Name for the marketplace | | url | String | URL for the marketplace | | description | String | Short description for the marketplace | | launchpadBuyerFee | Number | Fees that will be charged to the buyer when buying from launchpad. Fees should be specified in basis points for example 10% would be 1000 | | launchpadSellerFee | Number | Fees that will be charged to the seller when an inscription is listed on launchpad. Fees should be specified in basis points for example 10% would be 1000 | | launchpadBtcFeePayoutAddress | String | The address for paying out launchpad fees | {% tabs %} {% tab title="200: OK " %} ```json { "marketPlaceId": "123abce79a817d55d0e7123", // your new marketplace id "apiKey": "366e7416-9e95-459f-bee9-fe8abbf4591b" // the api key you provided } ``` {% endtab %} {% tab title="500: Internal Server Error " %} ```json { status: 'error', error: 'error reason' } ``` {% endtab %} {% endtabs %} # Update a Marketplace Update details of an existing marketplace {% hint style="info" %} An API Key is required to interact with MarketPlace APIs. Please contact us to get an API Key and get started. {% endhint %} Use this endpoint to update a previously created Marketplace.### `POST` Update a marketplace ## Update Marketplace `POST` `https://api.ordinalsbot.com/marketplace/update-marketplace` API Key is required in the header: `headers: { 'x-api-key': '
Fees that will be charged to the buyer when an ordinal is sold on the marketplace. Fees should be specified in basis points for example 10% would be 1000
| | btcFeePayoutAddress | String | The address for paying out marketplace fees | | name | String | Name for the marketplace | | url | String | URL for the marketplace | | description | String | Short description for the marketplace | | launchpadBuyerFee | Number | Fees that will be charged to the buyer when buying from launchpad. Fees should be specified in basis points for example 10% would be 1000 | | launchpadSellerFee | Number | Fees that will be charged to the seller when an inscription is listed on launchpad. Fees should be specified in basis points for example 10% would be 1000 | | launchpadBtcFeePayoutAddress | String | The address for paying out launchpad fees | {% tabs %} {% tab title="200: OK " %} ```json { "marketPlaceId": "123abce79a817d55d0e7123", // your new marketplace id "apiKey": "366e7416-9e95-459f-bee9-fe8abbf4591b" // the api key you provided } ``` {% endtab %} {% tab title="500: Internal Server Error " %} ```json { status: 'error', error: 'error reason' } ``` {% endtab %} {% endtabs %} # List ordinals for sale This endpoint is used to list one or more ordinals for sale on the marketplace. The endpoint returns a Partially Signed Bitcoin Transaction (PSBT) which the owner must sign. If someone buys the ordinal, the buyer must supply the unspent transaction output (UTXO) covering the ordinal's price and any applicable fees. The seller's signature is required only during the initial listing, while only the buyer's signature is necessary for completing the purchase.\ \ **Platform Cost:** \ A platform fee is applied only when an ordinal is sold. It is not charged for listing an ordinal. The current fee is 1% of sale amount charged to the seller. The response from this endpoint is a PSBT, encoded in base64, which the Ordinal owner's wallet needs to sign. Here's an example of how you can sign a listing transaction with the Xverse wallet:```javascript // XVerse Wallet example of creating a signing request // when listing an Ordinal for sale const sellerInput = { address: ordinalsAddress, // Seller's ordinal wallet address signingIndexes: [0], // always [0] when listing // Specify sigHash type as SIGHASH_SINGLE | SIGHASH_ANYONECANPAY sigHash: bitcoin.Transaction.SIGHASH_SINGLE | bitcoin.Transaction.SIGHASH_ANYONECANPAY, }; // Create the listing PSBT by calling /marketplace/create-listing API // This returns a base64 PSBT in string format which needs to be signed const { data } = await axios({ method: 'post' url: 'https://api.ordinalsbot.com/marketplace/create-listing', data: { sellerOrdinals sellerPaymentAddress, sellerOrdinalPublicKey }, headers: { 'x-api-key': API_KEY, }); // When using XVerse Wallet // Create the payload for signing the seller transaction const payload = { network: { type: "Mainnet" }, message: "Sign Seller Transaction", psbtBase64: data.psbt, // PSBT returned by the clear-listing API broadcast: false, inputsToSign: [sellerInput], }; // Make signing request await signTransaction({ payload, onFinish: async (response) => { try { // signed succesffully // Save the listing with the signed PSBT const updateListingData = { signedListingPSBT: response.psbtBase64, }; // Save the listing PSBT by calling /marketplace/save-listing API // This saves the signed PSBT const saveResponse= await axios({ method: 'patch' url: 'https://api.ordinalsbot.com/marketplace/save-listing' + sellerOrdinals[0].id, data: { ordinalId: sellerOrdinals[0].id, updateListingData }, headers: { 'x-api-key': API_KEY, } }); } catch (Error) { // error handling } }, onCancel: () => { // User cancelled signing request } }); ``` ### `POST` List a new ordinal for sale ## List a Ordinal for sale `POST` `https://api.ordinalsbot.com/marketplace/create-listing` API Key is required in the header: `headers: { 'x-api-key': '
An array with one or more objects. The object should include:
id:string; => Ordinal id for the ordinal to be listed for sale.
price:number | string; => Sale price of the ordinal in Sats.
| | sellerPaymentAddress | String | The address to receive the sale proceeds when the ordinal is sold. This will be part of the sale transaction that the buyer will sign. | | | sellerOrdinalPublicKey | String | The public key for the wallet address that owns the ordinal being listed for sale | | {% tabs %} {% tab title="200: OK " %} ```json { "psbt": "cHNidP1BAP15AQIAAAAE1K5...........", // base64 transaction to be signed } ``` {% endtab %} {% tab title="500: Internal Server Error " %} ```json { status: 'error', error: 'error reason' } ``` {% endtab %} {% endtabs %} # Save listing Save listing is part of the create listing process. create-listing end point returns a psbt which is signed by the client wallet, once signed the signed psbt needs to be saved in the listing database by calling /save-listing end point. Here's an example of how you can sign a listing transaction with the Xverse wallet and then save it by calling /save-listing:```javascript // XVerse Wallet example of creating a signing request // when listing an Ordinal for sale const sellerInput = { address: ordinalsAddress, // Seller's ordinal wallet address signingIndexes: [0], // always [0] when listing // Specify sigHash type as SIGHASH_SINGLE | SIGHASH_ANYONECANPAY sigHash: bitcoin.Transaction.SIGHASH_SINGLE | bitcoin.Transaction.SIGHASH_ANYONECANPAY, }; // Create the listing PSBT by calling /marketplace/create-listing API // This returns a base64 PSBT in string format which needs to be signed const { data } = await axios({ method: 'post' url: 'https://api.ordinalsbot.com/marketplace/create-listing', data: { sellerOrdinals sellerPaymentAddress, sellerOrdinalPublicKey }, headers: { 'x-api-key': API_KEY, }); // When using XVerse Wallet // Create the payload for signing the seller transaction const payload = { network: { type: "Mainnet" }, message: "Sign Seller Transaction", psbtBase64: data.psbt, // PSBT returned by the clear-listing API broadcast: false, inputsToSign: [sellerInput], }; // Make signing request await signTransaction({ payload, onFinish: async (response) => { try { // signed succesffully // Save the listing with the signed PSBT const updateListingData = { signedListingPSBT: response.psbtBase64, }; // Save the listing PSBT by calling /marketplace/save-listing API // This returns a base64 PSBT in string format which needs to be signed const saveResponse= await axios({ method: 'patch' url: 'https://api.ordinalsbot.com/marketplace/save-listing' + sellerOrdinals[0].id, data: { sellerOrdinals: [sellerOrdinals[0].id], updateListingData }, headers: { 'x-api-key': API_KEY, } }); } catch (Error) { // error handling } }, onCancel: () => { // User cancelled signing request } }); ``` ### `POST` Save listing data for ordinal ## Save listing details `POST` `https://api.ordinalsbot.com/marketplace/save-listing/` API Key is required in the header: `headers: { 'x-api-key': '
json object with a string signedListingPSBT.
Ex:
{
sellerOrdinals: \["0c9...ai0"],
updateListingData: {
signedListingPSBT:
"cHNidP8...AAA"
}
}
| | sellerOrdinals\* | Array | Array of ordinal Ids. The ids should be the same as ordinals ids used with /create-listing endpoint | {% tabs %} {% tab title="200: OK " %} ```json { "_id": "7354826c46a5856b972795d7", "ordinalId": "8dc4e.....6ce70260i0", "price": 12345, "sellerPaymentAddress": "3Ny......yc4q", "sellerOrdinalPublicKey": "4fa4.....118fad4e476541", "status": "Active", "sellerOutputValue": 21111, "ordinalUtxoTxId": "3362....61449ef", "ordinalUtxoVout": 0, "marketPlaceMakerFee": 0, "marketPlaceTakerFee": 0, "platformMakerFee": 1000, "platformTakerFee": 1000, "signedListingPSBT": "cHNid......1rARj61OR2VBAAA=" } ``` {% endtab %} {% tab title="500: Internal Server Error " %} ```json { status: 'error', error: 'error reason' } ``` {% endtab %} {% endtabs %} # Delete Listing This endpoint deletes an existing marketplace listing. This endpoint can be used to delete an ordinal listing from the marketplace. Deleting a listing requires the seller to create a transaction by calling `/delist` sign the transaction and then need to send the signed transaction by making a call to `/confirm-delist` , the signed transaction transfers the ordinal to the seller so that the original ordinal UTXO is consumed and not valid anymore. This is to ensure that the old, signed transaction cannot be used anymore to buy the ordinal.### `POST` Delete Listing `POST` `https://testnet-api.ordinalsbot.com/marketplace/delist` API Key is required in the header: `headers: { 'x-api-key': '
```typescript 'Sold', // Ordinals that have been sold 'Active', // Ordinals still available for sale 'Inactive', // Ordinals that have been marked as not available for sale by admin 'Pending Buyer Confirmation', // Ordinals where buyer has initiated purchase but not completed the sign and broadcast part of the process 'Pending Seller Confirmation', // Ordinals where seller has initiated listing but not completed the sign and save part of the process ``` Pagination and sorting options can be specified by adding `itemsPerPage` , `page` and `sort`\ values in the request body. By default results are sorted by listing time.\ Response provides an array of ordinals as well as information on current page and total ordinals for the specified search filter.\ \ Response structure: ```typescript { results: [{},{},{},{}], // array of Ordinal listings count: 0, // number of Ordinals in the current results array currentPage: page, // current page number totalPages: 0, // total pages that can be returned for the current search results totalItems: 0 // total items in the database for the current search results } ``` Here's an example of a call to get the 3rd page of all sold Ordinals sorted by time:
const LISTING_STATUS = {
sold: 'Sold',
active: 'Active',
inactive: 'Inactive',
pending_buyer_confirmation: 'Pending Buyer Confirmation',
pending_seller_confirmation: 'pending Seller Confirmation',
}
// Call /get-listing end point to get all Ordinals available for sale
// by default only available ordinals are returned
const { data } = await axios({
method: 'post'
url: 'https://api.ordinalsbot.com/marketplace/get-listing',
headers: {
'x-api-key': API_KEY,
});
// Call /get-listing end point to get all Ordinals that have been sold
const { data } = await axios({
method: 'post'
url: 'https://api.ordinalsbot.com/marketplace/get-listing',
data: {
filter: {
status: LISTING_STATUS.sold
},
page: 3,
itemsPerPage: 50,
sort: "time"
}
headers: {
'x-api-key': API_KEY,
});
An object with status or any other fields to filter
example
{ "status":"Sold" }
{
results: [
{
"_id": "7354826c46a5856b972795d7",
"ordinalId": "8dc4e.....6ce70260i0",
"price": 12345,
"sellerPaymentAddress": "3Ny......yc4q",
"sellerOrdinalPublicKey": "4fa4.....118fad4e476541",
"status": "Active",
"sellerOutputValue": 21111,
"ordinalUtxoTxId": "3362....61449ef",
"ordinalUtxoVout": 0,
"marketPlaceMakerFee": 0,
"marketPlaceTakerFee": 0,
"platformMakerFee": 1000,
"platformTakerFee": 1000,
"__v": 0,
"signedListingPSBT": "cHNid......1rARj61OR2VBAAA="
},
{
"_id": "1835526c46a5856b972795d7",
"ordinalId": "1dc4e.....6ce70260i0",
"price": 12345,
"sellerPaymentAddress": "3Ny......yc2a",
"sellerOrdinalPublicKey": "4fa4.....118fad4e476541",
"status": "Active",
"sellerOutputValue": 21111,
"ordinalUtxoTxId": "3362....61449ef",
"ordinalUtxoVout": 0,
"marketPlaceMakerFee": 0,
"marketPlaceTakerFee": 0,
"platformMakerFee": 1000,
"platformTakerFee": 1000,
"__v": 0,
"signedListingPSBT": "cHNid......1rARj61OR2VBAAA="
},
],
count: 2, // number of Ordinals in the current results array
currentPage: 3, // current page number
totalPages: 3, // total pages that can be returned for the current query
totalItems: 102 // total items for the current search query
}
```javascript // XVerse Wallet example of creating a signing request // when buying an Ordinal // Create the purchase PSBT by calling /marketplace/create-offer const { data } = await axios({ method: 'post' url: 'https://api.ordinalsbot.com/marketplace/create-offer', data: { ordinalId: id, buyerPaymentAddress: paymentAddress, buyerOrdinalAddress: ordinalsAddress, buyerPaymentPublicKey: paymentPublicKey }, headers: { 'x-api-key': API_KEY, }); // returned response has a base64 encoded psbt to sign and an array of input // indices which the buyer needs to sign with the payment address wallet const buyerInput = { address: paymentAddress, // Buyer's payment wallet address signingIndexes: data.buyerInputIndices }; // When using XVerse Wallet // Create the payload for signing the buyer transaction const payload = { network: { type: "Mainnet" }, message: "Sign Buyer Transaction", psbtBase64: data.psbt, broadcast: false, inputsToSign: [buyerInput], }; // Make signing request await signTransaction({ payload, onFinish: async (response) => { try { // Here make a call to /submit-offer // Things to do after successful signing } catch (Error) { // error handling } }, onCancel: () => { // User cancelled signing request } }); ``` ### `POST` Buy an ordinal ## Buy a listed ordinal `POST` `https://api.ordinalsbot.com/marketplace/create-offer` API Key is required in the header: `headers: { 'x-api-key': '
Transaction fee rate should be one of the following. Defaults to fastestFee if not specified:
fastestFee
halfHourFee
hourFee
minimumFee
Transaction fee rate should be one of the following. Defaults to fastestFee if not specified:
fastestFee
halfHourFee
hourFee
minimumFee
### `POST` Transfer one or more Ordinals ## Transfer one or more ordinals `POST` `https://api.ordinalsbot.com/marketplace/transfer-ordinals` API Key is required in the header: `headers: { 'x-api-key': '
`transfer` is an array with one or more objects. Each object needs an ordinal Id and receiver address.\ \ Example Request Body:\ \ `{`\ `"transfer": [`\ `{`\ `"ordinalId": "5f251...b9i0",`\ `"receiverOrdinalAddress": "tb1...yk3"`\ `},` `{`\ `"ordinalId": "2a920...c0i0",`\ `"receiverOrdinalAddress": "tb1...ze2"`\ `}`\ `],`\ `"senderPaymentAddress": "2N6Z...bKL",`\ `"senderPaymentPublicKey": "0335...c05",`\ `"senderOrdinalPublicKey": "e581...a26"`\ `}` \ This will return a PSBT. The PSBT has to be signed and broadcast. #### Request Body | Name | Type | Description | | -------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------- | | sellerOrdinalPublicKey\* | String | The public key for the wallet address that owns the ordinal | | transfer\* | Array | An array of objects. Each object should have an id for the ordinal and an address for the receiver of that ordinal. | | sellerPaymentAddress\* | String | Payment wallet address for the seller, this wallet address will receive the payment the ordinal is sold | | senderPaymentPublicKey\* | String | The public key for the payment wallet, this will be used for fees | {% tabs %} {% tab title="200: OK " %} ```json { "psbtBase64": "cHNidP8BA…yzcAAAAAAA==", "senderOrdinalInputs": [ 0, 1 ], "senderPaymentInputs": [ 2 ] } ``` {% endtab %} {% tab title="500: Internal Server Error " %} ```json { status: 'error', error: 'error reason' } ``` {% endtab %} {% endtabs %} # Create Marketplace {% hint style="info" %} An API Key is required to interact with Launchpad APIs. Please contact us to get an API Key and get started. {% endhint %} Use this endpoint to register a new Marketplace. Having a marketplace registered allows the marketplace to specify marketplace fees and launchpad fees for buying and selling ordinals. Marketplace fees are paid out when an ordinal is sold. Fees are transferred to the address specified in a trustless way as part of the purchase transaction. This endpoint can also be used to specify launchpad configuration to create a launchpad. marketplace fees and launchpad fees are separate
### `POST` Create a new marketplace ## Create Marketplace `POST` `https://api.ordinalsbot.com/legacy-marketplace/create-marketplace` API Key is required in the header: `headers: { 'x-api-key': '
Fees that will be charged to the buyer when an ordinal is sold on the marketplace. Fees should be specified in basis points for example 10% would be 1000
| | btcFeePayoutAddress | String | The address for paying out marketplace fees | | name\* | String | Name for the marketplace | | url | String | URL for the marketplace | | description | String | Short description for the marketplace | | launchpadBuyerFee | Number | Fees that will be charged to the buyer when buying from launchpad. Fees should be specified in basis points for example 10% would be 1000 | | launchpadSellerFee | Number | Fees that will be charged to the seller when an inscription is listed on launchpad. Fees should be specified in basis points for example 10% would be 1000 | | launchpadBtcFeePayoutAddress | String | The address for paying out launchpad fees | {% tabs %} {% tab title="200: OK " %} ```json { "marketPlaceId": "123abce79a817d55d0e7123", // your new marketplace id "apiKey": "366e7416-9e95-459f-bee9-fe8abbf4591b" // the api key you provided } ``` {% endtab %} {% tab title="500: Internal Server Error " %} ```json { status: 'error', error: 'error reason' } ``` {% endtab %} {% endtabs %} # Create a new Launchpad {% hint style="info" %} An API Key is required to interact with Launchpad APIs. Please contact us to get an API Key and get started. A Marketplace is required to create a new launchpad as it'll inherit fees from it. {% endhint %} Use this endpoint to create a new launchpad.\ To create a new launchpad ids for all the preinscribed inscriptions along with other launchpad related data including allowlst and phases needs to be provided to the create launch endpoint. This initiates the launchpad creation and creates a partially signed bitcoin transaction(PSBT) which needs to be signed by the wallet that has all the pre inscribed inscriptions. ### `POST` /launchpad/create-launch `POST` `https://api.ordinalsbot.com/launchpad/create-launch` API Key is required in the header: `headers: { 'x-api-key': 'The public key for the wallet address that owns all the inscriptions to be listed on the launchpad
| | phases | Array | An array of Phase objects each containing details about each phase of the launch | ### Phase Object | Name | Type | Description | | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ordinals | Array | An array of ordinal IDs in string format | | allowlist | Object | Mapping of addresses to their allocations. | | isPublic | Boolean | Whether the phase is public or private. Public is open to everyone without the need for an allowlist | | price | number | Price for this phase for each inscription in sats | | startDate | number | Start timestamp for the phase. | | endDate | number | End timestamp for the phase. | | metaData | String | Stringified Object with key value pairs. Properties for the launchpad like name description image links etc any launchpad specific key value properties can be stored in metaData. | {% tabs %} {% tab title="200: OK " %} ```json // Response has the the launchpd id and the status // status is pending while the psbt is being created // Once psbt is ready status will change to pending confirmation { "launchpadId": "65a123b789cdef0123456789", "status": "pending" } ``` {% endtab %} {% tab title="500: Internal Server Error " %} ```json { status: 'error', error: 'error reason' } ``` {% endtab %} {% endtabs %} # Retrieve Launch PSBT {% hint style="info" %} An API Key is required to interact with Launchpad APIs. Please contact us to get an API Key and get started. {% endhint %} Use this endpoint to retrieve the PSBT. If PSBT is not ready a pending status will be returned. When the psbt is ready, the psbt to be signed is returned along with a pending confirmation status. The PSBT needs to be signed by the wallet that owns all the pre inscribed inscriptions. ### `POST` /launchpad/get-launch-psbt/:launchpadId `GET` `https://api.ordinalsbot.com/launchpad/get-launch-psbt/:launchpadId` API Key is required in the header: `headers: { 'x-api-key': '| Name | Type | Description |
|---|---|---|
| String | launchpad id returned by the create launch api |
| String | The signed PSBT |
| Name | Type | Description |
|---|---|---|
| String | Launchpd id |
| String | Wallet address of a prospective buyer |
The ordinal address of the buyer, this address should also be in the allowlist of the active phase
| | buyerPaymentAddress | String | The payment wallet address of the buyer | | buyerPaymentPublicKey | String | The Payment public key of the buyer payment wallet address | {% tabs %} {% tab title="200: OK " %} ```json // Returns phase and launch info along with a unsigned PSBT { "phase": { "_id": "65a123b789cdef0123456790", "isPublic": false, "price": 6000, "startDate": "1234123432", "endDate": "1234923432" }, "ordinalId": "8f46149faff54a7efe0c5c73a633077a8009b374ebcf6d80609807eab8d73218i0", "launchpadPhase": "65a123b789cdef0123456790", "buyerInputIndices": [0, 1], "psbt": "cHNidP8BAHECAAAAAfPQ0OTWpSxwRJK...", "psbtHex": "70736..." } ``` {% endtab %} {% tab title="500: Internal Server Error " %} ```json { status: 'error', error: 'error reason' } ``` {% endtab %} {% endtabs %} # Confirm buy offer {% hint style="info" %} An API Key is required to interact with Launchpad APIs. Please contact us to get an API Key and get started. {% endhint %} This endpoint completes the purchase of an inscription. This requires the signed psbt from /create-launch-offer end point. Which is a psbt signed by the buyer and base64 encoded. This returns a transaction id for the ordinal sale transaction.\ \ The PSBT will only be created and returned for an active launchpad and only if the ordinal address of the buyer has an available allocation to buy in the currently active phase. ### `POST` /launchpad/submit-launch-offer `POST` `https://api.ordinalsbot.com/launchpad/submit-launch-offer` API Key is required in the header: `headers: { 'x-api-key': 'The PSBT signed by the buyer's payment wallet
| {% tabs %} {% tab title="200: OK " %} ```json // Returns transaction id { "txId": "2c8e7ec23d8b4f91e98034b288721b9b7d0eb14d618bef59fe238b5023a4a34a" } ``` {% endtab %} {% tab title="500: Internal Server Error " %} ```json { status: 'error', error: 'error reason' } ``` {% endtab %} {% endtabs %} # Get Launch Info {% hint style="info" %} An API Key is required to interact with Launchpad APIs. Please contact us to get an API Key and get started. {% endhint %} This endpoint returns launchpad information ### `GET` /launchpad/get-launch-stats `GET` `https://api.ordinalsbot.com/launchpad/get-launch-stats/:launchpadId` API Key is required in the header: `headers: { 'x-api-key': 'If set to true the response will contain ONLY the special ranges.
This is useful when you have a popular address with too many common ranges and you are not interested in them or the response is too big.
| #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | x-api-key\* | String | API Key | {% tabs %} {% tab title="200: OK The ranges and special ranges for the address" %} ```javascript { "result": { "inscriptions": [ { "output": "5c647ddc974d3f116093995a1cf8ac8ade10ed4f255bb3c4baf6435c5fb073d5:2", "inscriptions": [ "8ba8e1c2cf89413d94d6423032495c879435b2cde2c9fa1580d7f8dd7949e6a8i0" ] }, { "output": "e3dd6ed7324c5df96206f91dc43deabc6fc6fdc1692d8f4a91efc5724fddd6b7:2", "inscriptions": [ "f7664e7e746df85704f71c3f7fbe6bcaa5b8626d82b5268d637a26889d42df22i0" ] } ], "ranges": [ { "output": "5c647ddc974d3f116093995a1cf8ac8ade10ed4f255bb3c4baf6435c5fb073d5:2", "start": 1183905505897907, "end": 1183905505898453, "size": 546, "offset": 0, "rarity": "common" }, { "output": "e3dd6ed7324c5df96206f91dc43deabc6fc6fdc1692d8f4a91efc5724fddd6b7:2", "start": 305377150438027, "end": 305377150442477, "size": 4450, "offset": 0, "rarity": "common" } ], "specialRanges": [ { "start": 229634999999999, "output": "f69fc1bea9225b6077af7afd2f2d756b9f173e420c2f7b767435fba9b020b178:0", "size": 1, "offset": 0, "satributes": [ "black" ] } ] } } ``` {% endtab %} {% endtabs %} # Find Special Ranges UTXO Find special sats for the given UTXOs ## Find special sats in the given UTXOs `POST` `https://api.ordinalsbot.com/satscanner/find-special-ranges-utxo` #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | x-api-key\* | String | API Key | #### Request Body | Name | Type | Description | | --------------------------------------- | --------- | ---------------------- | | utxos\* | String\[] | Array of utxos to scan | {% tabs %} {% tab title="200: OK The ranges and special ranges for the address" %} ```javascript { "result": { "inscriptions": [ { "output": "5c647ddc974d3f116093995a1cf8ac8ade10ed4f255bb3c4baf6435c5fb073d5:2", "inscriptions": [ "8ba8e1c2cf89413d94d6423032495c879435b2cde2c9fa1580d7f8dd7949e6a8i0" ] } ], "ranges": [ { "output": "5c647ddc974d3f116093995a1cf8ac8ade10ed4f255bb3c4baf6435c5fb073d5:2", "start": 1183905505897907, "end": 1183905505898453, "size": 546, "offset": 0, "rarity": "common" } ], "specialRanges": [ { "start": 229634999999999, "output": "5c647ddc974d3f116093995a1cf8ac8ade10ed4f255bb3c4baf6435c5fb073d5:2", "size": 1, "offset": 0, "satributes": [ "black" ] } ] } } ``` {% endtab %} {% endtabs %} # Supported Satributes List supported satributes ## Get list all supported satributes `GET` `https://api.ordinalsbot.com/satscanner/supported-satributes` #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | x-api-key\* | String | API Key | {% tabs %} {% tab title="200: OK List of satributes" %} ```javascript { "result": [ "uncommon", "rare", "epic", "legendary", "mythic", "block-9", "block-78", "block-286", "block-666", "block-999", "vintage", "number-palindrome", "pizza", "hitman", "first-transaction", "nakamoto", "black", "legacy", "jpeg" ] } ``` {% endtab %} {% endtabs %} # Extract List supported satributes ## Build an unsigned transaction to extract the special sats in your address `POST` `https://api.ordinalsbot.com/satextractor/extract` #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | x-api-key\* | String | API Key | #### Request Body | Name | Type | Description | | ---------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | scanAddress\* | String | The bitcoin address to scan | | addressToSendSpecialSats\* | String | The address where we will send the special sats | | addressToSendCommonSats\* | String | The address where we will send all of the rest of the bitcoin in the given address | | feePerByte\* | Integer | The fee per byte for the transaction: make sure you use an up-to date fee per byte! | | filterSatributes | String\[] |Array of strings, if supplied we will only detect the selected satributes; Everything else will be sent to the common sats address.
You can get a list of supported satributes on the Supported Satributes endpoint
| {% tabs %} {% tab title="200: OK Transaction hex" %} ```javascript { "specialRanges": [ { "start": 280810779975733, "output": "826fe75c2e9d567baa6bee11160ae265b3007814ecca79299c5bd8338298b5d5:0", "size": 1, "offset": 0, "satributes": [ "pizza" ] } ], "tx": "0200000001d5b5988233d85b9c2979caec147800b365e20a1611ee6baa7b569d2e5ce76f820000000000fdffffff02220200000000000022512044ddb479c1fe1e5c6ca9c2d1b477fcf7eb024e57f5aee10f2507f0c450c47da85c1100000000000016001402b3df8c029274deabfac0ace62f9fddae7dbfca00000000" } ``` {% endtab %} {% endtabs %} # OPI API OPI API endpoints are available to use with an API Key or from allow-listed domains. **Mainnet:** [**https://api.ordinalsbot.com/opi**](https://api.ordinalsbot.com/opi) **Testnet:**| Name | Type | Description |
|---|---|---|
| x-api-key* | String | API Key |
| Name | Type | Description |
|---|---|---|
| x-api-key* | String | API Key |
| Name | Type | Description |
|---|---|---|
| x-api-key* | String | API Key |
| Name | Type | Description |
|---|---|---|
| x-api-key* | String | API Key |
| Name | Type | Description |
|---|---|---|
| x-api-key* | String | API Key |
array:
{ value: number, count: number }
| Array containing split objects | | value\* | number | Value of each UTXO split | | feeRate\* | number | Fee rate in sats/vByte | | publicKey | string | Address associated public key, needed for p2sh only | | excludeUTXOs | array of outpoints ("txid:vout") | Array containing UTXOs not to spend | | ignorePadding | boolean | If true padding outputs (600sats) will be ignored (Default = true) | **Example:** ```json { "inAddress": "tb1qr4...", "outAddress": "tb1qr4sw...", "splits": [ { "value": 600, "count": 2 }, { "value": 1000, "count": 3 } ], "feeRate": "10", "publicKey": "03725d3f189...", "excludeUTXOs": [ "b591b8b5ba6c54ce65bc72ea20a9e0ed4f50eccaaa8669b542932b8687b2ef37:0", "b591b8b5ba6c54ce65bc72ea20a9e0ed4f50eccaaa8669b542932b8687b2ef37:0" ], "ignorePadding": true } ``` **Response** {% tabs %} {% tab title="200" %} ```json { "psbt": "cHNidP8BAJACAAAA..." } ``` {% endtab %} {% tab title="500" %} ``` { "error": "Internal server error" } ``` {% endtab %} {% tab title="400" %} ```json { "error": "Invalid request" } ``` {% endtab %} {% endtabs %} # Inscribe your first Ordinal Coming Soon... # Receiving Payments Creators and developers may earn bitcoin by selling their collections, referring others to the service or creating applications that utilize OrdinalsBot API. ### Payout Frequency Payouts are done every day at 00:00 UTC and is managed through a daily batch run for eligible creators. ### Eligibility Criteria To be eligible for inclusion in the daily batch run, the total accumulated earnings must be at least 200k sats. These earnings can be a combination of the following: • Mint Price • Referral Earnings • Additional Fees (by using `additionalFee` parameter when [creating orders](/api/create-a-direct-inscription-order#create-order)) Please ensure that your combined earnings meet or exceed the **200k sats** threshold to be included in the daily batch payment. These minimums do not apply if you prefer to use a [Lightning Address](http://lightningaddress.com) to receive payouts instantly over Lightning Network. ### Checking Your Earnings {% hint style="info" %} Note that since service fees are dynamic it may not be possible to forecast or list exact earnings in satoshis/bitcoin. The number of created orders with a specific referral code and paid orders are tracked as inscriptions are completed by the platform. {% endhint %} • Accumulated Earnings: You can check your current accumulated earnings by visiting [Referral Scheme](/api/referral-scheme#get-referral-status). • Last Payment: To view the details of the last payment made to you by visiting [Referral Scheme](/api/referral-scheme)and checking `payments` elements. # Ordinals ### What is Ordinal Theory? The Ordinal theory introduces a unique numbering scheme for satoshis, facilitating the tracking and transferring of individual sats. These numbers, aptly called ordinal numbers, are assigned to satoshis in the order they are mined and transferred from transaction inputs to transaction outputs following a first-in-first-out methodology. This numbering scheme hinges on the order in which satoshis are mined, while the transfer scheme relies on the order of transaction inputs and outputs, hence the term "ordinals." What's intriguing about the Ordinal theory is that it operates independently, requiring no separate token, another blockchain, or any modifications to Bitcoin. In essence, it's a concept that is readily applicable in the current Bitcoin environment. ### Ordinal numbers can be represented in various ways: * **Integer notation:** This is simply the ordinal number, assigned according to the sequence in which the satoshi was mined. An example would be 2099994106992659. * **Decimal notation:** This representation includes the block height where the satoshi was mined, along with the offset of the satoshi within the block. An example would be 3891094.16797. * **Degree notation:** This takes a unique form, for example, 3°111094′214″16797‴. * **Percentile notation:** This expresses the satoshi's position in Bitcoin's supply as a percentage. An example would be 99.99971949060254%. * **Name:** This is an encoding of the ordinal number using the characters a through z, like 'satoshi'. Using ordinal numbers as stable identifiers, arbitrary assets such as NFTs, security tokens, accounts, or stablecoins can be attached to satoshis. ### Bitcoin Improvement Proposal The Bitcoin Improvement Proposal (BIP) provides more technical details about the Ordinal theory. The Ordinals project is an open-source initiative developed on [GitHub](https://github.com/bitcoin/bips), which includes a BIP describing the ordinal scheme, an index that interacts with a Bitcoin Core node to track all satoshis, a wallet for making ordinal-aware transactions, and a block explorer for interactive exploration of the blockchain. The project also offers functionalities for inscribing satoshis with digital artifacts and a comprehensive manual. # What is an Ordinal? Ordinals are a revolutionary concept in the world of cryptocurrencies that have gained significant traction since their inception. Developed by Casey Rodarmor, the term "Ordinal" refers to a unique form of data inscription onto Bitcoin, effectively turning the smallest unit of Bitcoin - the satoshi - into a unique digital artifact. A recent phenomenon, this concept leverages the Bitcoin blockchain and became feasible with the launch of the Taproot upgrade in November 2021. ### The Creation of Ordinals The creation of an Ordinal entails the inscription of content data into the witness of a Bitcoin transaction, a process that has been likened to creating non-fungible tokens (NFTs). This unique data inscription system builds upon the 2017 SegWit upgrade, which fixed bugs and laid the groundwork for Layer 2 payment channels like the Bitcoin Lightning Network. \ The Taproot upgrade played a crucial role in making the Ordinals system possible. It combined all parties' public keys in a transaction to create a new public key and used Schnorr signatures to do so. This method enhanced privacy by obscuring transaction inputs on the Bitcoin blockchain and reduced the amount of data needed for transactions, thereby lowering transaction costs. ### Bitcoin Ordinals: The NFTs of Bitcoin Often dubbed the NFTs of the Bitcoin blockchain, Bitcoin Ordinals are units of Bitcoin that have been inscribed with data such as text or images. Unlike conventional NFTs, the value of an Ordinal is not tied to the Satoshi it represents but the information inscribed onto it. The Ordinals Protocol, launched by Rodarmor in January 2023, enabled Bitcoin users to create Ordinals by linking data with individual units of Bitcoin. This protocol leveraged the 2021 Taproot upgrade, which enhanced privacy, security, scalability, and increased the data capacity for each Bitcoin unit to 4MB. Each Ordinal is assigned a unique, sequential number based on the time it is mined, with a numbering system that ranges from 0 to 2,100,000,000,000,000. The timing of its mining and inscription determines the rarity of an Ordinal, with coins minted and inscribed during significant periods deemed collectible. ### How Do Ordinals Differ from Traditional NFTs? Ordinals and traditional NFTs have several differences. First, Ordinals are not tokens but inscriptions on Bitcoin. Second, unlike NFTs that use smart contracts to enable a range of future behaviors, Ordinals do not have this feature. Lastly, Ordinals store their data entirely on-chain, meaning all information is held within the blockchain itself. This contrasts with many NFTs that use off-chain storage networks like IPFS to store their metadata. Although this on-chain storage approach might be slower and potentially more costly, it is completely unchangeable. The creation of an Ordinal involves two steps: creating a taproot output with the inscription content and then spending the output to reveal the inscription content on the blockchain. This content is wrapped in an envelope that doesn't alter the script. The data are inscribed directly into the Bitcoin blockchain, unlike many NFTs which often just contain reference points to off-chain data. The Bitcoin block size is capped at 4MB, which puts a limit on the number of Ordinals that can be created. # Satoshi Rarity The intricate world of Bitcoin is replete with technical nuances and fascinating insights. One area of particular interest is the notion of satoshi rarity, derived from the Ordinal theory that provides a framework for classifying and numbering Bitcoin's smallest unit, the satoshi. Named after the enigmatic founder of Bitcoin, Satoshi Nakamoto, a satoshi is the smallest indivisible unit of a Bitcoin, with one Bitcoin containing 100 million satoshis. Applying Ordinal Theory to this unit, each satoshi is numbered, resulting in what are known as "Ordinals." ### Identifying Unique Satoshis Several factors could make an ordinal, or satoshi, unique. It might have been held by Satoshi Nakamoto themselves, been part of the historic "Pizza Transaction," or carry significance because of its position within Bitcoin's blockchain. The possibilities are diverse and intriguing. ### The Rodarmor Rarity Index Casey Rodarmor, the inventor of Ordinal Theory, introduced a compelling method for identifying unique satoshis. Rodarmor's approach relies on natural, pre-programmed events within Bitcoin's blockchain to classify satoshis into rarity categories. This classification has become popularly known as the "Rodarmor Rarity Index." This index identifies six categories of satoshis based on rarity: * **Common:** These are regular satoshis, excluding the first sat of a block. Over 99% of all satoshis fall into this category. * **Uncommon:** The first satoshi of a block is labeled as "uncommon." As new blocks are mined approximately every 10 minutes, an uncommon satoshi is created in every such event. * **Rare:** This category includes the first satoshi of each difficulty adjustment period, which happens every 2,016 blocks or roughly every two weeks. * **Epic:** This rare breed is the first satoshi of each halving epoch, a phenomenon that occurs every 210,000 blocks, approximately every four years. * **Legendary:** Legendary sats are the first sat of each "cycle." As explained by Rodarmor, "Every six halvings, something magical happens: the halving and the difficulty adjustment coincide. This is called a conjunction, and the time period between conjunctions is a cycle." This event occurs roughly every 24 years, with the first conjunction expected around 2032. * **Mythic:** The first satoshi of the genesis block, the first satoshi ever created, holds this mythical status. Unspendable and unattainable, this is a special category as Satoshi Nakamoto made the first block unspendable. ### Beyond the Rodarmor index As the Rodarmor Rarity Index gains wider recognition, rarity categories such as "Pizza Sats" and "Block 78 Sats" have surfaced, further highlighting the exciting narrative embedded in Bitcoin's intricate blockchain. Here are some other popular rare sats: * **Pizza Sats:** Commemorates a significant event in Bitcoin history. On May 22, 2010, Laszlo Hanyecz, a programmer, bought two Papa John's pizzas with 10,000 Bitcoins, a value today that would be in the hundreds of millions of dollars. The satoshis involved in this transaction are known as "Pizza Sats." They carry historical importance, adding an additional dimension of value beyond their monetary worth. This transaction, one of Bitcoin's first real-world uses, is celebrated annually on Bitcoin Pizza Day. * **Palindrome Sats:** Refers to satoshis whose number can be read the same way backward or forward. An example is the number 2708111118072, taken from block 541. * **Block 9 Sats:** Are the oldest satoshis currently in circulation. * **Block 78 Sats:** Signifies satoshis mined from the first block by Hal Finney, who was the second Bitcoin miner after Satoshi Nakamoto. Block 78 is a pivotal point in Bitcoin's history, marking the first occasion a block was mined by someone other than Nakamoto. This signaled the start of Bitcoin network's broader decentralization and the expansion of Bitcoin mining. As a result, these satoshis, known as Block 78 Sats occupy a special spot in the historical evolution of Bitcoin. * **Vintage Sats:** Are the satoshis that were mined from the first 10,000 blocks. * **First Transaction Sats:** Denotes the satoshis involved in the inaugural transaction made by Satoshi to Hal Finney on January 12, 2009, within block 170. * **Nakamoto Sats:** Satoshis mined by Satoshi Nakamoto ### The Future of Satoshi Rarity The classification of satoshis into rarities introduces a new dimension to the Bitcoin world, adding value beyond the purely monetary aspect. The market might attribute additional worth to these "Uncommon," "Rare," "Epic," "Legendary," and "Mythic" satoshis due to their unique histories and symbolic significance within the blockchain. # What are BRC-20 Tokens? The [BRC-20 token standard](https://domo-2.gitbook.io/brc-20-experiment/) represents an intriguing milestone in the realm of cryptocurrency.[ Launched by Twitter user @domodata on March 8th, 2023](https://twitter.com/domodata/status/1633658974686855168), BRC-20 tokens have quickly gained attention within the crypto community. Despite sharing a similar name with [Ethereum's ERC-20 token standard](https://ethereum.org/en/developers/docs/standards/tokens/erc-20/), BRC-20 is quite distinct, both in its mechanism and purpose. ### Understanding BRC-20 Tokens BRC-20 is a fungible token standard developed specifically for the Bitcoin blockchain. It uses Ordinal inscriptions of [JavaScript Object Notation (JSON)](https://en.wikipedia.org/wiki/JSON) to deploy token contracts, mint, and transfer tokens. In essence, it's a way to attach a script file to bitcoin and use that file to attribute tokens to satoshis, the smallest unit of Bitcoin. These tokens can then be transferred from one user to another. Unlike the token standards on [EVM (Ethereum Virtual Machine) chains](https://medium.com/eligma-blog/what-are-evm-compatible-blockchains-64f91c97038e), which deploy smart contracts to govern token standards and rules, BRC-20 doesn't interact with smart contracts. Instead, BRC-20 tokens rely on the underlying Bitcoin protocol, utilizing its proof-of-work mechanism for operations. The BRC-20 token standard uses JSON inscriptions on satoshis to create tokens. JSON, a lightweight data-interchange format, houses executable code bits that define every aspect of the token, including supply, minting limit, and the token's identity. Once successfully deployed, any Bitcoin ordinal wallet can connect to the network, mint the token, and transact with it like any other cryptocurrency. Although BRC-20 tokens might seem similar to smart contract tokens, they possess an essential difference. While smart contracts allow the conditions to be changed, BRC-20 inscriptions are immutable, being directly inscribed to a satoshi, they cannot be modified by any counterparty. ### Advantages of BRC-20 Tokens BRC-20 tokens, although in their early stages, offer several notable benefits. * **Fungibility:** BRC-20 tokens are fungible, meaning they are interchangeable and can be easily traded on exchanges. This presents an opportunity to interact with the Bitcoin blockchain without necessarily trading Bitcoin itself. * **Security:** Being built on the Bitcoin protocol, BRC-20 tokens inherit the high level of security and resistance to hacking attempts characteristic of Bitcoin. * **Compatibility:** BRC-20 tokens integrate seamlessly with the Bitcoin protocol, which means they can be easily assimilated into the Bitcoin ecosystem. * **Decentralization:** Benefiting from Bitcoin's decentralized network, BRC-20 tokens can be sent between peers just like any other cryptocurrency. ### BRC-20 vs. ERC-20 Tokens While both BRC-20 and ERC-20 tokens run on a parent blockchain network, they differ significantly in their mechanisms and features.ERC-20 tokens are created through a smart contract code written in languages such as [Solidity](https://soliditylang.org/) and deployed on the Ethereum Virtual Machine. In contrast, BRC-20 tokens are created through ordinal inscriptions on satoshis using JSON. Unlike BRC-20 tokens that operate parallel to Bitcoin, activities on the ERC-20 protocol are in sync with the Ethereum network. Also, the distribution of ERC-20 tokens can be centrally managed by a single entity, which can lead to potential manipulation, while BRC-20 tokens foster a more decentralized and inclusive token generation process. In summary, BRC-20 represents a unique approach to fungible tokens on the Bitcoin blockchain. While they don't have the ability to interact with smart contracts like the Ethereum-based ERC-20 tokens, BRC-20 tokens provide a secure, fungible, and decentralized alternative for tokenization on the Bitcoin network. As the Bitcoin ecosystem continues to evolve, it will be exciting to see how BRC-20 tokens and similar innovations contribute to the blockchain's future. # Image Optimisation Image optimisation is the process of reducing file size and dimensions of digital images without compromising their quality. The main aim is to create the lightest image possible, in terms of file size, to make the page load quickly and smoothly, providing an optimal user experience. In the context of blockchain, image optimisation takes on new layers of significance. Blockchain technology, with its growing use in various fields including digital art and Non-Fungible Tokens (NFTs), relies heavily on image optimisation. Because every transaction (including image inscription) on the blockchain involves a cost, the size of the image can significantly impact the transaction fees. The larger the image, the higher the cost of storing it on-chain. ### How to Optimise Images Image optimisation involves several techniques and steps. Here are the most common methods: * **Resize the Images:** Reducing the dimensions of an image will reduce its file size. This can be done using image editing tools like [Adobe Photoshop](https://www.adobe.com/uk/products/photoshop/landpa.html?gclid=Cj0KCQjwqs6lBhCxARIsAG8YcDhiqfjDDPAR3F5ETjJCjQoFyWt3dPdIH7mpJ7JRfyMMeoFDreuyMjgaAqqDEALw_wcB\&mv=search\&mv=search\&sdid=LZ32SYVR\&ef_id=Cj0KCQjwqs6lBhCxARIsAG8YcDhiqfjDDPAR3F5ETjJCjQoFyWt3dPdIH7mpJ7JRfyMMeoFDreuyMjgaAqqDEALw_wcB:G:s\&s_kwcid=AL!3085!3!441664377297!e!!g!!adobe%20photoshop!1422700211!58647953511\&gad=1), [GIMP](https://www.gimp.org/), etc. * **Compress the Images:** Compression reduces the file size by removing the extra data. There are two types of image compression: lossless and lossy. Lossless compression reduces file size without affecting the image quality, while lossy compression reduces file size significantly, but compromises image quality to some extent. * **Choose the Right File Format:** JPEG, PNG, GIF, and WebP are common image formats. JPEG is good for photographs and detailed images, PNG is suitable for images with transparent backgrounds, and GIF is suitable for simple animations. [WebP](https://developers.google.com/speed/webp#:~:text=WebP%20is%20a%20modern%20image,that%20make%20the%20web%20faster.) is a newer format that provides superior compression and quality characteristics. * **Use Image Optimisation Tools:** Many online tools and software are available for image optimisation. Some popular tools are [TinyPNG](https://tinypng.com/), [ImageOptim](https://imageoptim.com/mac), and [Photoshop's 'Save for Web' ](https://www.lifewire.com/photoshop-save-for-web-tool-tutorial-1697537)option. For on-chain images, due to the cost associated with transactions, it becomes even more crucial to optimise images before uploading them onto the blockchain. However, one must ensure to keep a balance between the image quality and its size to maintain the integrity of the image while minimising the transaction fees. ### Impact of Image Optimisation and Importance of Retaining Image Integrity Image optimisation can greatly enhance the user experience on any website or app. Optimised images lead to faster page loading times, reduced bounce rates, improved [SEO](https://en.wikipedia.org/wiki/Search_engine_optimization) ranking, and lower usage of disk space and bandwidth. In the context of blockchain, image optimisation helps reduce the transaction fees and the storage requirements on the chain. It makes it feasible to include high-quality images in blockchain transactions, which can be especially important in areas like digital art, NFTs, or any other application where images are stored on-chain. However, it's important not to lose the integrity of the image during optimisation. Over-optimisation can lead to degradation of image quality, causing pixelation, blur, or loss of detail, which could undermine the purpose of using the image in the first place. For blockchain-based images, this is especially important, as once an image is stored on the blockchain, it cannot be altered or removed due to the immutable nature of the technology. Therefore, image optimisation must be done carefully to ensure the image remains visually appealing and true to its original intent after it is stored on-chain. ### Conclusion Image optimisation is a critical aspect of modern digital technology and is especially relevant in the evolving field of blockchain. By effectively optimising images without losing their integrity, developers and users can save costs, improve user experience, and make full use of the exciting possibilities offered by blockchain technology. However, care must be taken to ensure that optimisation does not compromise the quality and value of the images being used. # Pixel Art Pixel art is a digital art form that harks back to the early days of computer and video game graphics. From the iconic [Super Mario Bros.](https://www.mariowiki.com/Super_Mario_Bros.) to the modern pixel-based indie games like "[Celeste](https://www.celestegame.com/)," pixel art has carved out a unique and enduring place in the digital art world. This art form has experienced a resurgence in popularity due to the rise of NFTs, or non-fungible tokens, which use blockchain technology to offer proof of ownership for digital assets. One of the best examples of this is [CryptoPunks](https://www.larvalabs.com/cryptopunks), a series of 10,000 uniquely generated characters. ### What is Pixel Art? Pixel art is a form of digital art where images are created using raster graphics software that allows images to be edited on the pixel level. Each pixel acts as a building block for the larger image, much like how a single tile contributes to the overall mosaic. Pixel art has a characteristic aesthetic, defined by the minimalistic, blocky, and abstract nature of the images created. Artists must skillfully manipulate these limited pixels to create discernable images, often requiring creative use of color, shade, and minimalistic design to suggest detail rather than depict it outright. ### The Power of Scaling in Pixel Art An important attribute of pixel art is its scalability. Despite their initial small size, pixel art images often look fantastic when scaled up. This is because pixel art graphics are resolution independent. When you scale up a pixel art image, you're simply making each block (pixel) larger. If the aspect ratio is kept the same, the image retains its sharpness because the pixel grid scales along with the image, unlike traditional raster images which can become blurry when scaled up due to the interpolation of pixels. CryptoPunks, one of the first NFTs on the Ethereum blockchain, are a prime example of pixel art’s scalability. Each CryptoPunk is a 24x24 pixel art character. Despite the incredibly small canvas, the creators, software developers Matt Hall and John Watkinson, were able to design 10,000 unique characters, each with a distinctive combination of features. Even when viewed at significantly larger sizes, CryptoPunks maintain their visual coherence. The 24x24 pixel grid just becomes a grid of larger blocks. It's the same image, but the pixels are larger. The lines remain crisp and the colors remain vivid, maintaining the charm of the original design. This scalability has made CryptoPunks adaptable to various digital displays and formats, from smartphone screens to gigantic billboards. It’s a testament to the power of minimalist design and the creative use of a limited medium. There is a CSS trick that most NFT explorers use to maintain the pixel sharpness called pixelated image rendering. The CSS looks like this: ``` .nft-image { image-rendering: pixelated; } ``` When this style is applied to an element/image, all pixels are rounded to even numbers. This then has the effect that edges are displayed very sharply avoiding interpolation of pixels. ### The Magic of Pixel Art So, why does pixel art, and by extension CryptoPunks, continue to captivate audiences? Part of it certainly lies in the nostalgia that pixel art evokes, reminding us of the early days of digital graphics and video games. But it also lies in its minimalist aesthetic and how much can be expressed with so little. The artistic constraints that define pixel art compel artists to pare down their subjects to their most fundamental forms, focusing on the essential elements that capture a subject's character. This simplicity, far from being a limitation, can be a boon to creativity. Pixel art's capacity to scale up while retaining its charm also gives it a versatile utility in our increasingly digital world. Whether it's on the screen of a retro gaming console, a modern smartphone, or represented as a unique piece of blockchain art, pixel art continues to thrive and adapt, securing its place in the annals of digital art. In conclusion, the rise of projects like CryptoPunks underscores the enduring appeal and adaptability of pixel art. As we continue to push the boundaries of digital art and technology, we can expect to see this art form continue to evolve, inspire, and remind us that, sometimes, less can indeed be more. # Bitcoin The Bitcoin Mempool, Fee Market, and Transaction Confirmation The Bitcoin blockchain's decentralized architecture rests upon a series of complex processes that validate and confirm transactions. Key to these processes is the [mempool](https://mempool.space/), which acts as a waypoint for pending transactions. This article delves deeper into the role of the [mempool](https://mempool.space/) and its critical function within the Bitcoin fee market and transaction confirmation process. ### Decoding the Mempool In Bitcoin parlance, the [mempool](https://mempool.space/)—short for 'memory pool'—is a holding area for Bitcoin transactions that have been broadcast to the network but are yet to be included in the blockchain. Each Bitcoin node houses its own [mempool ](https://mempool.space/)and the size of these mempools varies as they are operator-defined. A Bitcoin transaction, upon its initiation, lands in the [mempool](https://mempool.space/), waiting for confirmation. Transactions do not remain in the [mempool](https://mempool.space/) indefinitely; those not picked up within a certain period (typically 14 days) are usually dropped. This doesn't mean the transaction has been cancelled or that the bitcoins are lost. Instead, the transaction is just no longer in that specific node's mempool. This situation typically happens when the network is congested, and there are more transactions than the block space allows. However, if the transaction is dropped from all nodes' mempools and still not picked up by a miner, it's as if the transaction never happened. The bitcoins never leave the sender's wallet. The sender can then choose to resend the transaction with a higher fee, increasing the likelihood of it being picked up by miners. Some Bitcoin wallets support a feature called Replace-by-Fee (RBF), which allows users to easily increase the fee on a transaction that's taking too long to confirm. ### Casting Bitcoin Transactions The initiation of a Bitcoin transaction occurs in the user's wallet. Here, the user defines the recipient's address and the amount to be transferred. The wallet then constructs a transaction message, which includes the sender's and recipient's details, the transfer amount, a transaction fee, and the sender's digital signature. The transaction fee plays a pivotal role in this process. It acts as a monetary incentive for miners to prioritize the user's transaction when mining new blocks. Hence, the higher the fee, the more likely the transaction is to be processed quickly. This is the first hint at the fee market that develops around Bitcoin transactions. Once constructed and signed, this transaction message is broadcast to the Bitcoin network. The mempool then steps into the equation. ### The Mempool's Role in the Fee Market and Transaction Confirmation Upon reaching the network, Bitcoin transactions are added to the [mempool](https://mempool.space/) of Bitcoin nodes. Nodes validate these transactions, verifying the sufficiency of the sender's Bitcoin balance and the authenticity of the digital signature. Post-validation, transactions reside in the mempool, awaiting their turn to be included in a block. This is where the 'fee market' comes into play. Miners select transactions from the [mempool](https://mempool.space/) for the blocks they mine, typically prioritizing those with higher fees, leading to a competitive marketplace for transaction fees. This competition intensifies during periods of network congestion, with users ramping up transaction fees to secure faster transaction processing. Once a miner mines a block containing the transaction, the transaction is confirmed, and the mined block becomes part of the blockchain. The nodes then update their version of the ledger, which simultaneously removes the confirmed transactions from the mempool, clearing space for new transactions. ### Confirming Transactions: The Final Step Once a transaction has been included in a block and that block has been added to the blockchain, we say that the transaction has one confirmation. Additional confirmations come as more blocks are added on top of the block containing the transaction, further securing it within the blockchain's history. Most recipients require multiple confirmations before considering a transaction as fully validated, typically around six confirmations. This process ensures the finality and irreversibility of the transaction, further enhancing Bitcoin's robustness and security. ### Wrapping Up The [mempool](https://mempool.space/) plays an instrumental role within the Bitcoin network, acting as a waiting area for transactions and a driver of the Bitcoin fee market. The dynamics of the mempool and miners' preferences contribute to the emergence of the fee market, thus impacting transaction costs and timings. Furthermore, the [mempool's](https://mempool.space/) role extends to the transaction confirmation process, a key security feature of Bitcoin transactions. Understanding the mempool's function allows users to better anticipate potential transaction fees and wait times, particularly during high network activity periods. As the intersection between miners, wallets, and the blockchain, the mempool encapsulates the decentralized, secure, and transparent nature of Bitcoin, enabling the seamless operation of the Bitcoin fee market and transaction confirmation process. # Unspent Transaction Output (UTXO) In the realm of Bitcoin (BTC), the term Unspent Transaction Output (UTXO) is a crucial building block. It pertains to transaction outputs that haven't been used, readily available for future transactions as inputs. The significance of UTXOs becomes clearer in the context of Ordinals, a system that operates within UTXOs. ### Bitcoin Transactions and UTXOs To grasp UTXOs, you need to understand Bitcoin transactions first. A Bitcoin transaction moves value by taking one or more inputs (referencing UTXOs from previous transactions) and turning them into one or more outputs, which in turn create new UTXOs for future transactions. UTXOs are akin to pieces of Bitcoin 'cash'. When you acquire Bitcoin, you're essentially receiving a collection of UTXOs. Your Bitcoin 'balance' is the aggregate value of these UTXOs. ### Utilizing UTXOs Sending Bitcoin involves your wallet picking out UTXOs as transaction inputs. These chosen UTXOs are 'spent' and hence cannot be used in future transactions. In cases where the cumulative value of input UTXOs exceeds the amount you want to transfer, your transaction generates a 'change' output. This is a new UTXO returned to your wallet. For instance, if you aim to transfer 0.5 BTC to someone and use a 1 BTC UTXO as an input, the transaction produces two outputs: one sends 0.5 BTC to the recipient and the other sends 0.5 BTC back to your wallet as ‘change’. ### The Importance of understanding UTXOs within the context of Ordinals Ordinals are essentially inscriptions stored inside UTXOs. A single satoshi (sat) contains the Ordinal inscription, while the rest serve as padding (generally 10,000 sats which creates a buffer when transacting with the ordinal). Wallet users, particularly those of Sparrow, benefit from understanding UTXOs; To avoid inadvertently spending the UTXO holding their Ordinal in transactions, miner fees, or transfers,. Therefore it is imperative to apply UTXO Management, also known as ‘Coin Control’. Many individuals have unfortunately lost their Ordinals through spending the UTXO and thus this inattention to this detail. However, for most users, wallets like Xverse and Unisat handle the management and mechanics of the UTXO containing your ordinal for you, eliminating the need to worry about this.