The Magic Eden Solana API is a powerful tool designed to assist developers in creating innovative experiences using NFTs (Non-Fungible Tokens) and accessing marketplace data. This article provides an overview of the Solana API, including its capabilities, usage guidelines, and information on Solana clusters and API keys.

The Magic Eden Solana API offers a comprehensive suite of endpoints that enable developers to access NFT metadata and marketplace data. With these endpoints, developers can perform various actions, such as listing NFTs, purchasing NFTs, placing bids, and more. The API empowers developers to create unique experiences and applications in the web3 space.

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 https://magiceden.io/

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.

Note: 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. Happy building!

A Comprehensive Guide to Buying, Selling, and Collecting SFTs on Magic Eden

Magic Eden API Guide: Harnessing the Power of Our Platform

Mastering the Magic Eden Ordinals API: A Comprehensive User Guide

A Guide to Custom Tokens in Magic Eden Wallet

Leveraging the Magic Eden Polygon API: A Comprehensive Guide