API Docs

Download OpenAPI specification:Download

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

To request an API key, please apply here.

General information

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.

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.

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>

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.

minCreatedAt
string <date-time>

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

maxCreatedAt
string <date-time>

Filter listings that were created 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" "CREATED_AT_ASC" "CREATED_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.

Responses

Request samples

Content type
application/json
{
  • "offset": 0,
  • "limit": 0,
  • "tagId": "f69eb9f1-ae9f-4086-b25c-c39758a43fb3",
  • "additionalSattributes": [
    ],
  • "minCreatedAt": "2019-08-24T14:15:22Z",
  • "maxCreatedAt": "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": [ ]
}

Response samples

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

getMessageForListing

Legacy Endpoint

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

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.

query Parameters
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.

utxo
required
string <txid:vout>
Example: utxo=b224d522dc25ba984f774498dda6808a97e380abf4bf8e0ac39a51a0b5d91e10:0

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.

header Parameters
X-MGST-API-KEY
required
string

Responses

Response samples

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

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 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.

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",
  • "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",
  • "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",
  • "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 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.

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",
  • "sellerSignature": "string",
  • "listings": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

deleteBulkListings

Delete a batch of listings.

query Parameters
listingIds
required
Array of strings <uuid>

List of listing ids to delete, comma separated.

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",
  • "buyerTxId": "string",
  • "price": "string",
  • "utxoSize": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "lowestSatIndex": "string",
  • "lowestSatBlockNumber": 0,
  • "lowestSatBlockTimestamp": "2019-08-24T14:15:22Z",
  • "relativeUnitPrice": "string",
  • "sellerVerified": true,
  • "sellerDisplayName": "string",
  • "sellerAvatarImageUrl": "string",
  • "sellerWebsiteUrl": "string",
  • "specialSatsCount": "string",
  • "mainSatoshi": {
    },
  • "mainTag": {
    }
}

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.

numberOfListings
required
string <int32> >= 1

The number of listings that the user wants to buy.

header Parameters
X-MGST-API-KEY
required
string

Responses

Response samples

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

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"
}

getBuyingMessage

Legacy Endpoint

Note: You should migrate to the endpoint POST /external/v1/psbt/buying

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

query Parameters
listingIds
required
string <uuid>

List of listing ids to buy

buyerAddress
required
string

The buyer wallet's address used for paying.

buyerReceiveAddress
required
string

The address where to send the utxos bought. Can be the same as the buyerAddress if the users wants to send the utxos bought to the address with which he makes the payment. The user can also set a different address, other than the pay address, to send the utxos bought.

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

Rate fee tier chosen by user for the buy transaction.

buyerPublicKey
required
string

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

header Parameters
X-MGST-API-KEY
required
string

Responses

Response samples

Content type
application/json
{
  • "psbtToHex": "string",
  • "psbtToBase64": "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.

Responses

Request samples

Content type
application/json
{
  • "listings": [
    ],
  • "buyerAddress": "string",
  • "buyerPublicKey": "string",
  • "feeRateTier": "fastestFee"
}

Response samples

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

postBuyingMessage

Legacy Endpoint

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

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
listingIds
required
Array of strings <uuid> non-empty

List of listing ids that the user wants to buy.

buyerAddress
required
string

The buyer wallet's address used for paying.

buyerReceiveAddress
required
string

The address where to send the utxos bought. Needs to be the same as the one specified in the request for the psbt buying message.

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

Rate fee tier chosen by user for the buy transaction.

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
string
Enum: "xverse_wallet" "unisat_wallet"

Specify what wallet is used to make the buying.

Responses

Request samples

Content type
application/json
{
  • "listingIds": [
    ],
  • "buyerAddress": "string",
  • "buyerReceiveAddress": "string",
  • "feeRateTier": "fastestFee",
  • "buyerPublicKey": "string",
  • "buyerSignature": "string",
  • "buyerWalletType": "xverse_wallet"
}

Response samples

Content type
application/json
[
  • {
    }
]

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.

Responses

Request samples

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

Response samples

Content type
application/json
[
  • {
    }
]