Unified API to bulk buy Ordinals from all different source sites via Ordyssey
Sweep Order
Definition: Sweep Order is an Ordyssey object to save the user request to buy a set ofOrdyssey listings. It includes a sequential execution pipeline ofPSBTs / Bitcoin Tx generated by different marketplaces (sweep sources) which supports sweep function.
Why it's stateful: The structure of a sweep PSBT / Tx depends on the real-time UTXO balance of a user wallet. This process is stateful and cannot concurrently apply unsigned + submit signed in only one step. After a Bitcoin Tx broadcasted, the UTXO distribution changes, and other PSBTs previously applied concurrently will be invalid. Therefore, we have to call the exchanges' purchasing interfaces step by step to generate unsigned PSBTs for users to sign and broadcast.
Step Design: The marketplaces have different PSBT algorithms for sweep function. Usually a complete purchasing transaction includes a preceding Bitcoin Tx to make the UTXOs available for the algorithm, so we define PSBT Steps for them respectively. Each purchase step corresponds to a Bitcoin Tx.
Only listings from these sources can be generated as a Sweep Order so far, so you may need to do some listings source filter for the range of user selecting on your app's UI.
Apply for un-signed PSBT or post-back signed PSBT in the order defined by steps
Path Parameters
Name
Type
Description
order_uuid*
String
The unique identifier of the sweep order
Request Body
Name
Type
Description
fee_rate_tier
String
The gas level keywords defined by mempool.space, must be one of minimumFee, economyFee, hourFee, halfHourFee, fastestFee
Most source exchanges follow the standard (while not directly use sats/vB), so we have no choice. Please make the gas price / cost data available for your users from this API https://mempool.space/api/v1/fees/recommended
signed_psbt_base64
String
Signed by user wallet and client side, such as from Unisat. But we need base64 format here.
For the step of returning signed PSBT by user, it's required.
DO NOT put it into production before reading the risk disclaimer below.
Disclaimer for potential unexpected UTXO spending
In principle, if the sweep targets are from other marketplaces, Ordyssey Proxy Sweep is just a proxy service and does not have the authority to change the generation of PSBT/Tx structure. The returned PSBT is consistent with the result from the source site's UI.
For example, OrdinalsWallet sweep PSBT algorithm has some issues here:
Prioritize consuming small UTXOs as payment, including MagicEden's 600 size dummy.
For payment UTXO selecting, OW does not recognize cursed inscriptions and rare sats.
For 1, if you have a large number of small UTXOs in your wallet, a simple payment Tx will have a large number of inputs, resulting in high gas fees.
For 2, we recommend developers also check the indexer results after receiving the unsigned PSBT to ensure that no inscriptions or rare sats are lost as payment UTXO. An additional layer of protection is required.
Ordyssey is not responsible for this kind of loss or UTXO protecting.
Similarly, if a wallet is also a user of MagicEden or Sating.io, its rare sats are unidentified by most products in the ecosystem.
What developers can do here is:
Identify the problem and risk for all inputs of the unsigned PSBT, reject the purchase request for user or do some advise.
Make a pre-risk statement for your users.
Try to contact with the source site developers to find out if there is room for optimization in their Tx structure and the behavior of consuming UTXO and indexer results.
