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