openapi: 3.0.1
info:
title: Magic Eden Bitcoin Ordinals API
description: Aggregated Magic Eden Bitcoin/Ordinals API covering ordinal collections, rare sats, runes (orders, swaps, sweeping,
market sells), block activities, and wallet balances.
version: v2
termsOfService: https://magiceden.io/terms-of-service.pdf
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api-mainnet.magiceden.dev/v2
components:
schemas:
BlockActivitySchema:
type: object
properties:
inscription:
type: object
properties:
id:
type: string
contentType:
type: string
contentMedia:
type: string
contentLength:
type: number
nullable: true
number:
type: number
nullable: true
sat:
type: number
nullable: true
satName:
type: string
nullable: true
satRarity:
type: string
nullable: true
satBlockHeight:
type: number
nullable: true
satBlockTime:
type: string
nullable: true
genesisTransaction:
type: string
genesisTransactionBlockTime:
type: string
nullable: true
genesisTransactionBlockHeight:
type: number
nullable: true
genesisTransactionBlockHash:
type: string
nullable: true
parentInscriptionId:
type: string
nullable: true
metaprotocol:
type: string
nullable: true
activityType:
type: string
blockHeight:
type: number
blockHash:
type: string
txId:
type: string
location:
type: string
address:
type: string
output:
type: string
value:
type: number
offset:
type: number
timestamp:
type: number
oldLocation:
type: string
nullable: true
oldAddress:
type: string
nullable: true
createdAt:
type: string
format: date-time
CollectionStatSchema:
type: object
properties:
floorPrice:
type: string
inscriptionNumberMin:
type: string
inscriptionNumberMax:
type: string
owners:
type: string
pendingTransactions:
type: string
supply:
type: string
totalListed:
type: string
totalVolume:
type: string
CollectionSchema:
type: object
properties:
symbol:
type: string
name:
type: string
imageURI:
type: string
chain:
type: string
description:
type: string
supply:
type: integer
twitterLink:
type: string
discordLink:
type: string
websiteLink:
type: string
min_inscription_number:
type: integer
max_inscription_number:
type: integer
createdAt:
type: string
RareSatsGetListingsSchema:
type: object
properties:
tokens:
type: array
items:
$ref: '#/components/schemas/RareSatsGetListingsItem'
RareSatsGetListingsItem:
type: object
properties:
id:
type: string
genesisTransaction:
type: string
genesisTransactionBlockTime:
type: string
genesisTransactionBlockHash:
type: string
genesisTransactionBlockHeight:
type: number
outputValue:
type: number
owner:
type: string
listed:
type: boolean
listedAt:
type: string
listedPrice:
type: number
listedSellerReceiverAddress:
type: string
minBlockHeight:
type: number
maxBlockHeight:
type: number
minBlockTime:
type: string
maxBlockTime:
type: string
minSatRange:
type: number
maxSatRange:
type: number
minUnitPrice:
type: number
maxUnitPrice:
type: number
satRanges:
type: array
items:
$ref: '#/components/schemas/RareSatsSatRanges'
SatributesSchema:
type: string
enum:
- Common
- Uncommon
- Rare
- Epic
- Legendary
- Black Uncommon
- Black Rare
- Black Epic
- Black Legendary
- Mythic
- Palindrome
- Uniform Palinception
- Perfect Palinception
- Paliblock Palindrome
- Vintage
- Nakamoto
- Block 9
- Block 9 450x
- Block 286
- Block 78
- Block 666
- First Transaction
- Pizza
- Taproot
- Alpha
- Omega
- JPEG
- Legacy
- Hitman
SatributesArraySchema:
type: array
items:
$ref: '#/components/schemas/SatributesSchema'
RareSatsSatRanges:
type: object
properties:
id:
type: string
from:
type: number
to:
type: number
parentFrom:
type: number
parentTo:
type: number
satributes:
$ref: '#/components/schemas/SatributesArraySchema'
amount:
type: number
sequence:
type: number
unitPrice:
type: number
blockInfo:
$ref: '#/components/schemas/BlockInfoSchema'
BlockInfoSchema:
type: object
properties:
blockHash:
type: string
blockHeight:
type: number
blockTime:
type: string
ItemSchema:
type: object
properties:
chain:
type: string
collection:
type: object
properties:
chain:
type: string
imageURI:
type: string
name:
type: string
symbol:
type: string
contentURI:
type: string
contentType:
type: string
contentBody:
type: string
contentPreviewURI:
type: string
sat:
type: number
satName:
type: string
satRarity:
type: string
genesisTransaction:
type: string
genesisTransactionBlockTime:
type: string
genesisTransactionBlockHeight:
type: number
genesisTransactionBlockHash:
type: string
inscriptionNumber:
type: number
meta:
type: object
properties:
name:
type: string
attributes:
type: array
items:
type: object
properties:
trait_type:
type: string
value:
type: string
owner:
type: string
collectionSymbol:
type: string
location:
type: string
locationBlockHeight:
type: number
locationBlockTime:
type: string
locationBlockHash:
type: string
outputValue:
type: number
output:
type: string
mempoolTxId:
type: string
mempoolTxTimestamp:
type: string
listed:
type: boolean
listedAt:
type: string
listedPrice:
type: number
listedMakerFeeBp:
type: number
listedSellerReceiverAddress:
type: string
listedForMint:
type: boolean
brc20TransferAmt:
type: number
brc20ListedUnitPrice:
type: number
domain:
type: string
RareSatsItemAdditionalSchema:
type: object
properties:
rareSatsUtxo:
$ref: '#/components/schemas/RareSatsUtxoSchema'
RareSatsUtxoSchema:
type: object
properties:
id:
type: string
txId:
type: string
vout:
type: number
value:
type: number
address:
type: string
blockInfo:
$ref: '#/components/schemas/BlockInfoSchema'
listedPrice:
type: number
satRanges:
type: array
items:
$ref: '#/components/schemas/RareSatsSatRanges'
hasUninscribedRareSat:
type: boolean
floorValue:
type: number
RareSatsSatRangePriceSchema:
type: object
required:
- id
- from
- to
- parentFrom
- parentTo
- satributes
properties:
id:
type: string
from:
type: number
to:
type: number
parentFrom:
type: number
parentTo:
type: number
unitPrice:
type: number
satributes:
$ref: '#/components/schemas/SatributesArraySchema'
RareSatsListingPSBTResultSchema:
type: object
required:
- sellerReceiveAddress
- price
- utxoId
- unsignedListingPSBTBase64
- makerFee
properties:
sellerReceiveAddress:
type: string
price:
type: number
utxoId:
type: string
unsignedListingPSBTBase64:
type: string
makerFee:
type: number
publicKey:
type: string
RareSatsListingsPSBTRequestSchema:
type: object
required:
- listings
properties:
listings:
type: array
items:
$ref: '#/components/schemas/RareSatsListingsPSBTRequestSchemaSingleItem'
RareSatsListingsPSBTRequestSchemaSingleItem:
type: object
required:
- utxoId
- satRangePrices
properties:
sellerReceiveAddress:
type: string
description: Default to the utxo owner address if not specified
publicKey:
type: string
utxoId:
type: string
satRangePrices:
type: array
items:
$ref: '#/components/schemas/RareSatsSatRangePriceSchema'
RareSatsListingsPSBTResultSchema:
type: object
required:
- results
- failed
- unsignedCombinedPSBTBase64
- toSignInputs
- toSignSigHash
properties:
results:
type: array
items:
$ref: '#/components/schemas/RareSatsListingPSBTResultSchema'
failed:
type: array
items:
type: string
unsignedCombinedPSBTBase64:
type: string
description: The PSBT to be signed by the owner of the rare sats
toSignInputs:
type: array
items:
type: number
toSignSigHash:
type: number
RareSatsListingSchema:
type: object
required:
- sellerReceiveAddress
- price
- utxoId
- satRangePrices
- signedListingPSBTBase64
- makerFee
properties:
sellerReceiveAddress:
type: string
price:
description: The total price of the listed rare sats utxo. Must be equal to the sum of the price of each sat range
type: number
utxoId:
type: string
satRangePrices:
type: array
items:
$ref: '#/components/schemas/RareSatsSatRangePriceSchema'
signedListingPSBTBase64:
description: Same as the signedCombinedPSBTBase64
type: string
makerFee:
description: Will be deprecated
type: number
publicKey:
type: string
RareSatsListingRequestSchema:
type: object
required:
- listings
- signedCombinedPSBTBase64
properties:
listings:
type: array
items:
$ref: '#/components/schemas/RareSatsListingSchema'
signedCombinedPSBTBase64:
description: The selling PSBT must be signed by the rare sats owner. The unsigned PSBT can be generated using the
`POST /listing-psbt` endpoint
type: string
RareSatsListingResultSchema:
type: object
required:
- ok
- listed
- failed
properties:
ok:
type: boolean
listed:
type: number
failed:
type: array
items:
type: string
RuneActivitySchema:
type: object
properties:
id:
type: string
kind:
type: string
oldOwner:
type: string
nullable: true
newOwner:
type: string
nullable: true
rune:
type: string
amount:
type: string
nullable: true
txValue:
type: string
nullable: true
txId:
type: string
nullable: true
txBlockTime:
type: string
format: date-time
nullable: true
txBlockHeight:
type: integer
nullable: true
txBlockHash:
type: string
nullable: true
deletedAt:
type: string
format: date-time
nullable: true
createdAt:
type: string
format: date-time
listedPrice:
type: string
nullable: true
listedMakerFeeBp:
type: integer
nullable: true
listedTakerFeeBp:
type: integer
nullable: true
btcUsdPrice:
type: string
nullable: true
sellerPaymentReceiverAddress:
type: string
nullable: true
buyerPaymentAddress:
type: string
nullable: true
GetRuneActivitiesResultSchema:
type: object
properties:
activities:
type: array
items:
$ref: '#/components/schemas/RuneActivitySchema'
GetCollectionStatsRuneResultSchema:
type: object
properties:
runes:
type: array
items:
$ref: '#/components/schemas/RuneStatsSchema'
RuneStatsSchema:
type: object
properties:
rune:
type: string
etching:
$ref: '#/components/schemas/RuneEtchingSchema'
vol:
type: number
nullable: true
totalVol:
type: number
nullable: true
unitPriceSats:
type: number
nullable: true
formattedUnitPriceSats:
type: string
nullable: true
txnCount:
type: number
nullable: true
imageURI:
type: string
nullable: true
unitPriceChange:
type: number
nullable: true
holderCount:
type: number
nullable: true
pendingCount:
type: number
nullable: true
RuneEtchingSchema:
type: object
properties:
details:
type: string
GetRunesMarketInfoResultSchema:
type: object
properties:
rune:
type: string
ticker:
type: string
totalSupply:
type: string
formattedTotalSupply:
type: string
divisibility:
type: integer
imageURI:
type: string
nullable: true
description:
type: string
nullable: true
coinMarketCapLink:
type: string
nullable: true
discordLink:
type: string
nullable: true
telegramLink:
type: string
nullable: true
twitterLink:
type: string
nullable: true
minOrderSize:
type: integer
nullable: true
maxOrderSize:
type: integer
nullable: true
pendingTxnCount:
type: integer
nullable: true
floorUnitPrice:
type: object
properties:
formatted:
type: string
value:
type: string
nullable: true
marketCap:
type: integer
nullable: true
volume:
type: object
properties:
24h:
type: integer
nullable: true
7d:
type: integer
nullable: true
30d:
type: integer
nullable: true
nullable: true
GetRunesOrderInfoResultSchema:
type: object
properties:
orders:
type: array
items:
$ref: '#/components/schemas/ISafeApiRuneOrderSchema'
ISafeApiRuneOrderSchema:
type: object
properties:
amount:
type: number
formattedAmount:
type: string
createdAt:
type: string
format: date-time
expiresAt:
type: string
format: date-time
id:
type: string
rune:
type: string
mempoolTxId:
type: string
nullable: true
maker:
type: string
makerReceiveAddress:
type: string
makerFeeBps:
type: number
price:
type: number
side:
type: string
status:
type: string
unitPrice:
type: number
formattedUnitPrice:
type: string
RuneUtxoSchema:
type: object
properties:
location:
type: string
address:
type: string
nullable: true
rune:
type: string
balance:
type: number
formattedBalance:
type: string
spent:
type: boolean
pure:
type: boolean
containsInscription:
type: boolean
nullable: true
costSats:
type: number
nullable: true
listing:
type: object
nullable: true
properties:
orderId:
type: string
format: uuid
totalPriceSats:
type: number
unitPriceSats:
type: number
formattedUnitPriceSats:
type: string
expiresAt:
type: string
format: date-time
GetRunesUtxoByWalletResultSchema:
type: object
properties:
utxos:
type: array
items:
$ref: '#/components/schemas/RuneUtxoSchema'
GetRuneActivitiesByAddressResultSchema:
type: object
properties:
activities:
type: array
items:
$ref: '#/components/schemas/RuneActivitySchema'
GetBalanceByAddressAndRuneResultSchema:
type: object
properties:
balance:
type: string
description: The raw balance of the Rune, typically in its smallest unit.
formattedBalance:
type: string
description: The formatted balance of the Rune, adjusted for human readability according to divisibility.
ticker:
type: string
description: The symbol of the Rune whose balance is represented.
pattern: ^[A-Z]{1,26}$
PostRunesOrderCancelRequestSchema:
type: object
required:
- signature
- orderIds
- makerAddress
- makerPublicKey
- token
properties:
signature:
type: string
description: A BIP322 signed version of the message requested from /v2/ord/btc/runes/psbt/order/cancel
orderIds:
type: array
items:
type: string
format: uuid
description: Array of UUIDs of the orders to be cancelled; cannot be empty and maximum of 20.
minItems: 1
maxItems: 20
makerAddress:
type: string
oneOf:
- pattern: ^(bc|tb)1q[023456789acdefghjklmnpqrstuvwxyz]{38,58}$
- pattern: ^(bc|tb)1p[023456789acdefghjklmnpqrstuvwxyz]{58}$
- pattern: ^[32][1-9A-HJ-NP-Za-km-z]{33,34}$
description: Maker's Bitcoin address, supporting native segwit, Taproot, or P2SH formats.
makerPublicKey:
type: string
oneOf:
- pattern: ^([0-9a-f]){66}$
- pattern: ^([0-9a-f]){64}$
description: Maker's Bitcoin public key, either a standard or x-only format.
token:
type: string
description: JWT token of cancellation request from /v2/ord/btc/runes/psbt/order/cancel.
additionalProperties: false
PostRunesOrderCancelResultSchema:
type: object
required:
- orderIds
properties:
orderIds:
type: array
items:
type: string
format: uuid
description: Array of UUIDs for successfully cancelled orders.
additionalProperties: false
PostRunesOrderCreateRequestSchema:
type: object
required:
- side
- signedPsbtBase64
- symbol
- makerRunesPublicKey
- makerRunesAddress
- makerReceiveAddress
- expiresAt
properties:
side:
type: string
enum:
- sell
description: Only 'sell' orders are currently supported.
signedPsbtBase64:
type: string
description: Base64-encoded signed PSBT (Partially Signed Bitcoin Transaction).
symbol:
type: string
description: Symbol representing the asset being transacted.
makerRunesPublicKey:
type: string
oneOf:
- pattern: ^([0-9a-f]){66}$
- pattern: ^([0-9a-f]){64}$
description: Maker's Bitcoin public key, either a standard or x-only format.
makerRunesAddress:
type: string
oneOf:
- pattern: ^(bc|tb)1q[023456789acdefghjklmnpqrstuvwxyz]{38,58}$
- pattern: ^(bc|tb)1p[023456789acdefghjklmnpqrstuvwxyz]{58}$
- pattern: ^[32][1-9A-HJ-NP-Za-km-z]{33,34}$
description: Maker's Bitcoin address, supporting native segwit, Taproot, or P2SH formats.
makerReceiveAddress:
type: string
oneOf:
- pattern: ^(bc|tb)1q[023456789acdefghjklmnpqrstuvwxyz]{38,58}$
- pattern: ^(bc|tb)1p[023456789acdefghjklmnpqrstuvwxyz]{58}$
- pattern: ^[32][1-9A-HJ-NP-Za-km-z]{33,34}$
description: Maker's Bitcoin receive address for the transaction, supporting native segwit, Taproot, or P2SH formats.
expiresAt:
type: string
format: date-time
description: Expiration date and time for the order.
signedRBFProtectedPsbts:
type: array
items:
type: string
format: uuid
description: Array of Base64-encoded signed PSBT (Partially Signed Bitcoin Transaction) of the RBF protected sell
order.
additionalProperties: false
PostRunesOrderCreateResultSchema:
type: object
required:
- orderIds
properties:
orderIds:
type: array
items:
type: string
format: uuid
description: Array of UUIDs for successfully created orders.
additionalProperties: false
PostRunesPSBTOrderCancelRequestSchema:
type: object
required:
- orderIds
- makerAddress
- makerPublicKey
properties:
orderIds:
type: array
items:
type: string
format: uuid
description: Array of UUIDs of the orders to be cancelled; cannot be empty and maximum of 20.
minItems: 1
maxItems: 20
makerAddress:
type: string
oneOf:
- pattern: ^(bc|tb)1q[023456789acdefghjklmnpqrstuvwxyz]{38,58}$
- pattern: ^(bc|tb)1p[023456789acdefghjklmnpqrstuvwxyz]{58}$
- pattern: ^[32][1-9A-HJ-NP-Za-km-z]{33,34}$
description: Maker's Bitcoin address, supporting native segwit, Taproot, or P2SH formats.
makerPublicKey:
type: string
oneOf:
- pattern: ^([0-9a-f]){66}$
- pattern: ^([0-9a-f]){64}$
description: Maker's Bitcoin public key, either a standard or x-only format.
additionalProperties: false
PostRunesPSBTOrderCancelResultSchema:
type: object
required:
- orderIds
- psbtBase64
properties:
orderIds:
type: array
items:
type: string
format: uuid
description: Array of UUIDs for successfully cancelled orders.
token:
type: string
description: JWT token of cancellation request.
message:
type: string
description: Unsigned message of cancellation request.
additionalProperties: false
PostRunesPSBTOrderCreateRequestSchema:
type: object
required:
- side
- rune
- makerRunesPublicKey
- makerRunesAddress
- makerReceiveAddress
- utxos
- expiresAt
properties:
side:
type: string
enum:
- sell
description: Currently only 'sell' orders are supported.
rune:
type: string
pattern: ^[A-Z]{1,26}$
description: Rune symbol must contain only uppercase letters and be between 1 and 26 characters long.
makerRunesPublicKey:
type: string
oneOf:
- pattern: ^([0-9a-f]){66}$
- pattern: ^([0-9a-f]){64}$
description: Bitcoin public key, either a standard or x-only format.
makerRunesAddress:
type: string
oneOf:
- pattern: ^(bc|tb)1q[023456789acdefghjklmnpqrstuvwxyz]{38,58}$
- pattern: ^(bc|tb)1p[023456789acdefghjklmnpqrstuvwxyz]{58}$
- pattern: ^[32][1-9A-HJ-NP-Za-km-z]{33,34}$
description: Bitcoin address, supporting native segwit, Taproot, or P2SH formats.
makerReceiveAddress:
type: string
oneOf:
- pattern: ^(bc|tb)1q[023456789acdefghjklmnpqrstuvwxyz]{38,58}$
- pattern: ^(bc|tb)1p[023456789acdefghjklmnpqrstuvwxyz]{58}$
- pattern: ^[32][1-9A-HJ-NP-Za-km-z]{33,34}$
description: Bitcoin receive address for the transaction, supporting native segwit, Taproot, or P2SH formats.
utxos:
type: array
maxItems: 100
items:
type: object
required:
- location
- priceSats
properties:
location:
type: string
description: Location identifier for the UTXO.
priceSats:
type: integer
minimum: 10000
maximum: 3000000000
description: Price in satoshis, within specified limits.
expiresAt:
type: string
format: date-time
description: Expiration date and time of the order.
additionalProperties: false
PostRunesPSBTOrderCreateResultSchema:
type: object
required:
- orderPsbtBase64
- unsignedRBFProtectedPsbts
properties:
orderPsbtBase64:
type: string
description: Base64-encoded unsigned PSBT (Partially Signed Bitcoin Transaction) of the sell order.
unsignedRBFProtectedPsbts:
type: array
items:
$ref: '#/components/schemas/UnsignedRBFProtectedPSBTSchema'
additionalProperties: false
UnsignedRBFProtectedPSBTSchema:
type: object
properties:
unsignedPSBTBase64:
type: string
description: Base64-encoded unsigned PSBT (Partially Signed Bitcoin Transaction) of the RBF protected sell order.
toSignInputs:
type: array
items:
type: number
description: Array of input indices to sign.
toSignSigHash:
type: number
description: Signature hash type for signing.
PostMarketSellPsbtRequestSchema:
type: object
properties:
requestId:
type: string
description: The unique request ID for the market sell.
signedPsbtBase64:
type: string
description: The signed PSBT (Partially Signed Bitcoin Transaction) in base64 format.
required:
- requestId
- signedPsbtBase64
PostMarketSellPsbtResponseSchema:
type: object
properties:
txid:
type: string
description: The transaction ID for the market sell.
required:
- txid
SettlementSchema:
type: object
properties:
amount:
type: string
format: bigint
description: A large integer value, represented the total amount of runes.
price:
type: number
format: float
description: The price value as a floating-point number, represented the total amount of BTC payment.
required:
- amount
- price
GetMarketSellPsbtRequestSchema:
type: object
properties:
orders:
type: array
items:
type: object
properties:
amount:
type: string
format: bigint
description: The amount for the order, represented as a string to accommodate large integers.
id:
type: string
description: The unique identifier for the order.
runeTicker:
type: string
description: The ticker symbol for the rune.
takerPaymentAddress:
type: string
description: The payment address of the taker.
takerRunesAddress:
type: string
description: The runes address of the taker.
takerRunesPublicKey:
type: string
description: The runes public key of the taker.
feeRateTier:
type: string
enum:
- custom
- minimumFee
- halfHourFee
- hourFee
- fastestFee
description: The fee rate tier.
default: hourFee
feeRateNum:
type: number
description: The numerical fee rate.
nullable: true
GetMarketSellPsbtResponseSchema:
type: object
properties:
invalidOrders:
type: array
description: List of order IDs that could not be processed.
items:
type: string
psbtBase64:
type: string
description: Base64-encoded unsigned PSBT (Partially Signed Bitcoin Transaction) of the market sell.
requestId:
type: string
description: The unique request ID for the market sell.
runeUtxoIndexes:
type: array
items:
type: integer
description: Array of rune UTXO indexes.
settlement:
$ref: '#/components/schemas/SettlementSchema'
description: The settlement details.
required:
- invalidOrders
- psbtBase64
- requestId
- runeUtxoIndexes
- settlement
GetQuoteResponseSchema:
type: object
properties:
amount:
type: string
format: bigint
description: The total amount for the quote, represented as a string to accommodate large integers.
averageUnitPrice:
type: number
description: The average unit price.
bestUnitPrice:
type: number
description: The best unit price available.
maxUnitPrice:
type: number
description: The maximum unit price.
minUnitPrice:
type: number
description: The minimum unit price.
price:
type: number
description: The total price.
orders:
type: array
items:
type: object
properties:
amount:
type: string
format: bigint
# --- truncated at 32 KB (76 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/magic-eden/refs/heads/main/openapi/magic-eden-ordinals-openapi.yml