Skip to main content
All CollectionsDeveloper ToolsMagic Eden's API
The Magic Eden Solana API
The Magic Eden Solana API

Understanding the Solana API's full potential.

Updated over a month ago

This article provides an overview of the Solana API, including its capabilities, usage guidelines, and information on Solana clusters and API keys.

API endpoints

The Solana API provides endpoints to access essential components of the marketplace, including events, collections, listings, bids, and more. These endpoints allow developers to retrieve data and perform actions similar to those available through the user interface.

Composability and Terms of Service

The Solana API is offered with the intention of fostering composability and openness in the web3 ecosystem. Magic Eden kindly requests that developers adhere to the Terms of Service when utilizing the API and building upon its data.

Attribution and usage guidelines

Magic Eden provides the Solana API free of charge and requests that developers attribute Magic Eden on their websites or within their applications. When leveraging the API, it is appreciated if developers consider linking to the Magic Eden marketplace from the NFTs showcased, where appropriate.

Rate limiting

Please note that the Solana API is rate-limited to ensure fair usage. By default, the API allows 120 queries per minute (QPM) or 2 queries per second (QPS). If you require a higher limit or need access to authorized endpoints, please fill out the form provided to obtain an API key.

To prevent connection refusal when making batch requests, it is recommended to add a small timeout between requests. This applies to both users with and without API keys.

Solana clusters

The Solana API supports different clusters for development and production environments. The following clusters are available:

  • Devnet: api-devnet.magiceden.dev/v2

    • Uses a testing Solana cluster with non-real tokens

  • Mainnet: api-mainnet.magiceden.dev/v2

    • Uses the real Solana cluster with real tokens consistent with data on our website.

For more information about Solana clusters, refer to the Solana documentation: https://docs.solana.com/clusters

API metadata

Certain endpoints in the Solana API can provide additional metadata upon request. To receive this metadata, include the request header "ME-Pub-API-Metadata" with a JSON object as its value. The JSON object should follow the TypeScript interface defined below:

typescriptCopy codeinterface RequestMetadata { paging?: boolean }

If an endpoint supports the "ME-Pub-API-Metadata" header, it will respond with the same named header in the response. The value of the response header will be a JSON object adhering to the following TypeScript interface:

typescriptCopy codeinterface ResponseMetadata { paging?: PagingMetadata } interface PagingMetadata { total: number start: number end: number }

Solana API keys

To access authorized endpoints, including those related to instructions and certain mmm endpoints, an API key must be provided in the Authorization header of the HTTP request. The API key can be obtained by filling out the provided form.

Instruction endpoints

Instruction endpoints generate instructions and are currently guarded by an API key. These endpoints include all of the endpoints in the "instructions" category and some endpoints in "mmm". To access these endpoints, include an Authorization header in your HTTP requests with the following format:

makefileCopy codeAuthorization: Bearer YOUR_API_KEY

Replace "YOUR_API_KEY" with the actual API key provided to you.

Authorization header

When accessing instruction endpoints, it is essential to include the Authorization header in your HTTP requests. The value of the Authorization header should be "Bearer" followed by the API key.

Example:

makefileCopy codeAuthorization: Bearer YOUR_API_KEY

Remember to replace "YOUR_API_KEY" with your actual API key.

Solana API endpoints

Magic Eden provides a range of endpoints in the Solana API that allow developers to access various functionalities and retrieve data related to NFTs and marketplace activities. This article provides an overview of the available endpoints, their purposes, and the required parameters.

Get Activities of a Collection

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/collections/{symbol}/activities

  • Required Path Parameter:

    • symbol: The symbol of the collection (string)

  • Optional Query Parameters:

    • offset: The number of items to skip (integer, default: 0, min: 0)

    • limit: The number of items to return (integer, default: 100, min: 1, max: 1000)

  • Responses:

    • 200: Success response

    • 400: Invalid symbol

Get Stats of a Collection

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/collections/{symbol}/stats

  • Required Path Parameter:

    • symbol: The symbol of the collection (string)

  • Responses:

    • 200: Success response

    • 400: Invalid symbol

    • 404: Collection not found

Get Collections

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/collections

  • Optional Query Parameters:

    • offset: The number of items to skip (integer, default: 0, min: 0)

    • limit: The number of items to return (integer, default: 200, min: 1, max: 500)

  • Optional Headers:

    • ME-Pub-API-Metadata: Object that supports paging metadata

  • Responses:

    • 200: Success response

Get Listings of a Collection

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/collections/{symbol}/listings

  • Required Path Parameter:

    • symbol: The symbol of the collection (string)

  • Optional Query Parameters:

    • offset: The number of items to skip (integer, default: 0, min: 0)

    • limit: The number of items to return (integer, default: 20, min: 1, max: 20)

    • min_price: Filter listings that are less than this price (number)

    • max_price: Filter listings that are more than this price (number)

    • attributes: Represents a filtering mechanism (array of arrays of objects)

    • sort: The field to sort the listings (string, default: 'listPrice')

    • sort_direction: The direction of the returned elements' sorting (string, default: 'asc')

  • Responses:

    • 200: Success response

    • 400: Invalid symbol

Get Holder Stats of a Collection

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/collections/{symbol}/holder_stats

  • Required Path Parameter:

    • symbol: The symbol of the collection (string)

  • Responses:

    • 200: Success response

    • 400: Bad request

Get Launchpad Collections

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/launchpad/collections

  • Optional Query Parameters:

    • offset: The number of items to skip (integer, default: 0, min: 0)

    • limit: The number of items to return (integer, default: 200, min: 1, max: 500)

  • Responses:

    • 200: Success response

Get the Top 50 Popular Collections for a Time Range

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/marketplace/popular_collections

  • Optional Query Parameters:

    • timeRange: The time range to return popular collections for (string, default: '1d')

      • Allowed values: '1h', '1d', '7d', '30d'

  • Responses:

    • 200: Success response

Get AMM Pools Corresponding to an Owner or Collection Symbol

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/mmm/pools

  • Optional Query Parameters:

    • collectionSymbol: The collection symbol to query the pools from (string)

    • owner: The owner public key to query the pools created by (string)

    • offset: The number of items to skip (integer, default: 0, min: 0)

    • limit: The number of items to return (integer, default: 100, min: 1, max: 500)

    • field: Sort pools by field (string or null)

      • Allowed values: '0' (NONE), '1' (ADDRESS), '2' (SPOT_PRICE), '5' (BUYSIDE_ADJUSTED_PRICE)

    • direction: Sort pools by field in specified directions (string or null)

      • Allowed values: '0' (NONE), '1' (DESC), '2' (INC)

  • Responses:

    • 200: Success response

Get Best Offers for an NFT

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/mmm/token/{mint_address}/pools

  • Required Path Parameter:

    • mint_address: Mint address of the NFT (string)

  • Optional Query Parameters:

    • limit: Total best offers to return (integer, default: 1, max: 5)

  • Responses:

    • 200: Success response

Get Instruction to Create a Pool

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/instructions/mmm/create-pool

  • Optional Query Parameters:

    • spotPrice: Pool initial spot price in SOL (number)

    • curveType: Type curve, either 'linear' or 'exp' (string)

    • curveDelta: Curve delta used to change price after a fill (number)

    • reinvestBuy: Whether to reinvest bought asset or transfer directly to owner (boolean)

    • reinvestSell: Whether to reinvest payment from sale or transfer directly to owner (boolean)

    • expiry: Timestamp in seconds in the future, 0 means no expiry (number)

    • lpFeeBp: Requested liquidity provider fee in basis points (number)

    • buysideCreatorRoyaltyBp: Amount of creator royalty the pool should pay in basis points (number)

    • paymentMint: Mint address of payment (default for SOL) (string)

    • collectionSymbol: Collection symbol for which the pool will be valid (string)

    • owner: Owner of the pool (string)

    • solDeposit: Optional SOL amount to deposit with pool creation (number)

  • Responses:

    • 200: Successful operation

Get Instruction to Withdraw SOL Payment from a Pool

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/instructions/mmm/sol-withdraw-buy

  • Optional Query Parameters:

    • pool: Public key of pool to withdraw from (string)

    • paymentAmount: The amount of SOL to withdraw (number)

  • Responses:

    • 200: Successful operation

Get Instruction to Have a Pool Fulfill a Buy

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/instructions/mmm/sol-fulfill-buy

  • Optional Query Parameters:

    • pool: Public key of pool to interact with (string)

    • assetAmount: Amount of asset to transact (number)

    • minPaymentAmount: Minimum payment amount acceptable by the seller, in SOL (number)

    • seller: Public key of the seller of the asset (string)

    • assetMint: Public key of the mint account of the asset (string)

    • assetTokenAccount: Public key of the token account of the asset (string)

    • allowlistAuxAccount: The allowlist aux account used for token authentication (string)

  • Responses:

    • 200: Successful operation

Get Instruction to Have a Pool Fulfill a Sell

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/instructions/mmm/sol-fulfill-sell

  • Optional Query Parameters:

    • pool: Public key of pool to interact with (string)

    • assetAmount: Amount of asset to transact (number)

    • maxPaymentAmount: Maximum payment amount to be paid by the buyer, in SOL (number)

    • buysideCreatorRoyaltyBp: Amount of royalty to be paid, in basis points of total royalty (number)

    • buyer: Public key of the buyer of the asset (string)

    • assetMint: Public key of the mint account of the asset (string)

    • allowlistAuxAccount: The allowlist aux account used for token authentication (string)

  • Responses:

    • 200: Successful operation

Get Listings for a Token

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/tokens/{token_mint}/listings

  • Required Path Parameter:

    • token_mint: Mint address of the token (string)

  • Responses:

    • 200: Success response

    • 400: Token not found

Get Received Offers for a Token

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/tokens/{token_mint}/offers_received

  • Required Path Parameter:

    • token_mint: Mint address of the token (string)

  • Optional Query Parameters:

    • min_price: Filter offers that are less than this price (number)

    • max_price: Filter offers that are more than this price (number)

    • offset: The number of items to skip (integer, default: 0, min: 0)

    • limit: The number of items to return (integer, default: 100, min: 1, max: 500)

    • sort: The field to sort the offers received (string, default: 'updatedAt')

    • sort_direction: The direction of the returned elements' sorting (string, default: 'desc')

  • Responses:

    • 200: Success response

    • 400: Token not found

Get Activities for a Token

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/tokens/{token_mint}/activities

  • Required Path Parameter:

    • token_mint: Mint address of the token (string)

  • Optional Query Parameters:

    • offset: The number of items to skip (integer, default: 0, min: 0)

    • limit: The number of items to return (integer, default: 100, min: 1, max: 500)

  • Responses:

    • 200: Success response

    • 400: Token not found

Get Token Metadata by Mint Address

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/tokens/{token_mint}

  • Required Path Parameter:

    • token_mint: Mint address of the token (string)

  • Responses:

    • 200: Success response

    • 400: Token not found

Get Tokens Owned by a Wallet

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/wallets/{wallet_address}/tokens

  • Required Path Parameter:

    • wallet_address: Wallet address (string)

  • Optional Query Parameters:

    • offset: The number of items to skip (integer, default: 0, min: 0)

    • limit: The number of items to return (integer, default: 100, min: 1, max: 500)

    • min_price: Filter listings that are less than this price (number)

    • max_price: Filter listings that are more than this price (number)

    • attributes: Represents a filtering mechanism (array of arrays of objects)

    • listStatus: Determines what type of tokens to return (string, default: 'both')

      • Allowed values: 'listed', 'unlisted', 'both'

    • sort: The field to sort the tokens (string, default: 'updatedAt')

      • Allowed values: 'updatedAt', 'listPrice'

    • sort_direction: The direction of the returned elements' sorting (string, default: 'desc')

      • Allowed values: 'desc', 'asc'

  • Responses:

    • 200: Success response

    • 400: Wallet not found

Get Info about the Wallet Owner

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/wallets/{wallet_address}

  • Required Path Parameter:

    • wallet_address: Wallet address (string)

  • Responses:

    • 200: Success response

    • 400: Wallet not found

Get Activities of a Wallet

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/wallets/{wallet_address}/activities

  • Required Path Parameter:

    • wallet_address: Wallet address (string)

  • Optional Query Parameters:

    • offset: The number of items to skip (integer, default: 0, min: 0)

    • limit: The number of items to return (integer, default: 100, min: 1, max: 500)

  • Responses:

    • 200: Success response

    • 400: Wallet not found

Get Offers Made by a Wallet

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/wallets/{wallet_address}/offers_made

  • Required Path Parameter:

    • wallet_address: Wallet address (string)

  • Optional Query Parameters:

    • min_price: Filter offers that are less than this price (number)

    • max_price: Filter offers that are more than this price (number)

    • offset: The number of items to skip (integer, default: 0, min: 0)

    • limit: The number of items to return (integer, default: 100, max: 500)

    • sort: The field to sort the offers made (string, default: 'bidAmount')

    • sort_direction: The direction of the returned elements' sorting (string, default: 'desc')

  • Responses:

    • 200: Success response

    • 400: Wallet not found

Get Offers Received by a Wallet

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/wallets/{wallet_address}/offers_received

  • Required Path Parameter:

    • wallet_address: Wallet address (string)

  • Optional Query Parameters:

    • min_price: Filter offers that are less than this price (number)

    • max_price: Filter offers that are more than this price (number)

    • sort: The field to sort the offers received (string, default: 'updatedAt')

    • sort_direction: The direction of the returned elements' sorting (string, default: 'desc')

    • offset: The number of items to skip (integer, default: 0, min: 0)

    • limit: The number of items to return (integer, default: 100, min: 1, max: 500)

  • Responses:

    • 200: Success response

    • 400: Wallet not found

Get Escrow Balance for a Wallet

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/wallets/{wallet_address}/escrow_balance

  • Required Path Parameter:

    • wallet_address: Wallet address (string)

  • Responses:

    • 200: Success response

    • 400: Wallet not found

Get Instruction to Buy (Bid)

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/instructions/buy

  • Optional Query Parameters:

    • buyer: Buyer wallet (string)

    • auctionHouseAddress: Auction house (string)

    • tokenMint: Token mint address (string)

    • price: Price in SOL (number)

    • buyerReferral: Buyer referral wallet (string)

    • expiry: Timestamp in seconds in the future, 0 means no expiry (number)

  • Responses:

    • 200: Successful operation

Get Instruction to Buy Now and Transfer NFT to Another Owner

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/instructions/buy_now_transfer_nft

  • Optional Query Parameters:

    • buyer: Buyer wallet (string)

    • seller: Seller wallet (string)

    • auctionHouseAddress: Auction house (string)

    • tokenMint: Token mint address (string)

    • tokenATA: Associate Token Account (string)

    • price: Price in SOL (number)

    • destinationATA: Associated token account to send the bought NFT to (string)

    • destinationOwner: Owner of the token account (string)

    • createATA: Whether to include create ATA instructions (boolean)

    • buyerReferral: Buyer referral wallet (string)

    • sellerReferral: Seller referral wallet (string)

    • buyerExpiry: Timestamp in seconds in the future, 0 means no expiry (number)

    • sellerExpiry: Timestamp in seconds in the future, 0 means no expiry (number)

    • buyerCreatorRoyaltyPercent: Buyer creator royalty percent, an integer between 0 and 100 (number)

  • Responses:

    • 200: Successful operation

Get Instruction to Buy Now

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/instructions/buy_now

  • Optional Query Parameters:

    • buyer: Buyer wallet (string)

    • seller: Seller wallet (string)

    • auctionHouseAddress: Auction house (string)

    • tokenMint: Token mint address (string)

    • tokenATA: Associate Token Account (string)

    • price: Price in SOL (number)

    • buyerReferral: Buyer referral wallet (string)

    • sellerReferral: Seller referral wallet (string)

    • buyerExpiry: Timestamp in seconds in the future, 0 means no expiry (number)

    • sellerExpiry: Timestamp in seconds in the future, 0 means no expiry (number)

    • buyerCreatorRoyaltyPercent: Buyer creator royalty percent, an integer between 0 and 100 (number)

  • Responses:

    • 200: Successful operation

Get Instruction to Cancel a Buy

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/instructions/buy_cancel

  • Query Parameters:

    • buyer: Buyer wallet (string, required)

    • auctionHouseAddress: Auction house (string, required)

    • tokenMint: Token mint address (string, required)

    • price: Price in SOL (number, required)

    • buyerReferral: Buyer referral wallet (string)

    • expiry: Timestamp in seconds in the future, 0 means no expiry (number)

  • Response:

    • 200: Successful operation

Get Instruction to Change a Buy Price

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/instructions/buy_change_price

  • Query Parameters:

    • buyer: Buyer wallet (string, required)

    • auctionHouseAddress: Auction house (string, required)

    • tokenMint: Token mint address (string, required)

    • price: Old price in SOL (number, required)

    • newPrice: New price in SOL (number, required)

    • buyerReferral: Buyer referral wallet (string)

    • expiry: Timestamp in seconds in the future, 0 means no expiry (number)

  • Response:

    • 200: Successful operation

Get Instruction to Sell (List)

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/instructions/sell

  • Query Parameters:

    • seller: Seller wallet (string, required)

    • auctionHouseAddress: Auction house (string, required)

    • tokenMint: Token mint address (string, required)

    • tokenAccount: Token account (string, required)

    • price: Price in SOL (number, required)

    • sellerReferral: Seller referral wallet (string)

    • expiry: Timestamp in seconds in the future, 0 means no expiry (number)

  • Response:

    • 200: Successful operation

Get Instruction to Change a Sell Price

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/instructions/sell_change_price

  • Query Parameters:

    • seller: Seller wallet (string, required)

    • auctionHouseAddress: Auction house (string, required)

    • tokenMint: Token mint address (string, required)

    • tokenAccount: Token account (string, required)

    • price: Price in SOL (number, required)

    • newPrice: New price in SOL (number, required)

    • sellerReferral: Seller referral wallet (string)

    • expiry: Timestamp in seconds in the future, 0 means no expiry (number)

  • Response:

    • 200: Successful operation

Get Instruction to Sell Now (Accept Offer)

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/instructions/sell_now

  • Query Parameters:

    • buyer: Buyer wallet (string, required)

    • seller: Seller wallet (string, required)

    • auctionHouseAddress: Auction house (string, required)

    • tokenMint: Token mint address (string, required)

    • tokenATA: Associate token account (string, required)

    • price: Price in SOL (number, required)

    • newPrice: New price in SOL (number, required)

    • sellerExpiry: Timestamp in seconds in the future, 0 means no expiry (number, required)

    • buyerReferral: Buyer referral wallet (string)

    • sellerReferral: Seller referral wallet (string)

    • buyerExpiry: Timestamp in seconds in the future, 0 means no expiry (number)

  • Response:

    • 200: Successful operation

Get Instruction to Cancel a Sell

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/instructions/sell_cancel

  • Query Parameters:

    • seller: Seller wallet (string, required)

    • auctionHouseAddress: Auction house (string, required)

    • tokenMint: Token mint address (string, required)

    • tokenAccount: Token account (string, required)

    • price: Price in SOL (number, required)

    • sellerReferral: Seller referral wallet (string)

    • expiry: Timestamp in seconds in the future, 0 means no expiry (number)

  • Response:

    • 200: Successful operation

Get Instruction to Deposit to Escrow

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/instructions/deposit

  • Query Parameters:

    • buyer: Buyer wallet (string, required)

    • auctionHouseAddress: Auction house (string, required)

    • amount: Amount in SOL (number, required)

  • Response:

    • 200: Successful operation

Get Instruction to Withdraw from Escrow

  • Endpoint: GET https://api-mainnet.magiceden.dev/v2/instructions/withdraw

  • Query Parameters:

    • buyer: Buyer wallet (string, required)

    • auctionHouseAddress: Auction house (string, required)

    • amount: Amount in SOL (number, required)

  • Response:

    • 200: Successful operation

Please note that these API endpoints are specific to Magic Eden and may be subject to change. It's always a good practice to refer to the official documentation or contact Magic Eden support for the most up-to-date information.

This Help Centre article provides an overview of the Solana API. For detailed information about specific endpoints and their functionalities, please refer to the Solana API documentation.

For further assistance or inquiries, feel free to join us on Discord or reach out to our support team.

Related Articles
A Comprehensive Guide to Buying, Selling, and Collecting SFTs on Magic Eden
The Magic Eden Ordinals API
Solana Naming Service (SNS) Integration with Magic Eden
The Magic Eden Polygon API
Unlocking the Future: Inscriptions on Solana
Did this answer your question?