openapi: 3.0.1
info:
  title: NFTTOOLS API DOCS FOR MAGIC EDEN Bitcoin Solana API
  version: 1.0.0
  description: A comprehensive API for interacting with Magic Eden, providing tools to handle collections, tokens, activity, bid, list, and buy on Solana, Bitcoin, Ethereum, Base, and Polygon chains.
servers:
- url: https://nfttools.pro/magiceden
  description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Solana
  description: Endpoints related to Solana blockchain
paths:
  /collection_stats/search/solana:
    servers:
    - url: https://nfttools.pro/magiceden_stats
    get:
      summary: Search Solana Collection Stats
      description: Retrieve collection statistics for Solana NFTs on Magic Eden, with options for sorting, filtering, and pagination.
      tags:
      - Solana
      parameters:
      - name: direction
        in: query
        required: true
        schema:
          type: string
          enum:
          - asc
          - desc
        description: The direction to sort the results
        example: desc
      - name: sort
        in: query
        required: true
        schema:
          type: string
          enum:
          - volume
          - floorPrice
          - listedCount
        description: The field to sort the results by
        example: volume
      - name: window
        in: query
        required: true
        schema:
          type: string
          enum:
          - 1d
          - 7d
          - 30d
        description: The time window for the stats
        example: 1d
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
        description: The maximum number of results to return
        example: 100
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
        description: The number of results to skip (for pagination)
        example: 0
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  collections:
                    type: array
                    items:
                      type: object
                      properties:
                        symbol:
                          type: string
                        name:
                          type: string
                        volume:
                          type: number
                        floorPrice:
                          type: number
                        listedCount:
                          type: integer
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '500':
          description: Internal server error
  /rpc/getCollectionHolderStats/{collectionSymbol}:
    get:
      summary: Get Collection Holder Statistics
      description: Retrieve holder statistics for a specific NFT collection on Magic Eden.
      tags:
      - Solana
      parameters:
      - name: collectionSymbol
        in: path
        required: true
        schema:
          type: string
        description: The symbol or identifier of the collection
        example: rugens_drip
      - name: edge_cache
        in: query
        required: false
        schema:
          type: boolean
        description: Whether to use edge caching for the request
        example: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalHolders:
                    type: integer
                    description: Total number of unique holders in the collection
                  uniqueHolders:
                    type: number
                    description: Percentage of unique holders (possibly out of total supply)
                  averageHoldingPerWallet:
                    type: number
                    description: Average number of NFTs held per wallet
                  holdersDistribution:
                    type: object
                    description: Distribution of holders by number of NFTs held
                    properties:
                      '1':
                        type: integer
                        description: Number of wallets holding 1 NFT
                      2-5:
                        type: integer
                        description: Number of wallets holding 2 to 5 NFTs
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Collection not found
        '500':
          description: Internal server error
  /idxv2/getAllNftsByCollectionSymbol:
    get:
      summary: Retrieve all NFTs by collection symbol
      tags:
      - Solana
      parameters:
      - name: collectionSymbol
        in: query
        required: true
        schema:
          type: string
        example: rugens_drip
      - name: direction
        in: query
        required: true
        schema:
          type: integer
          enum:
          - 1
          - -1
          default: 1
        example: 1
      - name: field
        in: query
        required: true
        schema:
          type: integer
          default: 1
        example: 1
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 1
        example: 1
      - name: token22StandardFilter
        in: query
        required: true
        schema:
          type: integer
          default: 1
        example: 1
      - name: mplCoreStandardFilter
        in: query
        required: true
        schema:
          type: integer
          default: 1
        example: 1
      - name: agg
        in: query
        required: true
        schema:
          type: integer
          default: 3
        example: 3
      - name: compressionMode
        in: query
        required: true
        schema:
          type: string
          enum:
          - both
          - compressed
          - uncompressed
          default: both
        example: both
      responses:
        '200':
          description: Successful response
        '400':
          description: Invalid request
        '404':
          description: NFTs not found
        '500':
          description: Internal server error
  /rpc/getNFTsByOwner/{ownerAddress}:
    get:
      summary: Retrieve NFTs by owner
      tags:
      - Solana
      parameters:
      - name: ownerAddress
        in: path
        required: true
        schema:
          type: string
        example: EfdC1uyq5gWqHQYxSENscwNZKY8k2z8CXkpmPRB7mn2N
      responses:
        '200':
          description: Successful response
        '400':
          description: Invalid request
        '404':
          description: NFTs not found
        '500':
          description: Internal server error
  /rpc/getCollectionAttributesStats/{collectionSymbol}:
    get:
      summary: Retrieve collection attributes stats
      tags:
      - Solana
      parameters:
      - name: collectionSymbol
        in: path
        required: true
        schema:
          type: string
        example: drip_tarimosi
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - all
          - active
          - inactive
          default: all
        example: all
      - name: edge_cache
        in: query
        required: true
        schema:
          type: boolean
          default: true
        example: true
      - name: agg
        in: query
        required: true
        schema:
          type: integer
          default: 3
        example: 3
      responses:
        '200':
          description: Successful response
        '400':
          description: Invalid request
        '404':
          description: Collection not found
        '500':
          description: Internal server error
  /collections/{collectionSymbol}/organization:
    get:
      summary: Retrieve collection organization details
      tags:
      - Solana
      parameters:
      - name: collectionSymbol
        in: path
        required: true
        schema:
          type: string
        example: drip_tarimosi
      - name: edge_cache
        in: query
        required: true
        schema:
          type: boolean
          default: true
        example: true
      responses:
        '200':
          description: Successful response
        '400':
          description: Invalid request
        '404':
          description: Collection not found
        '500':
          description: Internal server error
  /sft/collection/{collectionSymbol}:
    get:
      summary: Retrieve collection details with pagination
      tags:
      - Solana
      parameters:
      - name: collectionSymbol
        in: path
        required: true
        schema:
          type: string
        example: drip_tarimosi
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
        example: 0
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
        example: 20
      responses:
        '200':
          description: Successful response
        '400':
          description: Invalid request
        '404':
          description: Collection not found
        '500':
          description: Internal server error
  /rpc/getCollectionEscrowStats/{collectionSymbol}:
    get:
      summary: Retrieve collection escrow stats
      tags:
      - Solana
      parameters:
      - name: collectionSymbol
        in: path
        required: true
        schema:
          type: string
        example: drip_tarimosi
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - all
          - active
          - inactive
          default: all
        example: all
      - name: edge_cache
        in: query
        required: true
        schema:
          type: boolean
          default: true
        example: true
      - name: agg
        in: query
        required: true
        schema:
          type: integer
          default: 3
        example: 3
      - name: enableFloorWithFee
        in: query
        required: true
        schema:
          type: boolean
          default: true
        example: true
      responses:
        '200':
          description: Successful response
        '400':
          description: Invalid request
        '404':
          description: Collection not found
        '500':
          description: Internal server error
  /v2/activities:
    get:
      summary: Get Collection Activities
      description: Retrieve activities for a specific NFT collection on Magic Eden, with options for filtering by activity type and pagination.
      tags:
      - Solana
      parameters:
      - name: activityTypes
        in: query
        required: true
        schema:
          type: string
        description: JSON array of activity types to filter by, URL encoded
        example: '%5B%22sale%22%2C%22item_offer%22%2C%22pool_offer%22%2C%22attributes_offer%22%2C%22list%22%2C%22edit_list%22%2C%22delist%22%5D'
      - name: collectionSymbol
        in: query
        required: true
        schema:
          type: string
        description: The symbol or identifier of the collection
        example: drip_tarimosi
      - name: onChainCollectionAddress
        in: query
        required: true
        schema:
          type: string
        description: The on-chain address of the collection
        example: TAuAUS8neSS3KPSqLXQ7u1aWkKgnVPzqNizihDYuXvN
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 50
        description: The maximum number of results to return
        example: 50
      - name: enableSNS
        in: query
        required: true
        schema:
          type: boolean
        description: Whether to enable SNS (possibly Solana Name Service) resolution
        example: true
      responses:
        '200':
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Collection not found
        '500':
          description: Internal server error
  /idxv2/getListedNftsByCollectionSymbol:
    get:
      summary: Retrieve listed NFTs by collection symbol
      tags:
      - Solana
      parameters:
      - name: collectionSymbol
        in: query
        required: true
        schema:
          type: string
        example: drip_tarimosi
      - name: direction
        in: query
        required: false
        schema:
          type: integer
          enum:
          - 1
          - 2
          default: 2
        example: 2
      - name: field
        in: query
        required: false
        schema:
          type: integer
          default: 1
        example: 1
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 100
        example: 100
      - name: token22StandardFilter
        in: query
        required: false
        schema:
          type: integer
          default: 1
        example: 1
      - name: mplCoreStandardFilter
        in: query
        required: false
        schema:
          type: integer
          default: 1
        example: 1
      - name: mode
        in: query
        required: false
        schema:
          type: string
          enum:
          - all
          - listed
          default: all
        example: all
      - name: agg
        in: query
        required: false
        schema:
          type: integer
          default: 3
        example: 3
      - name: compressionMode
        in: query
        required: false
        schema:
          type: string
          enum:
          - none
          - both
          - compressed
          - uncompressed
          default: both
        example: both
      responses:
        '200':
          description: Successful response
        '400':
          description: Invalid request
        '404':
          description: NFTs not found
        '500':
          description: Internal server error
  /collection_watchlists/action/checkUserWatchCollection/{collectionSymbol}:
    get:
      summary: Check if user is watching a collection
      tags:
      - Solana
      parameters:
      - name: collectionSymbol
        in: path
        required: true
        schema:
          type: string
        example: drip_tarimosi
      - name: walletAddress
        in: query
        required: true
        schema:
          type: string
        example: EfdC1uyq5gWqHQYxSENscwNZKY8k2z8CXkpmPRB7mn2N
      responses:
        '200':
          description: Successful response
        '400':
          description: Invalid request
        '404':
          description: Collection or user not found
        '500':
          description: Internal server error
  /collections/{collectionSymbol}:
    get:
      summary: Retrieve collection details
      tags:
      - Solana
      parameters:
      - name: collectionSymbol
        in: path
        required: true
        schema:
          type: string
        example: drip_tarimosi
      - name: edge_cache
        in: query
        required: false
        schema:
          type: boolean
          default: true
        example: true
      responses:
        '200':
          description: Successful response
        '400':
          description: Invalid request
        '404':
          description: Collection not found
        '500':
          description: Internal server error
  /idxv2/getBidsByMintAddresses:
    get:
      summary: Retrieve bids by mint addresses
      tags:
      - Solana
      parameters:
      - name: hideExpired
        in: query
        required: false
        schema:
          type: boolean
          default: true
        example: true
      - name: mintAddresses
        in: query
        required: true
        schema:
          type: string
        example: DmdF3ACqvjmRh4mayaw3SAKuttVQ3tZkmut1N4RxSLCG
      - name: direction
        in: query
        required: false
        schema:
          type: integer
          enum:
          - 1
          - 2
          default: 1
        example: 1
      - name: field
        in: query
        required: false
        schema:
          type: integer
          default: 2
        example: 2
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 500
        example: 500
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
        example: 0
      responses:
        '200':
          description: Successful response
        '400':
          description: Invalid request
        '404':
          description: Bids not found
        '500':
          description: Internal server error
  /rpc/getNFTByMintAddress/{mintAddress}:
    get:
      summary: Retrieve NFT by mint address
      tags:
      - Solana
      parameters:
      - name: mintAddress
        in: path
        required: true
        schema:
          type: string
        example: DmdF3ACqvjmRh4mayaw3SAKuttVQ3tZkmut1N4RxSLCG
      - name: agg
        in: query
        required: false
        schema:
          type: integer
          default: 3
        example: 3
      - name: useRarity
        in: query
        required: false
        schema:
          type: boolean
          default: true
        example: true
      - name: includeBurntMint
        in: query
        required: false
        schema:
          type: boolean
          default: true
        example: true
      - name: compressionMode
        in: query
        required: false
        schema:
          type: string
          enum:
          - none
          - both
          - compressed
          - uncompressed
          default: both
        example: both
      responses:
        '200':
          description: Successful response
        '400':
          description: Invalid request
        '404':
          description: NFT not found
        '500':
          description: Internal server error
  /rpc/getNFTStatsByMintAddress/{mintAddress}:
    get:
      summary: Retrieve NFT stats by mint address
      tags:
      - Solana
      parameters:
      - name: mintAddress
        in: path
        required: true
        schema:
          type: string
        example: DmdF3ACqvjmRh4mayaw3SAKuttVQ3tZkmut1N4RxSLCG
      responses:
        '200':
          description: Successful response
        '400':
          description: Invalid request
        '404':
          description: NFT stats not found
        '500':
          description: Internal server error
  /v2/collections/{symbol}/activities:
    get:
      summary: Retrieve activities for a collection
      tags:
      - Solana
      parameters:
      - name: symbol
        in: path
        required: true
        schema:
          type: string
        example: drip_tarimosi
      responses:
        '200':
          description: Successful response
        '400':
          description: Invalid request
        '404':
          description: Activities not found
        '500':
          description: Internal server error
  /v2/tokens/{token_mint}/listings:
    get:
      summary: Retrieve listings for a token
      tags:
      - Solana
      parameters:
      - name: token_mint
        in: path
        required: true
        schema:
          type: string
        example: DmdF3ACqvjmRh4mayaw3SAKuttVQ3tZkmut1N4RxSLCG
      responses:
        '200':
          description: Successful response
        '400':
          description: Invalid request
        '404':
          description: Listings not found
        '500':
          description: Internal server error
  /v2/tokens/{token_mint}/offers_received:
    get:
      summary: Retrieve offers received for a token
      tags:
      - Solana
      parameters:
      - name: token_mint
        in: path
        required: true
        schema:
          type: string
        example: DmdF3ACqvjmRh4mayaw3SAKuttVQ3tZkmut1N4RxSLCG
      - name: min_price
        in: query
        required: false
        schema:
          type: integer
        example: 1000000
      - name: max_price
        in: query
        required: false
        schema:
          type: integer
        example: 100000000
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
        example: 0
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
        example: 50
      - name: sort
        in: query
        required: false
        schema:
          type: string
          enum:
          - updatedAt
          - bidAmount
        example: updatedAt
      - name: sort_direction
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
        example: desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  offers:
                    type: array
                    items:
                      type: object
                      properties:
                        price:
                          type: string
                          example: '1000000000'
                        buyer:
                          type: string
                          example: EfdC1uyq5gWqHQYxSENscwNZKY8k2z8CXkpmPRB7mn2N
                        mintAddress:
                          type: string
                          example: DmdF3ACqvjmRh4mayaw3SAKuttVQ3tZkmut1N4RxSLCG
                        timestamp:
                          type: string
                          example: 2023-07-04 12:34:56+00:00
        '400':
          description: Invalid request
        '404':
          description: Offers not found
        '500':
          description: Internal server error
  /v2/tokens/{token_mint}/activities:
    get:
      summary: Retrieve activities for a token
      tags:
      - Solana
      parameters:
      - name: token_mint
        in: path
        required: true
        schema:
          type: string
        example: DmdF3ACqvjmRh4mayaw3SAKuttVQ3tZkmut1N4RxSLCG
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
        example: 0
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
        example: 50
      responses:
        '200':
          description: Successful response
        '400':
          description: Invalid request
        '404':
          description: Activities not found
        '500':
          description: Internal server error
  /v2/tokens/{token_mint}:
    get:
      summary: Retrieve token details by mint address
      tags:
      - Solana
      parameters:
      - name: token_mint
        in: path
        required: true
        schema:
          type: string
        example: DmdF3ACqvjmRh4mayaw3SAKuttVQ3tZkmut1N4RxSLCG
      responses:
        '200':
          description: Successful response
        '400':
          description: Invalid request
        '404':
          description: Token not found
        '500':
          description: Internal server error
  /v2/collections/batch/listings:
    post:
      summary: Batch retrieve listings for collections
      tags:
      - Solana
      parameters:
      - name: attributes
        in: query
        schema:
          type: string
        description: 'Array of arrays of objects representing a filtering mechanism.

          Elements within each inner array are logically ORed, and resulting arrays are ANDed together.

          Each inner array consists of objects with properties traitType (string) and value (string).

          Example: [[{"traitType":"trait1", "value":"value1"},{"traitType":"trait1", "value":"value2"}]]

          '
      - name: offset
        required: false
        in: query
        schema:
          type: integer
          example: 0
        description: Offset for pagination
      - name: limit
        required: false
        in: query
        schema:
          type: integer
          example: 50
        description: Number of results per page
      - name: min_price
        in: query
        schema:
          type: integer
          example: 1000000
        description: Minimum price filter
      - name: max_price
        in: query
        schema:
          type: integer
          example: 100000000
        description: Maximum price filter
      - name: sort
        in: query
        schema:
          type: string
          enum:
          - listPrice
          - updatedAt
        example: listPrice
        description: Field to sort the listings
      - name: sort_direction
        in: query
        schema:
          type: string
          enum:
          - asc
          - desc
        example: asc
        description: Sort direction for the returned elements
      - name: listingAggMode
        in: query
        schema:
          type: boolean
        example: true
        description: True to return aggregated marketplace listings, false for Magic Eden listings only
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                collections:
                  type: array
                  items:
                    type: object
                    properties:
                      symbol:
                        type: string
                        example: drip_tarimosi
                mcc:
                  type: string
      responses:
        '200':
          description: Successful response
        '400':
          description: Invalid request
        '404':
          description: Listings not found
        '500':
          description: Internal server error
  /v2/instructions/sell:
    get:
      tags:
      - Solana
      summary: Get sell instructions
      description: Retrieve instructions for selling an NFT on Magic Eden.
      parameters:
      - name: seller
        in: query
        required: true
        schema:
          type: string
        example: EfdC1uyq5gWqHQYxSENscwNZKY8k2z8CXkpmPRB7mn2N
        description: The seller's wallet address.
      - name: auctionHouseAddress
        in: query
        required: true
        schema:
          type: string
        example: E8cU1WiRWjanGxmn96ewBgk9vPTcL6AEZ1t6F6fkgUWe
        description: The address of the auction house.
      - name: tokenMint
        in: query
        required: true
        schema:
          type: string
        example: 7kpQSvaSW5r4usqUHeqXCHK79zj4amadLdv1mpFpDiWR
        description: The mint address of the token.
      - name: tokenAccount
        in: query
        required: true
        schema:
          type: string
        example: HLfiWCHHma8BJDHPLt1q65v2cA4UXQKEswPCT1rEbQi4
        description: The token account address.
      - name: price
        in: query
        required: true
        schema:
          type: number
        example: 1
        description: The price of the token.
      responses:
        '200':
          description: Successful response
        '400':
          description: Invalid parameters
        '500':
          description: Internal server error
  /v2/tx/{txId}:
    post:
      tags:
      - Solana
      summary: Submit signed listing
      parameters:
      - in: path
        name: txId
        required: true
        schema:
          type: string
        description: The transaction ID to retrieve details for.
      requestBody:
        required: false
        content:
          application/json: {}
      responses:
        '200':
          description: Successful response
        '400':
          description: Bad request
        '404':
          description: Not found
        '500':
          description: Internal server error
  /v2/instructions/buy:
    get:
      tags:
      - Solana
      summary: Get buy instructions
      parameters:
      - name: buyer
        in: query
        required: true
        schema:
          type: string
        example: EfdC1uyq5gWqHQYxSENscwNZKY8k2z8CXkpmPRB7mn2N
      - name: auctionHouseAddress
        in: query
        required: true
        schema:
          type: string
        example: E8cU1WiRWjanGxmn96ewBgk9vPTcL6AEZ1t6F6fkgUWe
      - name: tokenMint
        in: query
        required: true
        schema:
          type: string
        example: 7kpQSvaSW5r4usqUHeqXCHK79zj4amadLdv1mpFpDiWR
      - name: price
        in: query
        required: true
        schema:
          type: number
        example: 1
      responses:
        '200':
          description: Successful response
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-NFT-API-Key
    cookieAuth:
      type: apiKey
      in: header
      name: Cookie
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT