aibtcdev/ordinals-marketplace

Ordinals Marketplace Skill

Browse and trade Bitcoin ordinals/inscriptions on the Magic Eden marketplace via the Magic Eden BTC ordinals API (api-mainnet.magiceden.dev/v2/ord/btc).

Important: This skill covers BTC ordinals only. Magic Eden operates separate marketplaces for different chains; this skill exclusively uses the Bitcoin ordinals API. All operations are mainnet-only — the API does not support testnet.

This is an MCP-tool skill. Agents invoke the underlying MCP tools directly rather than a standalone CLI script. Write operations use the Magic Eden PSBT-based listing flow: Magic Eden generates a PSBT which the seller or buyer signs and then broadcasts.

Prerequisites

• Wallet must be unlocked for all write operations (list-for-sale, buy, cancel-listing)
• get-listings is public and requires no wallet
• Active wallet must have Taproot keys (P2TR address) — managed wallets satisfy this
• BTC balance required for purchasing and cancellations (miner fee for cancel; purchase price + fee for buy)
• Set MAGIC_EDEN_API_KEY environment variable for a dedicated authenticated rate limit (optional but recommended for high-volume use; without it, the unauthenticated shared limit applies: 30 QPM)

Subcommands

get-listings

Browse active BTC ordinals listings on Magic Eden. No wallet required.

MCP tool: ordinals_get_listings

Options:

• collection (optional) — Magic Eden collection symbol to filter by (e.g. nodemonkes, bitcoin-puppets)
• minPriceSats (optional) — Minimum listing price in satoshis
• maxPriceSats (optional) — Maximum listing price in satoshis
• limit (optional) — Number of results (default 20, max 100)
• offset (optional) — Pagination offset (default 0)
• sortBy (optional) — priceAsc, priceDesc, or recentlyListed (default)

Returns active listings with inscription details, seller address, and price in satoshis.

list-for-sale

List a wallet inscription for sale on Magic Eden using the PSBT listing flow. Step 1 of 2.

MCP tool: ordinals_list_for_sale

Options:

• inscriptionId (required) — Inscription ID in txid+index format, e.g. abc123...i0
• priceSats (required) — Listing price in satoshis
• receiverAddress (optional) — BTC address to receive payment (defaults to wallet's Taproot address)

Returns a psbtBase64 for signing. The inscription is not moved; the signed PSBT authorizes the sale to any buyer.

Next step: sign the returned PSBT using psbt_sign, then call list-for-sale-submit.

list-for-sale-submit

Submit a signed listing PSBT to Magic Eden to publish the listing. Step 2 of 2.

MCP tool: ordinals_list_for_sale_submit

Options:

• inscriptionId (required) — The inscription ID being listed
• signedPsbt (required) — The signed PSBT in base64 format (from psbt_sign)

Returns { "status": "listed" } on success.

buy

Buy a listed BTC ordinal inscription from Magic Eden. Multi-step PSBT flow.

MCP tool: ordinals_buy

Options:

• inscriptionId (required) — Inscription ID to purchase, e.g. abc123...i0
• buyerAddress (optional) — BTC address to receive the inscription (defaults to wallet's Taproot address)
• buyerPaymentAddress (optional) — BTC address to fund the purchase (defaults to wallet's SegWit address)
• feeRate (optional) — Fee rate in sat/vB (uses halfHourFee network default if omitted)

Returns a psbtBase64 combining the seller's listing and buyer's payment inputs.

Next step: sign the PSBT with psbt_sign, then broadcast with psbt_broadcast.

cancel-listing

Cancel an active Magic Eden listing for an inscription you own.

MCP tool: ordinals_cancel_listing

Options:

• inscriptionId (required) — Inscription ID of the active listing to cancel, e.g. abc123...i0
• sellerAddress (optional) — BTC Taproot address that owns the listing (defaults to wallet's Taproot address)

Returns a psbtBase64 for the cancellation transaction.

Next step: sign the PSBT with psbt_sign, then broadcast with psbt_broadcast to finalize the cancellation.

Multi-Step Flows

Listing Flow

1. ordinals_list_for_sale    (get listing PSBT)
2. psbt_sign                 (sign the psbtBase64)
3. ordinals_list_for_sale_submit  (publish listing)

Buy Flow

1. ordinals_get_listings     (find inscription and price)
2. ordinals_buy              (get buyer PSBT)
3. psbt_sign                 (sign the psbtBase64)
4. psbt_broadcast            (broadcast to complete purchase)

Cancel Flow

1. ordinals_cancel_listing   (get cancellation PSBT)
2. psbt_sign                 (sign the psbtBase64)
3. psbt_broadcast            (broadcast to cancel listing)

Notes

• All write operations require mainnet — the API returns an error on testnet
• Magic Eden's BTC ordinals API (api-mainnet.magiceden.dev/v2/ord/btc) is the backend for all operations
• The inscription must be in the wallet's Taproot (P2TR / bc1p...) address for listing and cancellation
• Payment for purchases comes from the SegWit (P2WPKH / bc1q...) address
• If MAGIC_EDEN_API_KEY is not set, the shared unauthenticated rate limit (30 QPM) applies