Magic Eden Runes Swap API

openapi: 3.2.0
info:
  title: Magic Eden Bitcoin Ordinals Runes Swap 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 Swap
paths:
  /v2/ord/btc/runes/quote:
    get:
      tags:
      - Runes Swap
      summary: Get available rune quotes with given parameters for the swap
      parameters:
      - name: runeTicker
        in: query
        description: Rune symbol
        required: true
        schema:
          type: string
      - name: amount
        in: query
        description: The amount for the quote
        required: true
        schema:
          type: string
          format: bigint
      - name: side
        in: query
        description: The side of the trade, either "buy" or "sell"
        required: true
        schema:
          type: string
          enum:
          - buy
          - sell
      - name: priceToleranceBp
        in: query
        description: The price tolerance in percentage x 10000
        required: false
        schema:
          type: integer
      - name: rbfPreventionListingOnly
        in: query
        description: Flag indicating if only RBF protection sell orders should be considered.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetQuoteResponseSchema'
      operationId: getV2OrdBtcRunesQuote
      x-operation-id-source: derived
  /v2/ord/btc/runes/psbt/swap:
    post:
      tags:
      - Runes Swap
      summary: Get an unsigned PSBT for swapping runes
      requestBody:
        description: Post Request Body for get unsigned PSBT for swapping runes
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetRuneSwapPsbtRequestSchema'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRuneSwapPsbtResponseSchema'
      operationId: postV2OrdBtcRunesPsbtSwap
      x-operation-id-source: derived
  /v2/ord/btc/runes/swap:
    post:
      tags:
      - Runes Swap
      summary: Post a signed PSBT to broadcast the swapping transaction
      requestBody:
        description: Post Request Body for swapping runes
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostRuneSwapPsbtRequestSchema'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostRuneSwapPsbtResponseSchema'
      operationId: postV2OrdBtcRunesSwap
      x-operation-id-source: derived
components:
  schemas:
    GetRuneSwapPsbtRequestSchema:
      type: object
      properties:
        amount:
          type: string
          format: bigint
          description: The amount for the swap, represented as a string to accommodate large integers.
          minimum: 1
        priceToleranceBp:
          type:
          - integer
          - 'null'
          description: The price tolerance in percentate x 10000.
        runeTicker:
          type: string
          description: The ticker symbol for the rune.
        side:
          type: string
          enum:
          - buy
          - sell
          description: The side of the trade, either "buy" or "sell".
        takerPaymentAddress:
          type: string
          description: The payment address of the taker.
        takerPublicKey:
          type:
          - string
          - 'null'
          description: The public key of the taker, required for buying.
        takerRunesAddress:
          type: string
          description: The runes address of the taker.
        takerRunesPublicKey:
          type:
          - string
          - 'null'
          description: The runes public key of the taker, required for selling.
        feeRateTier:
          type: string
          enum:
          - custom
          - minimumFee
          - halfHourFee
          - hourFee
          - fastestFee
          description: The fee rate tier.
          default: hourFee
        feeRateNum:
          type:
          - number
          - 'null'
          description: The numerical fee rate.
        legacyListingOnly:
          type:
          - boolean
          - 'null'
          description: Flag indicating if only legacy listings should be considered.
        rbfPreventionListingOnly:
          type:
          - boolean
          - 'null'
          description: Flag indicating if only RBF prevention listings should be considered.
      required:
      - amount
      - runeTicker
      - side
      - takerPaymentAddress
      - takerRunesAddress
    SettlementSchema:
      type: object
      properties:
        amount:
          type: string
          format: bigint
          description: A large integer value, represented the total amount of runes.
        price:
          type: number
          format: float
          description: The price value as a floating-point number, represented the total amount of BTC payment.
      required:
      - amount
      - price
    GetRuneSwapPsbtResponseSchema:
      type: object
      properties:
        btcChangeOutputIndex:
          type:
          - integer
          - 'null'
          description: The index of the BTC change output, optional for sweeping post split.
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/RuneSwapErrorSchema'
          description: An array of errors encountered during the swap process.
        psbts:
          type: array
          items:
            $ref: '#/components/schemas/RuneSwapPsbtSchema'
          description: An array of PSBTs (Partially Signed Bitcoin Transactions).
        quote:
          $ref: '#/components/schemas/GetQuoteResponseSchema'
          description: The quote details for the swap.
        settlement:
          $ref: '#/components/schemas/SettlementSchema'
          description: The settlement details.
        requestId:
          type: string
          description: The unique request identifier.
      required:
      - psbts
      - quote
      - settlement
      - requestId
    RuneSwapPsbtSchema:
      type: object
      properties:
        type:
          type: string
          enum:
          - legacy-buy
          - rbf-buy
          - market-sell
          description: The type of the Rune swap transaction.
        paymentUtxoIndexes:
          type: array
          items:
            type: integer
          description: Array of payment UTXO indexes.
        psbtBase64:
          type: string
          description: The PSBT (Partially Signed Bitcoin Transaction) in base64 format.
        settlement:
          $ref: '#/components/schemas/SettlementSchema'
          description: The settlement details.
        runeUtxoIndexes:
          type: array
          items:
            type: integer
          description: Array of rune UTXO indexes.
      required:
      - type
      - paymentUtxoIndexes
      - psbtBase64
      - settlement
      - runeUtxoIndexes
    SignedSwapPsbtSchema:
      type: object
      properties:
        signedPsbtBase64:
          type: string
          description: The signed PSBT (Partially Signed Bitcoin Transaction) in base64 format.
      required:
      - signedPsbtBase64
    GetQuoteResponseSchema:
      type: object
      properties:
        amount:
          type: string
          format: bigint
          description: The total amount for the quote, represented as a string to accommodate large integers.
        averageUnitPrice:
          type: number
          description: The average unit price.
        bestUnitPrice:
          type: number
          description: The best unit price available.
        maxUnitPrice:
          type: number
          description: The maximum unit price.
        minUnitPrice:
          type: number
          description: The minimum unit price.
        price:
          type: number
          description: The total price.
        orders:
          type: array
          items:
            type: object
            properties:
              amount:
                type: string
                format: bigint
                description: The amount for the order, represented as a string to accommodate large integers.
              id:
                type: string
                description: The unique identifier for the order.
      required:
      - amount
      - averageUnitPrice
      - bestUnitPrice
      - maxUnitPrice
      - minUnitPrice
      - price
      - orders
    PostRuneSwapPsbtResponseSchema:
      type: object
      properties:
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/RuneSwapErrorSchema'
          description: An array of errors encountered during the swap process.
        txs:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - legacy-buy
                - rbf-buy
                - market-sell
                description: The type of the Rune swap transaction.
              txid:
                type: string
                description: The transaction ID.
          description: An array of transactions with their types and IDs.
      required:
      - txs
    RuneSwapErrorSchema:
      type: object
      properties:
        type:
          type: string
          enum:
          - legacy-buy
          - rbf-buy
          - market-sell
          description: The type of the Rune swap transaction error.
        message:
          type: string
          description: The error message.
      required:
      - type
      - message
    PostRuneSwapPsbtRequestSchema:
      type: object
      properties:
        requestId:
          type: string
          description: The unique request identifier.
        signedPsbts:
          type: array
          items:
            $ref: '#/components/schemas/SignedSwapPsbtSchema'
          description: An array of signed PSBTs (Partially Signed Bitcoin Transactions).
      required:
      - requestId
      - signedPsbts
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer