Magisat Logo
API docs by Redocly

API Docs | Magisat Rare Sats (1.6.0)

Download OpenAPI specification:Download

The API for the Magisat project (https://api.magisat.io/).

To request an API key, please apply here.

General information

Premium endpoints

Our Premium API version offers customers access to high-performance endpoints designed to handle complex and resource-intensive requests. Due to the intensive resources required to maintain these premium services, we implement a fee structure to sustain their quality, availability, and reliability. By subscribing to the Premium API, customers not only gain access to these enhanced features but also contribute to the ongoing development and support of a robust, scalable system that ensures exceptional performance, even for the most complex and computationally intensive queries.

To subscribe to our API, open a ticket on our discord: https://discord.gg/magisat . No worries, we respond promptly!

Premium endpoints are available only for users with a premium subscription. To get access to these endpoints, please contact us on discord.

What is a prepared UTXO?

Any Unspent Transaction Output, containing no special sats, and less than 1,000 sats overall - is called a Prepared UTXO.

Prepared UTXOs are used as placeholders to allow other outputs to reach a certain index in the transaction. This procesure ensures the end-to-end trustless UTXO-exchange functionality.

What are Spendables UTXOs?

Spendables UTXOs are the UTXOs that contain ONLY the followings type of rare-sats (just from the list): Palindrome, Sequence Pali, Alpha & Omega. We will make announcements when new types of rare-sats are added to the list.

Why are they used and in which conditions?

They are used in case the wallet you made the request for has not enough common utxos for payment when creating prepareds or making a buy. If the user has no problems with using spendables as payment, the spendables won't be used if the wallet has enough commons. Spendables are used only if needed.

You can decide in each request by changing the param overrideDisableSpendables. The default is false, case in which spendables can be used. Set to true if you don't want to use the spendables as payment even if wallet has not enough commons for payment.

Legacy API endpoints

We will continue to provide updates and support for the endpoints marked as Legacy, so your existing code will not break. However, in an effort to bring all the endpoints to a healthy level of standardization and consistency, please consider migrating to the non-legacy endpoints.

API 2.0.0 will mark the discontinuation of the Legacy endpoints.

Tags

getTags

Get list of available tags ordered by priority.

query Parameters
isCategory
string
Enum: "true" "1" "false" "0"

Filter tags by column isCategory. By not specifying this param, the endpoint will return all tags. To get only tags that are categories set the param to one of the values "true" or "1". If you specify any other value the endpoint will return non-category tags.

beforeTime
string
Enum: "1h" "24h" "7d" "30d" "ALL"

Changes totalVolume and beforeFloorPrice key values for tags. By not specifing this param, or setting the ALL value will not use any time frame for total volume and set beforeFloorPrice to null.

includeIsVirtual
string
Enum: "true" "1"

Optional, set to true or 1 to receive ordinal collections alongside rare-sats tags.

header Parameters
X-MGST-API-KEY
required
string

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "count": "string"
}

getTagFloorPriceHistory

Get paginated history of floor prices for a given tag.

query Parameters
tagId
required
string <uuid>

The tag id to get the floor price history.

offset
required
number

Start offset to get history. Used for pagination

limit
required
number

Number of history to get. Used for pagination. Maximum limit is 10000.

timeOrder
required
string
Enum: "ASC" "DESC"

Order the history from the response by timestamp. Choose between ASC or DESC order.

header Parameters
X-MGST-API-KEY
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

getTagIdBySlug

Get the tagId, name and picture for a given tag slug.

path Parameters
slug
required
string

The slug of the tag to get.

header Parameters
X-MGST-API-KEY
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "picture": "string"
}

getCollections

Get paginated list of available ordinals collections.

query Parameters
offset
required
number

Start offset to get collections. Used for pagination

limit
required
number

Number of collections to get. Used for pagination. Maximum limit is 50.

beforeTime
string
Enum: "1h" "24h" "7d" "30d" "ALL"

Changes totalVolume and beforeFloorPrice key values for tags. By not specifing this param, or setting the ALL value will not use any time frame for total volume and set beforeFloorPrice to null.

sortBy
string
Enum: "WEEK_VOLUME_ASC" "WEEK_VOLUME_DESC"

Order the collections from the response by a column with a given sort direction. By default (if missing) will use the natural sorting from frontend.

header Parameters
X-MGST-API-KEY
required
string

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "count": "string"
}

Listing

getListings

Get list of available listings.

header Parameters
X-MGST-API-KEY
required
string
Request Body schema: application/json
offset
required
number <int64>

Start index to get listings. Used for pagination.

limit
required
number <int64>

How many listings to fetch. Used for pagination. Maximum limit 50.

tagId
string <uuid>

Get tagId from /tag. Used to filter listings which have at least a satoshi that has all required sattributes of the given tag.

additionalSattributes
Array of strings <uuid> [ items <uuid > ]

List of Sattribute ids. Get them from /tag response under the additionalSattributes field. Used in combination with tagId to allow more filtering of the listings. Will fetch listings which have at least a satoshi that hash all required sattributes of the given tag, plus the given list of additional sattributes given.

minUpdatedAt
string <date-time>

Filter listings that were updated after the given date-time (is inclusive).

maxUpdatedAt
string <date-time>

Filter listings that were updated before the given date-time (is inclusive).

minPrice
string <int64>

Value in satoshis. Filter listings that have a price greater or equal to the given value.

maxPrice
string <int64>

Value in satoshis. Filter listings that have a price lower or equal to the given value.

minUtxoSize
string <int64>

Value in satoshis. Filter listings that have an utxo value greater or equal to the given value. An utxo's value is the number of satoshis contained by the utxo, and the value used in tx if you don't take in consideration the special satoshis.

maxUtxoSize
string <int64>

Value in satoshis. Filter listings that have an utxo value lower or equal to the given value. An utxo's value is the number of satoshis contained by the utxo, and the value used in tx if you don't take in consideration the special satoshis.

minSatRange
string <int64>

Sat value. Filter listings that contains satoshis greater or equal to the given value.

maxSatRange
string <int64>

Sat value. Filter listings that contains satoshis greater or equal to the given value.

minBlockNumber
string <int32>

Filter listings that contains satoshis created in or after the given block. For a given sat, we consider the block number, the block in which the sat first appeared (in which was created), not the block which created the utxo, that contains the sat now.

maxBlockNumber
string <int32>

Filter listings that contains satoshis created before or in the given block. For a given sat, we consider the block number, the block in which the sat first appeared (in which was created), not the block which created the utxo, that contains the sat now.

minBlockTimestamp
string <date-time>

Filter listings that contains satoshis created after the given timestamp (is inclusive). For a given sat, we consider the block timestamp, the timestamp in which the sat first appeared (in which was created), not the timestamp creation of the utxo in which it appears now.

maxBlockTimestamp
string <date-time>

Filter listings that contains satoshis created before the given timestamp (is inclusive). For a given sat, we consider the block timestamp, the timestamp in which the sat first appeared (in which was created), not the timestamp creation of the utxo in which it appears now.

orderByColumnWithDirection
Array of strings
Items Enum: "PRICE_ASC" "PRICE_DESC" "UPDATED_AT_ASC" "UPDATED_AT_DESC" "BLOCK_NUMBER_ASC" "BLOCK_NUMBER_DESC" "BLOCK_TIMESTAMP_ASC" "BLOCK_TIMESTAMP_DESC" "RANGE_START_ASC" "RANGE_START_DESC" "RELATIVE_UNIT_PRICE_ASC" "RELATIVE_UNIT_PRICE_DESC"

Order the listings from the response by a column with a given sort direction. If you specify the same column with both sort direction, the descending order will be used, regardless of the order you place them in the array (you shouldn't send them both anyways). If you give multiple order values, the priority in sorting is given by the above list. Ex. If you send ["PRICE_ASC", "CREATED_AT_ASC"], the listings will be sorted by price first, than by createdAt.

satName
string

Filter listings that contains satoshis that contain the given sat name. Must be between 1 and 11 lowercase letters.

includePendingPurchase
boolean

Set to true to include listings that are pending to be bought.

isVirtual
boolean

Works only if not sending 'tagId'. Include in response listings that contain at least an ordinal inscription.

Responses

Request samples

Content type
application/json
{
  • "offset": 0,
  • "limit": 0,
  • "tagId": "f69eb9f1-ae9f-4086-b25c-c39758a43fb3",
  • "additionalSattributes": [
    ],
  • "minUpdatedAt": "2019-08-24T14:15:22Z",
  • "maxUpdatedAt": "2019-08-24T14:15:22Z",
  • "minPrice": "string",
  • "maxPrice": "string",
  • "minUtxoSize": "string",
  • "maxUtxoSize": "string",
  • "minSatRange": "string",
  • "maxSatRange": "string",
  • "minBlockNumber": "string",
  • "maxBlockNumber": "string",
  • "minBlockTimestamp": "2019-08-24T14:15:22Z",
  • "maxBlockTimestamp": "2019-08-24T14:15:22Z",
  • "orderByColumnWithDirection": [ ],
  • "satName": "string",
  • "includePendingPurchase": true,
  • "isVirtual": true
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "count": "string"
}

getRbfListings ( Instant Snipe )

Get a list of RBF listing for a given transaction id.

path Parameters
txId
required
string

The transaction id to get the RBF listings.

header Parameters
X-MGST-API-KEY
required
string

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "count": "string",
  • "isPlatformTransaction": true
}

getMessageForBulkListing

Get a message to be signed by the seller to prepare for creating a listing of an utxo. For update, you need to call the endpoint GET /psbt/listing again with the updated arguments.

header Parameters
X-MGST-API-KEY
required
string
Request Body schema: application/json
sellerAddress
required
string

The address of the seller's ordinals wallet owning (some of) the UTXOs to be listed.

sellerPublicKey
required
string

The public key of the seller's ordinals wallet owning (some of) the UTXOs to be listed.

sellerPaymentAddress
string or null

The address of the seller's payment wallet owning (some of) the UTXOs to be listed.

sellerPaymentPublicKey
string or null

The public key of the seller's payment wallet owning (some of) the UTXOs to be listed.

required
Array of objects (ListingItemSellInfo)

Information about each utxo that is going to be listed. The price and sellerReceiveAddress can be specified differently for each utxo.

Responses

Request samples

Content type
application/json
{
  • "sellerAddress": "string",
  • "sellerPublicKey": "string",
  • "sellerPaymentAddress": "string",
  • "sellerPaymentPublicKey": "string",
  • "listings": [
    ]
}

Response samples

Content type
application/json
{
  • "psbtToHex": "string",
  • "psbtToBase64": "string"
}

createNewListing

Legacy Endpoint

Note: You should migrate to the endpoint POST /external/v1/listing/bulk

Used to create or update a listing. The update works only after deleting the listing.

Restrictions: Do not use legacy wallets! The buying process cannot include inputs signed by legacy wallets

header Parameters
X-MGST-API-KEY
required
string
Request Body schema: application/json
utxo
required
string <txid:vout>

The utxo that is going to be listed by the user. The utxo must be owned by the sellerAddress.

price
required
string <int64>

The value in satoshis as payment for the utxo requested by the user. Must be at least 546 sats and smaller than 2000000000000000 sats. Also, the price cannot be lower than the utxo base value.

sellerAddress
required
string

The seller wallet's address owning the utxo to be listed.

sellerPublicKey
required
string

The seller wallet's public key from the address owning the utxo to be listed.

sellerReceiveAddress
required
string

The address where to send the price requested for the listing. Can be the same as the sellerAddress if the user wants to receive the payment for the listing on the same wallet. The user can also set a different address, other than the one used to made the listing, to receive the payment.

sellerSignature
required
string <base64>

The sell message in base64 for the given utxo. The message must be signed by the seller. You can get the message to be signed from the endpoint GET /psbt/listing.

Responses

Request samples

Content type
application/json
{
  • "utxo": "b224d522dc25ba984f774498dda6808a97e380abf4bf8e0ac39a51a0b5d91e10:0",
  • "price": "string",
  • "sellerAddress": "string",
  • "sellerPublicKey": "string",
  • "sellerReceiveAddress": "string",
  • "sellerSignature": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "utxo": "b224d522dc25ba984f774498dda6808a97e380abf4bf8e0ac39a51a0b5d91e10:0",
  • "utxoValue": "string",
  • "sellerAddress": "string",
  • "sellerReceiveAddress": "string",
  • "type": "OWNER",
  • "status": "UNDECORATED",
  • "buyerTxId": "string",
  • "price": "string",
  • "utxoSize": "string",
  • "mainTagId": "string",
  • "lowestSatIndex": "string",
  • "lowestSatBlockNumber": 0,
  • "lowestSatBlockTimestamp": "2019-08-24T14:15:22Z",
  • "relativeUnitPrice": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "deletedAt": "string",
  • "purchasedAt": "string"
}

createNewListings

Used to create or update a batch of listings. The update works only after deleting the listing.

Restrictions: Do not use legacy wallets! The buying process cannot include inputs signed by legacy wallets

header Parameters
X-MGST-API-KEY
required
string
Request Body schema: application/json
sellerAddress
required
string

The address of the seller's ordinals wallet owning (some of) the UTXOs to be listed.

sellerPublicKey
required
string

The public key of the seller's ordinals wallet owning (some of) the UTXOs to be listed.

sellerPaymentAddress
string or null

The address of the seller's payment wallet owning (some of) the UTXOs to be listed.

sellerPaymentPublicKey
string or null

The public key of the seller's payment wallet owning (some of) the UTXOs to be listed.

sellerSignature
required
string <base64>

The sell message in base64 for the given utxo. The message must be signed by the seller. You can get the message to be signed from the endpoint GET /psbt/listing.

required
Array of objects (ListingItemSellInfo)

Information about each utxo that is going to be listed. The price and sellerReceiveAddress can be specified differently for each utxo.

Responses

Request samples

Content type
application/json
{
  • "sellerAddress": "string",
  • "sellerPublicKey": "string",
  • "sellerPaymentAddress": "string",
  • "sellerPaymentPublicKey": "string",
  • "sellerSignature": "string",
  • "listings": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

deleteBulkListings

Delete a batch of listings.

query Parameters
listingIds
required
Array of strings <uuid> [ items <uuid > ]

List of listing ids to delete, comma separated.

header Parameters
X-MGST-API-KEY
required
string

Responses

Response samples

Content type
application/json
{
  • "deleted": true
}

getListingById

Get a listing by id

path Parameters
listingId
required
string

The id of the listing to get.

header Parameters
X-MGST-API-KEY
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "utxo": "b224d522dc25ba984f774498dda6808a97e380abf4bf8e0ac39a51a0b5d91e10:0",
  • "utxoValue": "string",
  • "sellerAddress": "string",
  • "sellerReceiveAddress": "string",
  • "status": "UNDECORATED",
  • "type": "OWNER",
  • "buyerTxId": "string",
  • "price": "string",
  • "utxoSize": "string",
  • "mainTagId": "f6a82061-fc55-4abe-8700-c5bc58541215",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "purchasedAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "lowestSatIndex": "string",
  • "lowestSatBlockNumber": 0,
  • "lowestSatBlockTimestamp": "2019-08-24T14:15:22Z",
  • "relativeUnitPrice": "string",
  • "minFeeRate": 0,
  • "minFeeTotal": 0,
  • "sellerVerified": true,
  • "sellerDisplayName": "string",
  • "sellerAvatarImageUrl": "string",
  • "sellerWebsiteUrl": "string",
  • "specialSatsCount": "string",
  • "includedInCollections": [
    ],
  • "mainSatoshi": {
    },
  • "mainTag": {
    },
  • "mainSecondaryTags": [
    ],
  • "additionalDisplayRareSatSattributes": [
    ],
  • "runes": [
    ]
}

deleteListing

Delete an active listing.

path Parameters
listingId
required
string

The id of the listing to be deleted.

header Parameters
X-MGST-API-KEY
required
string

Responses

Response samples

Content type
application/json
{
  • "deleted": true
}

Buying

getPreparedMessageForBuying

First call when buying listings. Get a message to be signed by the buyer to prepare for buying.

query Parameters
buyerAddress
required
string

The buyer wallet's address used for paying.

buyerPublicKey
required
string

The buyer wallet's public key from the address used for paying.

feeRateTier
required
string (FeeRateTier)
Enum: "fastestFee" "halfHourFee" "hourFee" "minimumFee"

Rate fee tier chosen by user for the buy transaction.

feeRate
number <int64>

Rate fee chosen by user for the buy transaction. Value in sats. Either feeRate or feeRateTier should be sent, but not both of them.

listingIds
required
Array of strings <uuid> [ items <uuid > ]

Comma separated list of IDs for the listings that you're preparing to buy.

optimizationLevel
number <int32>
Enum: 0 1

Configure the optimization of the transaction and the prepared created. Values between 0 for no optimization, and 1 to optimize. When setting optimization level 1 the receiveAddress for each address from the listings must be the same. Default 0 if not given.

overrideDisableSpendables
boolean

Optional, default set to false if not sent. If set to true, the endpoint will not use the spendables from the user's wallet to create the prepared message. View more

header Parameters
X-MGST-API-KEY
required
string

Responses

Response samples

Content type
application/json
{
  • "psbtToHex": "string",
  • "psbtToBase64": "string",
  • "hasEnoughDummyUtxos": true,
  • "increasedFeeRate": 0
}

postPreparedMessageForBuying

Second call when buying listings. Broadcast the prepared message, signed by the user, to prepare for buying.

header Parameters
X-MGST-API-KEY
required
string
Request Body schema: application/json
psbtBase64
required
string <base64>

The prepared message, signed by the user.

Responses

Request samples

Content type
application/json
{
  • "psbtBase64": "string"
}

Response samples

Content type
application/json
{
  • "txId": "string"
}

getBulkBuyingMessage

Third call when buying listings. Get the message to be signed by the buyer to make the buy.

header Parameters
X-MGST-API-KEY
required
string
Request Body schema: application/json
required
Array of objects (ListingItemBuyInfo)

Information about each listings that is going to be bought, where to send each utxo bought.

buyerAddress
required
string

The buyer wallet's address used for paying.

buyerPublicKey
required
string

The buyer wallet's public key from the address used for paying.

feeRateTier
required
string (FeeRateTier)
Enum: "fastestFee" "halfHourFee" "hourFee" "minimumFee"

Rate fee tier chosen by user for the buy transaction.

feeRate
required
number <int64>

Rate fee chosen by user for the buy transaction. Value in sats. Either feeRate or feeRateTier should be sent, but not both of them.

optimizationLevel
number <int32>
Default: 0
Enum: 0 1

Configure the optimization of the transaction and the prepared created. Values between 0 for no optimization, and 1 to optimize. When setting optimization level 1 the receiveAddress for each address from the listings must be the same.

receiveAddress
string

If the optimization level is set to 1, this key is required and needs to be set on all listings from the request.

overrideDisableSpendables
boolean
Default: false

Optional, default set to false if not sent. If set to true, the endpoint will not use the spendables from the user's wallet to create the prepared message. View more

Responses

Request samples

Content type
application/json
{
  • "listings": [
    ],
  • "buyerAddress": "string",
  • "buyerPublicKey": "string",
  • "feeRateTier": "fastestFee",
  • "feeRate": 0,
  • "optimizationLevel": 0,
  • "receiveAddress": "string",
  • "overrideDisableSpendables": false
}

Response samples

Content type
application/json
{
  • "psbtToHex": "string",
  • "psbtToBase64": "string",
  • "structure": "SPECIAL_SAT",
  • "increasedFeeRate": 0,
  • "saleableListings": [
    ],
  • "usedRuneUtxos": [
    ],
  • "feeRate": 0
}

postBulkBuyingMessage

Fourth and final call when buying listings. Broadcast the buying message, signed by user, to finalize the buying.

header Parameters
X-MGST-API-KEY
required
string
Request Body schema: application/json
required
Array of objects (ListingItemBuyInfo)

Information about each listings that is going to be bought, where to send each utxo bought.

buyerAddress
required
string

The buyer wallet's address used for paying.

buyerPublicKey
required
string

The buyer wallet's public key from the address used for paying.

buyerSignature
required
string <base64>

The signed message in base64 for buying. The message must be signed by the buyer. You can get the message to be signed from the endpoint /psbt/buying.

buyerWalletType
required
string
Enum: "xverse_wallet" "unisat_wallet"

Specify what wallet is used to make the buying.

optimizationLevel
number <int32>
Default: 0
Enum: 0 1

Configure the optimization of the transaction and the prepared created. Values between 0 for no optimization, and 1 to optimize. When setting optimization level 1 the receiveAddress for each address from the listings must be the same.

receiveAddress
string

If the optimization level is set to 1, this key is required and needs to be set on all listings from the request.

Responses

Request samples

Content type
application/json
{
  • "listings": [
    ],
  • "buyerAddress": "string",
  • "buyerPublicKey": "string",
  • "buyerSignature": "string",
  • "buyerWalletType": "xverse_wallet",
  • "optimizationLevel": 0,
  • "receiveAddress": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

getPendingBuyingsForAddress

Get list of pending buying transactions for the given address.

path Parameters
address
required
string

The wallet address to check for pending buying transactions.

header Parameters
X-MGST-API-KEY
required
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 0
}

Offer

postPsbtOfferCreateMessage

Get a message to be signed by the buyer to prepare for creating offers for given utxos.

Step 1 in creating an offer. This api can be used to create multiple offers.

header Parameters
X-MGST-API-KEY
required
string
Request Body schema: application/json
Array
utxo
required
string <txid:vout>

The utxo that the user wants to buy and make the offer to the owner.

makerAddress
required
string

The address of the user that wants to buy the utxo.

makerPublicKey
required
string

The public key of the user that wants to buy the utxo.

makerReceiveAddress
required
string

The address where to send the utxo bought.

price
required
number

The value in satoshis as payment for the utxo requested by the user.

paymentUtxos
required
Array of strings <txid:vout> [ items <txid:vout > ]

List of utxos used to pay the transaction.

feeRateTier
required
string (FeeRateTier)
Enum: "fastestFee" "halfHourFee" "hourFee" "minimumFee"

Rate fee tier chosen by user for the buy transaction.

feeRate
number <int64>

Rate fee chosen by user for the buy transaction. Value in sats. Either feeRate or feeRateTier should be sent, but not both of them.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

postPsbtOfferAcceptMessage

Get a message to be signed by the seller to prepare for accepting offers for given utxos.

Step 1 in accepting an offer. This api can be used to accepet multiple offers.

header Parameters
X-MGST-API-KEY
required
string
Request Body schema: application/json
Array
offerId
required
string <uuid>

The unique identifier for the offer.

takerAddress
required
string

The address of the user who owns the utxo and accepts the offer.

takerPublicKey
required
string

The public key of the user who owns the utxo and accepts the offer.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

postOfferCreate

Second call when creating offers.

header Parameters
X-MGST-API-KEY
required
string
Request Body schema: application/json
Array
utxo
required
string <txid:vout>

The utxo that the user wants to buy and make the offer to the owner.

makerAddress
required
string

The address of the user that wants to buy the utxo.

makerPublicKey
required
string

The public key of the user that wants to buy the utxo.

makerReceiveAddress
required
string

The address where to send the utxo bought.

price
required
number

The value in satoshis as payment for the utxo requested by the user.

paymentUtxos
required
Array of strings <txid:vout> [ items <txid:vout > ]

List of utxos used to pay the transaction.

feeRateTier
required
string (FeeRateTier)
Enum: "fastestFee" "halfHourFee" "hourFee" "minimumFee"

Rate fee tier chosen by user for the buy transaction.

feeRate
number <int64>

Rate fee chosen by user for the buy transaction. Value in sats. Either feeRate or feeRateTier should be sent, but not both of them.

makerSignature
required
string

The signed message of the user from /psbt/offer/create

duration
required
string <date-time>

The duration of the offer.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

postOfferAccept

Second call when accepting offers.

header Parameters
X-MGST-API-KEY
required
string
Request Body schema: application/json
Array
offerId
required
string <uuid>

The unique identifier for the offer.

takerAddress
required
string

The address of the user who owns the utxo and accepts the offer.

takerPublicKey
required
string

The public key of the user who owns the utxo and accepts the offer.

takerSignature
required
string

The signed message of the user from /psbt/offer/accept

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

getListOfOffers

Get list of available offers.

header Parameters
X-MGST-API-KEY
required
string
Request Body schema: application/json
utxo
required
string <txid:vout>

The utxo that the user wants to buy and make the offer to the owner.

makerAddress
required
string

The address of the user that wants to buy the utxo and made the offer.

offset
required
number <int64>

Start index to get offers. Used for pagination

limit
required
number <int64>

Number of offers to get. Used for pagination. Maximum limit 50.

minPrice
string <int64>

The minimum value in satoshis as payment for the utxo requested by the user.

maxPrice
string <int64>

The maximum value in satoshis as payment for the utxo requested by the user.

minUpdatedAt
string <date-time>

The minimum date-time when the offer was updated.

maxUpdatedAt
string <date-time>

The maximum date-time when the offer was updated.

orderByColumnWithDirection
Array of strings
Items Enum: "PRICE_ASC" "PRICE_DESC" "UPDATED_AT_ASC" "UPDATED_AT_DESC"

Order the offers by the given column and direction.

Responses

Request samples

Content type
application/json
{
  • "utxo": "string",
  • "makerAddress": "string",
  • "offset": 0,
  • "limit": 0,
  • "minPrice": "string",
  • "maxPrice": "string",
  • "minUpdatedAt": "2019-08-24T14:15:22Z",
  • "maxUpdatedAt": "2019-08-24T14:15:22Z",
  • "orderByColumnWithDirection": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "count": "string"
}

deleteOffer

Delete an active offer.

header Parameters
X-MGST-API-KEY
required
string
Request Body schema: application/json
Array
offerId
string <uuid>

The unique identifier for the offer to be deleted.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "deleted": true
}

Runes

getRuneFloorPriceHistory

Get paginated history of floor prices for a given rune.

query Parameters
runeName
required
string

The rune name (spaced version) to get the floor price history.

offset
required
number

Start offset to get history. Used for pagination

limit
required
number

Number of history to get. Used for pagination. Maximum limit is 10000.

timeOrder
required
string
Enum: "ASC" "DESC"

Order the history from the response by timestamp. Choose between ASC or DESC order.

header Parameters
X-MGST-API-KEY
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Wallet

getListingsByWalletRareSats

Get listings owned by a wallet address containing at least one rare-sat.

query Parameters
address
required
string

The wallet address to get the listings.

paymentAddress
string

The payment address associated with the wallet.

header Parameters
X-MGST-API-KEY
required
string

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "count": "string"
}

getListingsByWalletInscriptions

Get listings owned by a wallet address containing at least one inscription.

query Parameters
address
required
string

The wallet address to get the listings.

paymentAddress
string

The payment address associated with the wallet.

header Parameters
X-MGST-API-KEY
required
string

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "count": "string"
}

getListingsByWalletRunes

Get listings owned by a wallet address containing at least one rune.

query Parameters
address
required
string

The wallet address to get the listings.

paymentAddress
string

The payment address associated with the wallet.

header Parameters
X-MGST-API-KEY
required
string

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "count": "string"
}

getRareSatsPortfolio

PREMIUM

Get the portfolio of rare-sats for a given address.

query Parameters
address
required
string

The wallet address to get the portfolio.

paymentAddress
string

The payment address associated with the wallet.

header Parameters
X-MGST-API-KEY
required
string

Responses

Response samples

Content type
application/json
{
  • "totalRareSatsValue": "string",
  • "items": [
    ]
}

getInscriptionsPortfolio

PREMIUM

Get the portfolio of inscriptions for a given address.

query Parameters
address
required
string

The wallet address to get the portfolio.

paymentAddress
string

The payment address associated with the wallet.

header Parameters
X-MGST-API-KEY
required
string

Responses

Response samples

Content type
application/json
{
  • "totalInscriptionsValue": "string",
  • "items": [
    ]
}

getRunePortfolio

PREMIUM

Get the portfolio of runes for a given address.

query Parameters
address
required
string

The wallet address to get the portfolio.

paymentAddress
string

The payment address associated with the wallet.

header Parameters
X-MGST-API-KEY
required
string

Responses

Response samples

Content type
application/json
{
  • "totalRuneValue": "string",
  • "items": [
    ]
}