Magic Eden Runes Info API

openapi: 3.2.0
info:
  title: Magic Eden Bitcoin Ordinals Runes Info API
  description: Aggregated Magic Eden Bitcoin/Ordinals API covering ordinal collections, rare sats, runes (orders, swaps, sweeping, market sells), block activities, and wallet balances.
  version: v2
  termsOfService: https://magiceden.io/terms-of-service.pdf
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api-mainnet.magiceden.dev/v2
tags:
- name: Runes Info
paths:
  /v2/ord/btc/runes/activities/{rune}:
    get:
      tags:
      - Runes Info
      summary: Get activities for a specific rune
      parameters:
      - name: rune
        in: path
        description: The rune symbol for which activities are fetched.
        required: true
        schema:
          type: string
          pattern: ^[A-Z]{1,26}$
      - name: offset
        in: query
        description: Pagination offset for the list of activities. Defaults to 0, increments must be multiples of 100, up to 5000.
        required: false
        schema:
          type: integer
          minimum: 0
          maximum: 5000
          multipleOf: 100
      responses:
        '200':
          description: Successful response with an array of activity records for the specified rune.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRuneActivitiesResultSchema'
      operationId: getV2OrdBtcRunesActivitiesByRune
      x-operation-id-source: derived
  /v2/ord/btc/runes/collection_stats/search:
    get:
      tags:
      - Runes Info
      summary: Get Rune collection stats
      parameters:
      - name: window
        in: query
        description: Time window for which statistics are aggregated.
        required: true
        schema:
          type: string
          enum:
          - 10m
          - 1h
          - 6h
          - 1d
          - 7d
          - 30d
          default: 1d
      - name: limit
        in: query
        description: Limit the number of results returned. Default is 20, maximum is 2000.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 2000
      - name: offset
        in: query
        description: Pagination offset for results.
        required: false
        schema:
          type: integer
          minimum: 0
          maximum: 15000
      - name: sort
        in: query
        description: Column to sort the results by.
        required: true
        schema:
          type: string
          enum:
          - volume
          - volumePercentageChange
          - totalVolume
          - sales
          - salesPercentageChange
          - totalSales
          - floorPrice
          - floorPricePercentageChange
          - topOffer
          - listedOverSupply
          - ownerPercentage
          - pending
          - marketCap
          - ownerCount
          - listedCount
          default: floorPrice
      - name: direction
        in: query
        description: Direction of the sort ('asc' for ascending, 'desc' for descending).
        required: true
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - name: walletAddress
        in: query
        description: Filter results by a specific wallet address.
        required: false
        schema:
          type: string
      - name: searchTerm
        in: query
        description: Filter collections by a search term.
        required: false
        schema:
          type: string
          maxLength: 100
      - name: allCollections
        in: query
        description: Include all collections in the results, regardless of activity.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Successful response with collection statistics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCollectionStatsRuneResultSchema'
      operationId: getV2OrdBtcRunesCollectionStatsSearch
      x-operation-id-source: derived
  /v2/ord/btc/runes/market/{rune}/info:
    get:
      tags:
      - Runes Info
      summary: Get rune market info
      description: Get market market info for a specific rune
      parameters:
      - name: rune
        in: path
        description: Rune symbol
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRunesMarketInfoResultSchema'
      operationId: getV2OrdBtcRunesMarketByRuneInfo
      x-operation-id-source: derived
  /v2/ord/btc/runes/orders/{rune}:
    get:
      tags:
      - Runes Info
      summary: Get orders for a specific rune
      parameters:
      - name: rune
        in: path
        description: The rune symbol for which orders are requested.
        required: true
        schema:
          type: string
      - name: side
        in: query
        description: Filter by order side, currently only 'sell' orders are supported.
        required: true
        schema:
          type: string
          enum:
          - sell
      - name: sort
        in: query
        description: Sorting order of the results. Default is 'unitPriceAsc'.
        required: false
        schema:
          type: string
          enum:
          - unitPriceAsc
          - unitPriceDesc
          - totalPriceAsc
          - totalPriceDesc
      - name: offset
        in: query
        description: Pagination offset for the results. Default is 0, and increments of 100 are supported up to 2000.
        required: false
        schema:
          type: integer
          minimum: 0
          maximum: 2000
          multipleOf: 100
      - name: includePending
        in: query
        description: Whether to include pending orders in the results. Default is false.
        required: false
        schema:
          type: boolean
      - name: rbfPreventionListingOnly
        in: query
        description: Whether to only include RBF protected rune orders. Default is false.
        required: false
        schema:
          type: boolean
      - name: queryIssuerAddress
        in: query
        description: When "rbfPreventionListingOnly == true", filter the rune orders can be bought with RBF protection
        required: false
        schema:
          type: string
          pattern: ^(bc|tb)1p[023456789acdefghjklmnpqrstuvwxyz]{58}$
      responses:
        '200':
          description: Successful response with an array of orders for the specified rune.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRunesOrderInfoResultSchema'
      operationId: getV2OrdBtcRunesOrdersByRune
      x-operation-id-source: derived
  /v2/ord/btc/runes/utxos/wallet/{address}:
    get:
      tags:
      - Runes Info
      summary: Get rune utxos by wallet address
      parameters:
      - name: address
        in: path
        description: The Bitcoin address to fetch Rune UTXOs for.
        required: true
        schema:
          oneOf:
          - pattern: ^(bc|tb)1q[023456789acdefghjklmnpqrstuvwxyz]{38,58}$
          - pattern: ^(bc|tb)1p[023456789acdefghjklmnpqrstuvwxyz]{58}$
          - pattern: ^[32][1-9A-HJ-NP-Za-km-z]{33,34}$
      - name: rune
        in: query
        description: Filter UTXOs by rune symbol.
        required: true
        schema:
          type: string
          pattern: ^[A-Z]{1,26}$
      - name: sort
        in: query
        description: Sorting order of the UTXOs based on their balance. Defaults to 'balanceAsc'.
        required: false
        schema:
          type: string
          enum:
          - balanceDesc
          - balanceAsc
      - name: includeListed
        in: query
        description: Whether to include UTXOs that are currently listed in the marketplace. Defaults to false.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Successful response with an array of UTXOs for the specified address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRunesUtxoByWalletResultSchema'
      operationId: getV2OrdBtcRunesUtxosWalletByAddress
      x-operation-id-source: derived
  /v2/ord/btc/runes/wallet/activities/{address}:
    get:
      tags:
      - Runes Info
      summary: Get Rune activities for a specific wallet address
      parameters:
      - name: address
        in: path
        description: The wallet address to fetch Rune activities for.
        required: true
        schema:
          oneOf:
          - pattern: ^(bc|tb)1q[023456789acdefghjklmnpqrstuvwxyz]{38,58}$
          - pattern: ^(bc|tb)1p[023456789acdefghjklmnpqrstuvwxyz]{58}$
          - pattern: ^[32][1-9A-HJ-NP-Za-km-z]{33,34}$
      - name: offset
        in: query
        description: Pagination offset for the list of activities. Defaults to 0, increments must be multiples of 100, up to 10,000.
        required: false
        schema:
          type: integer
          minimum: 0
          maximum: 10000
          multipleOf: 100
      responses:
        '200':
          description: Successful response with an array of Rune activities for the specified wallet address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRuneActivitiesByAddressResultSchema'
      operationId: getV2OrdBtcRunesWalletActivitiesByAddress
      x-operation-id-source: derived
  /v2/ord/btc/runes/wallet/balances/{address}/{rune}:
    get:
      tags:
      - Runes Info
      summary: Get Rune balances by wallet address
      parameters:
      - name: address
        in: path
        description: The wallet address to fetch Rune balances for.
        required: true
        schema:
          oneOf:
          - pattern: ^(bc|tb)1q[023456789acdefghjklmnpqrstuvwxyz]{38,58}$
          - pattern: ^(bc|tb)1p[023456789acdefghjklmnpqrstuvwxyz]{58}$
          - pattern: ^[32][1-9A-HJ-NP-Za-km-z]{33,34}$
      - name: rune
        in: path
        description: The specific Rune symbol whose balance is being queried.
        required: true
        schema:
          type: string
          pattern: ^[A-Z]{1,26}$
      responses:
        '200':
          description: Successful response with the balance details of the specified Rune for the given address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBalanceByAddressAndRuneResultSchema'
      operationId: getV2OrdBtcRunesWalletBalancesByAddressByRune
      x-operation-id-source: derived
components:
  schemas:
    GetRuneActivitiesResultSchema:
      type: object
      properties:
        activities:
          type: array
          items:
            $ref: '#/components/schemas/RuneActivitySchema'
    GetRunesUtxoByWalletResultSchema:
      type: object
      properties:
        utxos:
          type: array
          items:
            $ref: '#/components/schemas/RuneUtxoSchema'
    RuneUtxoSchema:
      type: object
      properties:
        location:
          type: string
        address:
          type:
          - string
          - 'null'
        rune:
          type: string
        balance:
          type: number
        formattedBalance:
          type: string
        spent:
          type: boolean
        pure:
          type: boolean
        containsInscription:
          type:
          - boolean
          - 'null'
        costSats:
          type:
          - number
          - 'null'
        listing:
          type:
          - object
          - 'null'
          properties:
            orderId:
              type: string
              format: uuid
            totalPriceSats:
              type: number
            unitPriceSats:
              type: number
            formattedUnitPriceSats:
              type: string
            expiresAt:
              type: string
              format: date-time
    GetBalanceByAddressAndRuneResultSchema:
      type: object
      properties:
        balance:
          type: string
          description: The raw balance of the Rune, typically in its smallest unit.
        formattedBalance:
          type: string
          description: The formatted balance of the Rune, adjusted for human readability according to divisibility.
        ticker:
          type: string
          description: The symbol of the Rune whose balance is represented.
          pattern: ^[A-Z]{1,26}$
    RuneEtchingSchema:
      type: object
      properties:
        details:
          type: string
    GetCollectionStatsRuneResultSchema:
      type: object
      properties:
        runes:
          type: array
          items:
            $ref: '#/components/schemas/RuneStatsSchema'
    ISafeApiRuneOrderSchema:
      type: object
      properties:
        amount:
          type: number
        formattedAmount:
          type: string
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
        id:
          type: string
        rune:
          type: string
        mempoolTxId:
          type:
          - string
          - 'null'
        maker:
          type: string
        makerReceiveAddress:
          type: string
        makerFeeBps:
          type: number
        price:
          type: number
        side:
          type: string
        status:
          type: string
        unitPrice:
          type: number
        formattedUnitPrice:
          type: string
    RuneStatsSchema:
      type: object
      properties:
        rune:
          type: string
        etching:
          $ref: '#/components/schemas/RuneEtchingSchema'
        vol:
          type:
          - number
          - 'null'
        totalVol:
          type:
          - number
          - 'null'
        unitPriceSats:
          type:
          - number
          - 'null'
        formattedUnitPriceSats:
          type:
          - string
          - 'null'
        txnCount:
          type:
          - number
          - 'null'
        imageURI:
          type:
          - string
          - 'null'
        unitPriceChange:
          type:
          - number
          - 'null'
        holderCount:
          type:
          - number
          - 'null'
        pendingCount:
          type:
          - number
          - 'null'
    GetRunesMarketInfoResultSchema:
      type:
      - object
      - 'null'
      properties:
        rune:
          type: string
        ticker:
          type: string
        totalSupply:
          type: string
        formattedTotalSupply:
          type: string
        divisibility:
          type: integer
        imageURI:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        coinMarketCapLink:
          type:
          - string
          - 'null'
        discordLink:
          type:
          - string
          - 'null'
        telegramLink:
          type:
          - string
          - 'null'
        twitterLink:
          type:
          - string
          - 'null'
        minOrderSize:
          type:
          - integer
          - 'null'
        maxOrderSize:
          type:
          - integer
          - 'null'
        pendingTxnCount:
          type:
          - integer
          - 'null'
        floorUnitPrice:
          type:
          - object
          - 'null'
          properties:
            formatted:
              type: string
            value:
              type: string
        marketCap:
          type:
          - integer
          - 'null'
        volume:
          type: object
          properties:
            24h:
              type:
              - integer
              - 'null'
            7d:
              type:
              - integer
              - 'null'
            30d:
              type:
              - integer
              - 'null'
    GetRuneActivitiesByAddressResultSchema:
      type: object
      properties:
        activities:
          type: array
          items:
            $ref: '#/components/schemas/RuneActivitySchema'
    GetRunesOrderInfoResultSchema:
      type: object
      properties:
        orders:
          type: array
          items:
            $ref: '#/components/schemas/ISafeApiRuneOrderSchema'
    RuneActivitySchema:
      type: object
      properties:
        id:
          type: string
        kind:
          type: string
        oldOwner:
          type:
          - string
          - 'null'
        newOwner:
          type:
          - string
          - 'null'
        rune:
          type: string
        amount:
          type:
          - string
          - 'null'
        txValue:
          type:
          - string
          - 'null'
        txId:
          type:
          - string
          - 'null'
        txBlockTime:
          type:
          - string
          - 'null'
          format: date-time
        txBlockHeight:
          type:
          - integer
          - 'null'
        txBlockHash:
          type:
          - string
          - 'null'
        deletedAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
        listedPrice:
          type:
          - string
          - 'null'
        listedMakerFeeBp:
          type:
          - integer
          - 'null'
        listedTakerFeeBp:
          type:
          - integer
          - 'null'
        btcUsdPrice:
          type:
          - string
          - 'null'
        sellerPaymentReceiverAddress:
          type:
          - string
          - 'null'
        buyerPaymentAddress:
          type:
          - string
          - 'null'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer