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-ordinals
Collection details retrieved successfully
Collection not found
GET /marketplace/collection/{slug} HTTP/1.1
Host: api.ordinalsbot.com
Accept: */*
{
"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"
},
"data": [
{
"id": "8e7ba76e0c06ff5f43f50371bce849ae4e88dd36e1c0629e1a6f4383d1b0e679i0",
"meta": {
"attributes": [
{
"trait_type": "background",
"value": "orange"
}
],
"name": "Satoshibles: The Ordinals #1"
}
}
]
}
Creates a new marketplace with configurable fees and payout addresses.
API key for authorization.
your-api-key
Seller fee percentage as a non-negative float.
1.5
Buyer fee percentage as a non-negative float.
1
BTC address where fees will be paid.
1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
Seller fee percentage specifically for launchpad as a non-negative float.
2
Buyer fee percentage specifically for launchpad as a non-negative float.
1.8
BTC address where launchpad fees will be paid.
1BoatSLRHtKNngkdXEeobR76b53LETtpyT
Maker fee percentage for marketplace as a non-negative float.
0.5
Taker fee percentage for marketplace as a non-negative float.
0.75
BTC address for marketplace fees.
1Examp1eBTCAddr3ssPlaceTakerFee
Maker fee percentage for launchpad as a non-negative float.
0.4
Taker fee percentage for launchpad as a non-negative float.
0.6
BTC address for launchpad fees.
1LaunchBTCAddr3ssFee
URL for the marketplace.
https://example.com
A brief description of the marketplace.
A marketplace for digital assets.
Rate limit level as a non-negative integer.
5
Marketplace 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-key
Marketplace 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)
1
Number of items per page (optional)
10
Sort listings by this field (optional)
price
Possible 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-09-01T06:32:23.818Z",
"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-key
Bitcoin address for receiving payments.
2NA......V75C
Public key associated with the payment address.
029......cf37
Ordinal address for the maker.
e58......88a26
Public key associated with the Ordinal.
594......702e
Listings 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-key
Array 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.
1
API key required for authorization.
your-api-key
New price for the listing in Satoshis.
15
Signed Partially Signed Bitcoin Transaction.
cHNi.....ZUEAAA==
Bitcoin address for receiving payments.
2NA......V75C
Public key associated with the payment address.
029......cf37
Public key associated with the Ordinal.
594......702e
Listing 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.
1
API key required for authorization.
your-api-key
Bitcoin address for receiving payments.
2NA......V75C
Public key associated with the payment address.
029......cf37
Fee rate in Satoshis per byte (optional).
3
Listing 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.
1
API key required for authorization.
your-api-key
Bitcoin address for receiving payments.
2NA......V75C
Signed 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-key
Unique identifiers of the listing to purchase.
[1,2]
Bitcoin address for the buyer's payment.
2N6......nbKL
Public key associated with the buyer's payment address.
033......5c05
Ordinal address for the buyer.
e58......88a26
Flag to indicate if we should scan the payment utxos for rare sats
false
Buy 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-key
Array of listing IDs to broadcast.
[1,2]
Base64-encoded Partially Signed Bitcoin Transaction (PSBT) to broadcast.
cHNi.....ZUEAAA
Bitcoin address for the buyer's payment.
2N6......nbKL
Ordinal address for the buyer.
e58......88a26
Transaction 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-key
Bitcoin address for the maker's payment.
2N6.....nbKL
Public key associated with the maker's payment address.
033.....5c05
Public key associated with the maker's ordinal.
e58.....88a26
Fee rate in Satoshis per byte.
1
Ordinal 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-key
Bitcoin address to check for padding outputs.
2N6......bKL
Optional number of outputs to create.
3
Check 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-key
Bitcoin address to select padding outputs.
2N6......bKL
List 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-key
Bitcoin address to set up padding outputs.
2N6......bKL
Public key associated with the Bitcoin address.
033......05c05
Fee rate in Satoshis per byte.
28
Optional number of outputs to create.
3
Padding 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-key
The slug of the launchpad.
satoshibles-the-ordinals
Bitcoin address for receiving payments
2N6ZePLQrKtix9bJBfznsykxKX1XtirnbKL
Public key associated with the payment address
033528dc4c9fd062e63d2a8d5f8b2e3c3b8312ae7c1d3c4a41a9dc4eefa4205c05
Maker ordinal address
bc1q...
Public key associated with the ordinals
e581edf3a948470930171a3e676490a8f7953a3698044c14b4d75ffeabc88a26
Launchpad 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.
1
Number of inscriptions to mint (buy).
2
Bitcoin 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.
5
Whether to use the sat scanner for input selection.
false
Offer 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)
1
Number of items per page (optional)
10
Sort listings by this field (optional)
id
Possible 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": []
}
],
"count": 1
}
Last updated