API Docs
Marketplace for inscriptions, runes, brc20 and everything else!
Onboard a new NFT collection with detailed metadata and item information.
Collection onboarded successfully
POST /marketplace/collection/onboard HTTP/1.1
Host: api.ordinalsbot.com
Content-Type: application/json
Accept: */*
Content-Length: 1157
{
"meta": {
"description": "Satoshi has come home to Bitcoin! The Ordinals collection by OG NFT project Satoshibles are a limited edition collection of 100 ordinals, featuring all new traits from the original artist Ayyoub Bouzerda. This collection is a tribute to Satoshi and the enduring legacy of Bitcoin. Don't miss your chance to own a piece of history!",
"discord_link": "https://discord.com/invite/7Wm9Jg8MkW",
"icon": "https://turbo.ordinalswallet.com/inscription/preview/3542f12dbe5fe3bd7fd622d1bb54994432e9a9184d24ff62ceb83234383b558ei0",
"inscription_icon": "3542f12dbe5fe3bd7fd622d1bb54994432e9a9184d24ff62ceb83234383b558ei0",
"name": "Satoshibles: The Ordinals",
"slug": "satoshibles-the-ordinals",
"twitter_link": "https://twitter.com/satoshibles",
"website_link": "https://satoshibles.com",
"telegram_link": "https://t.me/satoshibles",
"instagram_link": "https://instagram.com/satoshibles",
"banner_image": "https://example.com/banner.jpg",
"extra_metadata": {
"key": "value"
}
},
"data": [
{
"id": "8e7ba76e0c06ff5f43f50371bce849ae4e88dd36e1c0629e1a6f4383d1b0e679i0",
"meta": {
"attributes": [
{
"trait_type": "background",
"value": "orange"
}
],
"name": "Satoshibles: The Ordinals #1"
}
}
]
}Collection onboarded successfully
{
"message": "Collection onboarded successfully"
}Retrieve metadata and items for a specific NFT collection based on the provided slug. Returns up to 1k items!
The slug of the collection to retrieve.
satoshibles-the-ordinalsCollection details retrieved successfully
Collection not found
GET /marketplace/collection/{slug} HTTP/1.1
Host: api.ordinalsbot.com
Accept: */*
{
"meta": {
"name": "Satoshibles: The Ordinals",
"description": "Satoshi has come home to Bitcoin! The Ordinals collection by OG NFT project Satoshibles are a limited edition collection of 100 ordinals, featuring all new traits from the original artist Ayyoub Bouzerda. This collection is a tribute to Satoshi and the enduring legacy of Bitcoin. Don't miss your chance to own a piece of history!",
"discord_link": "https://discord.com/invite/7Wm9Jg8MkW",
"icon": "https://explorer.ordinalsbot.com/content/3542f12dbe5fe3bd7fd622d1bb54994432e9a9184d24ff62ceb83234383b558ei0",
"slug": "satoshibles-the-ordinals",
"twitter_link": "https://twitter.com/satoshibles",
"website_link": "https://satoshibles.com",
"banner_image": null,
"telegram_link": null,
"instagram_link": null,
"inscription_icon": {
"inscription_id": "3542f12dbe5fe3bd7fd622d1bb54994432e9a9184d24ff62ceb83234383b558ei0"
}
},
"inscriptions": [
{
"name": "Satoshibles: The Ordinals #4",
"inscription_id": "3542f12dbe5fe3bd7fd622d1bb54994432e9a9184d24ff62ceb83234383b558ei0",
"attributes": [
{
"value": "yellow",
"category": {
"name": "background"
},
"value_type": "string"
}
]
}
]
}Creates a new marketplace with configurable fees and payout addresses.
API key for authorization.
your-api-keySeller fee percentage as a non-negative float.
1.5Buyer fee percentage as a non-negative float.
1BTC address where fees will be paid.
1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNaSeller fee percentage specifically for launchpad as a non-negative float.
2Buyer fee percentage specifically for launchpad as a non-negative float.
1.8BTC address where launchpad fees will be paid.
1BoatSLRHtKNngkdXEeobR76b53LETtpyTMaker fee percentage for marketplace as a non-negative float.
0.5Taker fee percentage for marketplace as a non-negative float.
0.75BTC address for marketplace fees.
1Examp1eBTCAddr3ssPlaceTakerFeeMaker fee percentage for launchpad as a non-negative float.
0.4Taker fee percentage for launchpad as a non-negative float.
0.6BTC address for launchpad fees.
1LaunchBTCAddr3ssFeeURL for the marketplace.
https://example.comA brief description of the marketplace.
A marketplace for digital assets.Rate limit level as a non-negative integer.
5Marketplace created successfully
Invalid input, validation errors
POST /marketplace/marketplaces/create HTTP/1.1
Host: api.ordinalsbot.com
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 511
{
"sellerFee": 1.5,
"buyerFee": 1,
"btcFeePayoutAddress": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
"launchpadSellerFee": 2,
"launchpadBuyerFee": 1.8,
"launchpadBtcFeePayoutAddress": "1BoatSLRHtKNngkdXEeobR76b53LETtpyT",
"marketPlaceMakerFee": 0.5,
"marketPlaceTakerFee": 0.75,
"marketPlaceFeeBtcAddress": "1Examp1eBTCAddr3ssPlaceTakerFee",
"launchpadMakerFee": 0.4,
"launchpadTakerFee": 0.6,
"launchpadFeeBtcAddress": "1LaunchBTCAddr3ssFee",
"url": "https://example.com",
"description": "A marketplace for digital assets.",
"rateLimitLevel": 5
}{
"message": "Marketplace created successfully"
}Retrieves information about the marketplace. Requires an API key for access.
API key required for accessing marketplace details.
your-api-keyMarketplace details retrieved successfully
Unauthorized - API key missing or invalid
GET /marketplace/marketplaces HTTP/1.1
Host: api.ordinalsbot.com
x-api-key: text
Accept: */*
{
"id": "3b32e70e-6802-42e7-a7d3-056ad909ebd7",
"api_key": "9571e8be-a77e-41c4-afcb-76440fd27a48",
"name": "Test marketplace 04",
"marketplace_maker_fee": 499,
"marketplace_taker_fee": 499,
"marketplace_fee_btc_address_id": 1,
"launchpad_maker_fee": 599,
"launchpad_taker_fee": 599,
"launchpad_fee_btc_address_id": 1,
"url": "https://domain.com",
"description": "abc",
"rate_limit_level": null
}Retrieves a list of listings based on filter, pagination, and sorting options.
The page number for pagination (optional)
1Number of items per page (optional)
10Sort listings by this field (optional)
pricePossible values: Successfully retrieved the listings.
Unauthorized - API key missing or invalid.
POST /marketplace/listings HTTP/1.1
Host: api.ordinalsbot.com
Content-Type: application/json
Accept: */*
Content-Length: 75
{
"filter": {
"status": "broadcast"
},
"page": 1,
"itemsPerPage": 10,
"sort": "price"
}{
"results": [
{
"id": 1,
"utxo_id": 1,
"price": 1,
"psbt": "text",
"side": "text",
"maker_payment_address_id": 1,
"maker_ordinal_address_id": 1,
"merged_psbt": "text",
"status": "text",
"maker_output_value": 1,
"index_in_maker_psbt": 1,
"marketplace_id": "text",
"marketplace_maker_fee": 1,
"marketplace_taker_fee": 1,
"platform_maker_fee": 1,
"platform_taker_fee": 1,
"platform_fee_btc_address_id": 1,
"marketplace_fee_btc_address_id": 1,
"timestamp": "2025-10-31T05:30:35.881Z",
"maker_payment": {
"id": 1,
"address": "text",
"public_key": "text"
},
"utxos": {
"utxo": "text",
"utxo_contents": [
{
"inscriptions": {
"inscription_id": "text"
}
}
]
}
}
],
"count": 1,
"currentPage": 1,
"totalPages": 1,
"totalItems": 1
}List one or more items for sale on the marketplace. The endpoint returns a Partially Signed Bitcoin Transaction (PSBT) for the owner to sign. The buyer must supply a UTXO covering the listing price and any applicable fees. The seller's signature is required only during listing creation, while only the buyer's signature is needed to complete the purchase.
API key required for authorization.
your-api-keyBitcoin address for receiving payments.
2NA......V75CPublic key associated with the payment address.
029......cf37Ordinal address for the maker.
e58......88a26Public key associated with the Ordinal.
594......702eListings created successfully with a PSBT for the owner to sign.
Bad Request - Validation error in the request payload.
Unauthorized - API key missing or invalid.
POST /marketplace/listings/create HTTP/1.1
Host: api.ordinalsbot.com
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 210
{
"makerPaymentAddress": "2NA......V75C",
"makerPaymentPublicKey": "029......cf37",
"makerOrdinalAddress": "e58......88a26",
"makerOrdinalPublicKey": "594......702e",
"utxos": [
{
"utxo": "ead......63d8:1",
"price": "1520"
}
]
}{
"psbt": "cHni.....AAAAA=",
"listingIds": [
1,
2,
3
]
}Confirms a listing by saving the signed Partially Signed Bitcoin Transaction (PSBT) in the listing database. This is the final step in the listing creation process after signing the PSBT returned by the listings/create endpoint.
API key required for authorization.
your-api-keyArray of listing IDs to confirm.
[1,2,3]Signed Partially Signed Bitcoin Transaction.
cHNi.....ZUEAAA==Confirmation successful, PSBT is updated.
Unauthorized - API key missing or invalid.
PUT /marketplace/listings/confirm HTTP/1.1
Host: api.ordinalsbot.com
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 55
{
"listingIds": [
1,
2,
3
],
"signedPSBT": "cHNi.....ZUEAAA=="
}{
"message": "Signed PSBT is updated successfully"
}Updates the price of a listing on the marketplace. Returns a Partially Signed Bitcoin Transaction (PSBT) for the owner to sign.
The unique identifier of the listing to update.
1API key required for authorization.
your-api-keyNew price for the listing in Satoshis.
15Signed Partially Signed Bitcoin Transaction.
cHNi.....ZUEAAA==Bitcoin address for receiving payments.
2NA......V75CPublic key associated with the payment address.
029......cf37Public key associated with the Ordinal.
594......702eListing updated successfully, with a PSBT for the owner to sign.
Bad Request - Validation error in the request payload.
Unauthorized - API key missing or invalid.
POST /marketplace/listings/{id}/relist HTTP/1.1
Host: api.ordinalsbot.com
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 163
{
"price": 15,
"signedPSBT": "cHNi.....ZUEAAA==",
"makerPaymentAddress": "2NA......V75C",
"makerPaymentPublicKey": "029......cf37",
"makerOrdinalPublicKey": "594......702e"
}{
"psbt": "cHni.....AAAAA=",
"listingId": 1
}Removes a listing from the marketplace and returns a Partially Signed Bitcoin Transaction (PSBT) that must be signed by the owner.
The unique identifier of the listing to delete.
1API key required for authorization.
your-api-keyBitcoin address for receiving payments.
2NA......V75CPublic key associated with the payment address.
029......cf37Fee rate in Satoshis per byte (optional).
3Listing deleted successfully with a PSBT for the owner to sign.
Internal Server Error - An unexpected error occurred.
DELETE /marketplace/listings/{id} HTTP/1.1
Host: api.ordinalsbot.com
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 91
{
"makerPaymentAddress": "2NA......V75C",
"makerPaymentPublicKey": "029......cf37",
"feeRate": 3
}{
"psbtBase64": "cHni.....AAAAA=",
"makerOrdinalInputIndices": [
0
],
"makerPaymentInputIndices": [
1,
2
]
}Finalize the deletion of a listing by saving the signed Partially Signed Bitcoin Transaction (PSBT) and removing the listing from the database. This is the final step in the deletion process after signing the PSBT returned by the marketplace/listings/{id} endpoint.
The unique identifier of the listing to confirm deletion.
1API key required for authorization.
your-api-keyBitcoin address for receiving payments.
2NA......V75CSigned Partially Signed Bitcoin Transaction.
cHNi.....ZUEAAA==Listing delisted successfully.
Internal Server Error - An unexpected error occurred.
PUT /marketplace/listings/{id}/confirm-delist HTTP/1.1
Host: api.ordinalsbot.com
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 72
{
"makerPaymentAddress": "2NA......V75C",
"signedPSBT": "cHNi.....ZUEAAA=="
}{
"txId": "aa1c27........2767",
"message": "Record successfully delisted"
}Creates a transaction to purchase a listing on the marketplace. Returns a base64-encoded Partially Signed Bitcoin Transaction (PSBT) and input indices that the buyer must sign to complete the purchase.
API key required for authorization.
your-api-keyUnique identifiers of the listing to purchase.
[1,2]Bitcoin address for the buyer's payment.
2N6......nbKLPublic key associated with the buyer's payment address.
033......5c05Ordinal address for the buyer.
e58......88a26Flag to indicate if we should scan the payment utxos for rare sats
falseBuy offer created successfully, with a PSBT for the buyer to sign.
Bad Request - Validation error in the request payload.
Unauthorized - API key missing or invalid.
POST /marketplace/listings/offers HTTP/1.1
Host: api.ordinalsbot.com
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 146
{
"ids": [
1,
2
],
"takerPaymentAddress": "2N6......nbKL",
"takerPaymentPublicKey": "033......5c05",
"takerOrdinalAddress": "e58......88a26",
"satScan": false
}{
"psbt": "cHni.....AAAAA=",
"inputIndices": [
0,
1,
3,
4
]
}Broadcasts the transaction to the network and updates the listing status.
API key required for authorization.
your-api-keyArray of listing IDs to broadcast.
[1,2]Base64-encoded Partially Signed Bitcoin Transaction (PSBT) to broadcast.
cHNi.....ZUEAAABitcoin address for the buyer's payment.
2N6......nbKLOrdinal address for the buyer.
e58......88a26Transaction broadcast successfully, with updated listing status.
Internal Server Error - An unexpected error occurred.
POST /marketplace/listings/broadcast HTTP/1.1
Host: api.ordinalsbot.com
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 115
{
"ids": [
1,
2
],
"psbt": "cHNi.....ZUEAAA",
"takerPaymentAddress": "2N6......nbKL",
"takerOrdinalAddress": "e58......88a26"
}{
"txId": "aa1c27........2767"
}Transfers one or more ordinals, generating a Partially Signed Bitcoin Transaction (PSBT) that must be signed by the owner.
API key required for authorization.
your-api-keyBitcoin address for the maker's payment.
2N6.....nbKLPublic key associated with the maker's payment address.
033.....5c05Public key associated with the maker's ordinal.
e58.....88a26Fee rate in Satoshis per byte.
1Ordinal transfer transaction created successfully, with a PSBT for the owner to sign.
Internal Server Error - An unexpected error occurred.
POST /marketplace/inscriptions/transfer HTTP/1.1
Host: api.ordinalsbot.com
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 211
{
"transfer": [
{
"ordinalId": "8c5.....2ci0",
"receiverOrdinalAddress": "tb1.....3yk3"
}
],
"makerPaymentAddress": "2N6.....nbKL",
"makerPaymentPublicKey": "033.....5c05",
"makerOrdinalPublicKey": "e58.....88a26",
"feeRate": 1
}{
"psbtBase64": "cHni.....AAAAA=",
"makerOrdinalInputIndices": [
0
],
"makerPaymentInputIndices": [
1,
2
]
}Checks if padding outputs exist for a given Bitcoin address.
API key required for authorization.
your-api-keyBitcoin address to check for padding outputs.
2N6......bKLOptional number of outputs to create.
3Check completed successfully, indicating if padding outputs are present.
Internal Server Error - An unexpected error occurred.
PUT /marketplace/inscriptions/confirm-padding HTTP/1.1
Host: api.ordinalsbot.com
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 46
{
"address": "2N6......bKL",
"numberOfOutputs": 3
}{
"paddingOutputsExist": true,
"requiredDummyOutputs": 3,
"additionalOutputsNeeded": 0
}Selects padding outputs associated with a given Bitcoin address.
API key required for authorization.
your-api-keyBitcoin address to select padding outputs.
2N6......bKLList of selected padding outputs.
Internal Server Error - An unexpected error occurred.
POST /marketplace/inscriptions/select-padding HTTP/1.1
Host: api.ordinalsbot.com
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 26
{
"address": "2N6......bKL"
}[
{
"txid": "f50......1b38b",
"vout": 0,
"status": {
"confirmed": true,
"block_height": 3124442,
"block_hash": "000.....589ae",
"block_time": 1728662165
},
"value": 600
}
]Sets up padding outputs for a given Bitcoin address.
API key required for authorization.
your-api-keyBitcoin address to set up padding outputs.
2N6......bKLPublic key associated with the Bitcoin address.
033......05c05Fee rate in Satoshis per byte.
28Optional number of outputs to create.
3Padding outputs setup successfully, returning a PSBT and input indices.
Internal Server Error - An unexpected error occurred.
POST /marketplace/inscriptions/setup-padding HTTP/1.1
Host: api.ordinalsbot.com
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 88
{
"address": "2N6......bKL",
"publicKey": "033......05c05",
"feeRate": 28,
"numberOfOutputs": 3
}{
"psbt": "cHNid......AAAAAAA=",
"inputIndices": [
0,
1
]
}Creates a new launchpad with specified phases and configuration.
API key required for authorization.
your-api-keyThe slug of the launchpad.
satoshibles-the-ordinalsBitcoin address for receiving payments
2N6ZePLQrKtix9bJBfznsykxKX1XtirnbKLPublic key associated with the payment address
033528dc4c9fd062e63d2a8d5f8b2e3c3b8312ae7c1d3c4a41a9dc4eefa4205c05Maker ordinal address
bc1q...Public key associated with the ordinals
e581edf3a948470930171a3e676490a8f7953a3698044c14b4d75ffeabc88a26Launchpad created successfully
Bad Request - Validation error in the request payload
POST /marketplace/launchpads/create HTTP/1.1
Host: api.ordinalsbot.com
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 1598
{
"slug": "satoshibles-the-ordinals",
"makerPaymentAddress": "2N6ZePLQrKtix9bJBfznsykxKX1XtirnbKL",
"makerPaymentPublicKey": "033528dc4c9fd062e63d2a8d5f8b2e3c3b8312ae7c1d3c4a41a9dc4eefa4205c05",
"makerOrdinalAddress": "bc1q...",
"makerOrdinalPublicKey": "e581edf3a948470930171a3e676490a8f7953a3698044c14b4d75ffeabc88a26",
"data": [
{
"id": "8e7ba76e0c06ff5f43f50371bce849ae4e88dd36e1c0629e1a6f4383d1b0e679i0",
"meta": {
"attributes": [
{
"trait_type": "background",
"value": "orange"
}
],
"name": "Satoshibles: The Ordinals #1"
}
}
],
"meta": {
"description": "Satoshi has come home to Bitcoin! The Ordinals collection by OG NFT project Satoshibles are a limited edition collection of 100 ordinals, featuring all new traits from the original artist Ayyoub Bouzerda. This collection is a tribute to Satoshi and the enduring legacy of Bitcoin. Don't miss your chance to own a piece of history!",
"discord_link": "https://discord.com/invite/7Wm9Jg8MkW",
"icon": "https://turbo.ordinalswallet.com/inscription/preview/3542f12dbe5fe3bd7fd622d1bb54994432e9a9184d24ff62ceb83234383b558ei0",
"inscription_icon": "3542f12dbe5fe3bd7fd622d1bb54994432e9a9184d24ff62ceb83234383b558ei0",
"name": "Satoshibles: The Ordinals",
"slug": "satoshibles-the-ordinals",
"twitter_link": "https://twitter.com/satoshibles",
"website_link": "https://satoshibles.com",
"telegram_link": "https://t.me/satoshibles",
"instagram_link": "https://instagram.com/satoshibles",
"banner_image": "https://example.com/banner.jpg"
},
"phases": [
{
"name": "Whitelist Sale",
"startDate": 1712044800,
"endDate": 1712131200,
"price": 100000,
"isPublic": false,
"allowList": [
{
"address": "bc1q...",
"allocation": 5
}
]
}
]
}{
"launchpadId": 1,
"status": "pending"
}Retrieves the current PSBT status and data for a specific launchpad.
The unique identifier of the launchpad phase psbt.
API key required for authorization.
PSBT status retrieved successfully.
Launchpad not found.
GET /marketplace/launchpads/psbt/{id} HTTP/1.1
Host: api.ordinalsbot.com
x-api-key: text
Accept: */*
{
"id": 1,
"phase_id": 1,
"batch_number": 1,
"status": "unsigned",
"inscription_count": 2,
"psbt": "cHNi.....ZUEAAA=="
}Confirms and updates the signed PSBT for a specific launchpad.
The unique identifier of the launchpad phase psbt.
API key required for authorization.
Base64-encoded signed PSBT.
cHNi.....ZUEAAA==PSBT signed successfully.
PUT /marketplace/launchpads/psbt/{id}/confirm HTTP/1.1
Host: api.ordinalsbot.com
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 34
{
"signedPSBT": "cHNi.....ZUEAAA=="
}PSBT signed successfully.
{
"message": "Signed PSBT is updated successfully"
}Creates a new buy offer for one or more inscriptions in an active launchpad phase. It returns a PSBT and the orderbook IDs reserved for the buyer.
API key required for authorization.
Launchpad ID.
1Number of inscriptions to mint (buy).
2Bitcoin address for receiving change.
bc1q...Public key associated with the payment address.
02ab...Bitcoin address for receiving the inscription.
bc1q...Network fee rate in sats/vB.
5Whether to use the sat scanner for input selection.
falseOffer created successfully.
POST /marketplace/launchpads/offers HTTP/1.1
Host: api.ordinalsbot.com
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 148
{
"id": 1,
"mintCount": 2,
"takerPaymentAddress": "bc1q...",
"takerPaymentPublicKey": "02ab...",
"takerOrdinalAddress": "bc1q...",
"feeRate": 5,
"satScan": false
}Offer created successfully.
{
"ids": [
41,
43
],
"phaseId": 1,
"psbt": "cHNidP8BAJMCAAAAASFll4Wtm3...",
"inputIndices": [
1
]
}Retrieves the allocation details for a given address in a launchpad phase.
Launchpad ID.
Bitcoin address to check allocation for.
API key required for authorization.
Allocation details retrieved successfully.
GET /marketplace/launchpads/{id}/allocation/{takerOrdinalAddress} HTTP/1.1
Host: api.ordinalsbot.com
x-api-key: text
Accept: */*
Allocation details retrieved successfully.
{
"status": "success",
"message": "Phases fetched successfully",
"phases": [
{
"id": 2,
"is_public": 0,
"total_allocation": 5,
"remaining_allocation": 5
}
],
"has_public_phases": true
}Retrieves a list of all launchpads with optional filtering.
API key required for authorization.
The page number for pagination (optional)
1Number of items per page (optional)
10Sort listings by this field (optional)
idPossible values: List of launchpads retrieved successfully.
POST /marketplace/launchpads HTTP/1.1
Host: api.ordinalsbot.com
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 69
{
"filter": {
"status": "active"
},
"page": 1,
"itemsPerPage": 10,
"sort": "id"
}List of launchpads retrieved successfully.
{
"data": [
{
"id": 1,
"status": "text",
"phases": [
{
"id": 1,
"launchpad_id": 1,
"name": "text",
"phase_number": 1,
"start_date": 1,
"end_date": 1,
"status": "text",
"is_public": true,
"price": 1
}
]
}
],
"count": 1
}Last updated