openapi: 3.1.0
info:
  title: Cryptomus API
  description: >
    Cryptomus is a cryptocurrency payment gateway providing REST APIs for accepting
    crypto payments, creating invoices, processing payouts, managing recurring billing,
    and accessing real-time exchange rate and market data across 100+ cryptocurrencies.
  version: 1.0.0
  contact:
    name: Cryptomus Support
    url: https://cryptomus.com/
  termsOfService: https://cryptomus.com/terms
  license:
    name: Proprietary
    url: https://cryptomus.com/privacy

servers:
  - url: https://api.cryptomus.com/v1
    description: Cryptomus API v1 (Merchant & Payout)
  - url: https://api.cryptomus.com/v2
    description: Cryptomus API v2 (Exchange & Market Data)

security:
  - MerchantAuth: []

components:
  securitySchemes:
    MerchantAuth:
      type: apiKey
      in: header
      name: merchant
      description: >
        Merchant UUID from personal account settings. All requests also require a
        `sign` header computed as MD5(base64_encode(request_body) + API_KEY).

  headers:
    SignHeader:
      description: >
        Cryptographic signature: MD5(base64_encode(request_body) + API_KEY).
        For requests with no body, use MD5(base64_encode('') + API_KEY).
      schema:
        type: string

  schemas:
    PaginateResult:
      type: object
      properties:
        count:
          type: integer
          description: Number of items on the current page
        hasPages:
          type: boolean
          description: Whether multiple pages exist
        nextCursor:
          type: string
          nullable: true
          description: Cursor for the next page
        previousCursor:
          type: string
          nullable: true
          description: Cursor for the previous page
        perPage:
          type: integer
          description: Maximum items per page

    PaymentObject:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        order_id:
          type: string
        amount:
          type: string
        payment_amount:
          type: string
          nullable: true
        payer_amount:
          type: string
          nullable: true
        discount_percent:
          type: integer
          nullable: true
        discount:
          type: string
        payer_currency:
          type: string
          nullable: true
        currency:
          type: string
        merchant_amount:
          type: string
          nullable: true
        network:
          type: string
          nullable: true
        address:
          type: string
          nullable: true
        from:
          type: string
          nullable: true
        txid:
          type: string
          nullable: true
        payment_status:
          type: string
          enum: [process, check, paid, paid_over, fail, wrong_amount, cancel, system_fail, refund_process, refund_fail, refund_paid]
        url:
          type: string
          format: uri
        expired_at:
          type: integer
          description: Unix timestamp of expiry
        is_final:
          type: boolean
        additional_data:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    PayoutObject:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        amount:
          type: string
        currency:
          type: string
        network:
          type: string
        address:
          type: string
        txid:
          type: string
          nullable: true
        status:
          type: string
          enum: [process, check, paid, fail, cancel, system_fail]
        is_final:
          type: boolean
        balance:
          type: number
        payer_currency:
          type: string
        payer_amount:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    RecurringObject:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        name:
          type: string
        order_id:
          type: string
          nullable: true
        amount:
          type: string
        currency:
          type: string
        payer_currency:
          type: string
        payer_amount:
          type: string
        payer_amount_usd:
          type: string
        url_callback:
          type: string
          nullable: true
          format: uri
        discount_days:
          type: string
        discount_amount:
          type: string
        end_of_discount:
          type: string
          nullable: true
        period:
          type: string
          enum: [weekly, monthly, three_month]
        status:
          type: string
          enum: [wait_accept, active, cancel_by_merchant, cancel_by_user]
        url:
          type: string
          format: uri
        last_pay_off:
          type: string
          nullable: true

    ServiceItem:
      type: object
      properties:
        network:
          type: string
        currency:
          type: string
        is_available:
          type: boolean
        limit:
          type: object
          properties:
            min_amount:
              type: string
            max_amount:
              type: string
        commission:
          type: object
          properties:
            fee_amount:
              type: string
            percent:
              type: string

    ErrorResponse:
      type: object
      properties:
        state:
          type: integer
          description: Error state code (1 = error)
        message:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string

paths:

  # ── Payment Endpoints ──────────────────────────────────────────────────────

  /payment:
    post:
      operationId: createInvoice
      summary: Create a payment invoice
      description: Creates a cryptocurrency payment invoice for merchant integrations.
      tags:
        - Payments
      parameters:
        - in: header
          name: sign
          required: true
          schema:
            type: string
          description: MD5(base64_encode(body) + API_KEY)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
                - currency
                - order_id
              properties:
                amount:
                  type: string
                  description: Payment amount (e.g., "10.28")
                currency:
                  type: string
                  description: Currency code
                order_id:
                  type: string
                  minLength: 1
                  maxLength: 128
                  description: Unique merchant order ID (alphanumeric, dashes, underscores)
                network:
                  type: string
                  description: Blockchain network code
                url_return:
                  type: string
                  minLength: 6
                  maxLength: 255
                  description: Return URL after payment
                url_success:
                  type: string
                  minLength: 6
                  maxLength: 255
                  description: Success redirect URL
                url_callback:
                  type: string
                  minLength: 6
                  maxLength: 255
                  description: Webhook URL for payment status notifications
                is_payment_multiple:
                  type: boolean
                  default: true
                  description: Allow multiple payments for the same invoice
                lifetime:
                  type: integer
                  minimum: 300
                  maximum: 43200
                  default: 3600
                  description: Invoice lifespan in seconds
                to_currency:
                  type: string
                  description: Target cryptocurrency for conversion
                subtract:
                  type: integer
                  minimum: 0
                  maximum: 100
                  default: 0
                  description: Commission percentage deducted from payment amount
                accuracy_payment_percent:
                  type: number
                  minimum: 0
                  maximum: 5
                  default: 0
                  description: Accepted payment tolerance percentage
                additional_data:
                  type: string
                  maxLength: 255
                  description: Internal notes
                currencies:
                  type: array
                  items:
                    type: string
                  description: Allowed payment currencies
                except_currencies:
                  type: array
                  items:
                    type: string
                  description: Excluded payment currencies
                course_source:
                  type: string
                  enum: [Binance, BinanceP2P, Exmo, Kucoin]
                  description: Exchange rate source
                from_referral_code:
                  type: string
                  description: Referral connection code
                discount_percent:
                  type: integer
                  minimum: -99
                  maximum: 100
                  description: Discount (-) or commission (+) percentage applied
                is_refresh:
                  type: boolean
                  default: false
                  description: Refresh an expired invoice
      responses:
        '200':
          description: Invoice created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: integer
                  result:
                    $ref: '#/components/schemas/PaymentObject'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /payment/info:
    post:
      operationId: getPaymentInfo
      summary: Get payment information
      description: Retrieve details of a specific payment invoice.
      tags:
        - Payments
      parameters:
        - in: header
          name: sign
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                uuid:
                  type: string
                  format: uuid
                  description: Invoice UUID
                order_id:
                  type: string
                  minLength: 1
                  maxLength: 128
                  description: Invoice order ID (takes precedence if both provided)
      responses:
        '200':
          description: Payment information retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: integer
                  result:
                    $ref: '#/components/schemas/PaymentObject'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /payment/list:
    post:
      operationId: listPayments
      summary: List payment history
      description: Retrieve a paginated list of payment invoices with optional date filters.
      tags:
        - Payments
      parameters:
        - in: header
          name: sign
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                date_from:
                  type: string
                  description: Filter from date (YYYY-MM-DD H:mm:ss)
                date_to:
                  type: string
                  description: Filter to date (YYYY-MM-DD H:mm:ss)
                cursor:
                  type: string
                  description: Pagination cursor
      responses:
        '200':
          description: Payment list retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: integer
                  result:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/PaymentObject'
                      paginate:
                        $ref: '#/components/schemas/PaginateResult'

  /payment/services:
    post:
      operationId: listPaymentServices
      summary: List available payment services
      description: Retrieve available payment networks and currencies with limits and commissions.
      tags:
        - Payments
      parameters:
        - in: header
          name: sign
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Payment services list
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: integer
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/ServiceItem'

  /payment/refund:
    post:
      operationId: refundPayment
      summary: Refund a payment
      description: Issue a refund for a completed payment to a specified address.
      tags:
        - Payments
      parameters:
        - in: header
          name: sign
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - address
                - is_subtract
              properties:
                uuid:
                  type: string
                  format: uuid
                  description: Invoice UUID
                order_id:
                  type: string
                  minLength: 1
                  maxLength: 128
                  description: Invoice order ID
                address:
                  type: string
                  description: Wallet address to refund to
                is_subtract:
                  type: boolean
                  description: If true, deduct commission from merchant balance; if false, reduce refund amount
      responses:
        '200':
          description: Refund initiated
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: integer
                  result:
                    type: array
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /payment/mark-as-paid:
    post:
      operationId: markPaymentAsPaid
      summary: Mark payment as paid
      description: Manually mark an invoice as paid (test/internal use).
      tags:
        - Payments
      parameters:
        - in: header
          name: sign
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                uuid:
                  type: string
                  format: uuid
                order_id:
                  type: string
      responses:
        '200':
          description: Payment marked as paid
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string

  /payment/qr:
    post:
      operationId: getInvoiceQrCode
      summary: Generate invoice QR code
      description: Generate a QR code image for a payment invoice.
      tags:
        - Payments
      parameters:
        - in: header
          name: sign
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - merchant_payment_uuid
              properties:
                merchant_payment_uuid:
                  type: string
                  format: uuid
                  description: Invoice identifier
      responses:
        '200':
          description: QR code image returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: integer
                  result:
                    type: object
                    properties:
                      image:
                        type: string
                        description: Base64 encoded QR code image

  # ── Static Wallet Endpoints ───────────────────────────────────────────────

  /wallet:
    post:
      operationId: createStaticWallet
      summary: Create a static wallet
      description: Create a static cryptocurrency wallet for receiving repeated payments.
      tags:
        - Wallets
      parameters:
        - in: header
          name: sign
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - currency
                - network
                - order_id
              properties:
                currency:
                  type: string
                  description: Currency code
                network:
                  type: string
                  description: Blockchain network code
                order_id:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: Unique identifier in merchant system
                url_callback:
                  type: string
                  minLength: 6
                  maxLength: 255
                  description: Webhook URL for wallet top-ups
                from_referral_code:
                  type: string
                  description: Referral code for merchant attribution
      responses:
        '200':
          description: Static wallet created
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: integer
                  result:
                    type: object
                    properties:
                      wallet_uuid:
                        type: string
                        format: uuid
                      uuid:
                        type: string
                        format: uuid
                      address:
                        type: string
                      network:
                        type: string
                      currency:
                        type: string
                      url:
                        type: string
                        format: uri
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /wallet/qr:
    post:
      operationId: getWalletQrCode
      summary: Generate static wallet QR code
      description: Generate a QR code image for a static wallet address.
      tags:
        - Wallets
      parameters:
        - in: header
          name: sign
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - wallet_address_uuid
              properties:
                wallet_address_uuid:
                  type: string
                  format: uuid
                  description: Unique identifier for the static wallet
      responses:
        '200':
          description: QR code image returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: integer
                  result:
                    type: object
                    properties:
                      image:
                        type: string
                        description: Base64 encoded QR code image

  /wallet/block-address:
    post:
      operationId: blockStaticWallet
      summary: Block a static wallet
      description: Block a static wallet from receiving further payments.
      tags:
        - Wallets
      parameters:
        - in: header
          name: sign
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                uuid:
                  type: string
                  format: uuid
                  description: Static wallet identifier
                order_id:
                  type: string
                  minLength: 1
                  maxLength: 32
                  description: Order ID (takes precedence if both provided)
                is_force_refund:
                  type: boolean
                  default: false
                  description: If true, refund incoming payments to sender addresses
      responses:
        '200':
          description: Wallet blocked
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: integer
                  result:
                    type: object
                    properties:
                      uuid:
                        type: string
                        format: uuid
                      status:
                        type: string
                        enum: [blocked, active, in_active]
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  # ── Webhook Testing Endpoints ──────────────────────────────────────────────

  /test-webhook/payment:
    post:
      operationId: testPaymentWebhook
      summary: Test payment webhook
      description: Send a test webhook notification to verify your callback endpoint.
      tags:
        - Webhooks
      parameters:
        - in: header
          name: sign
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url_callback
                - currency
                - network
              properties:
                url_callback:
                  type: string
                  minLength: 6
                  maxLength: 150
                  description: Webhook destination URL
                currency:
                  type: string
                  description: Invoice currency code
                network:
                  type: string
                  description: Invoice network code
                uuid:
                  type: string
                  format: uuid
                  description: Invoice identifier (random if omitted)
                order_id:
                  type: string
                  minLength: 1
                  maxLength: 32
                  description: Invoice order ID (random if omitted)
                status:
                  type: string
                  default: paid
                  enum: [process, check, paid, paid_over, fail, wrong_amount, cancel, system_fail, refund_process, refund_fail, refund_paid]
      responses:
        '200':
          description: Test webhook sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: integer
                  result:
                    type: array

  /test-webhook/payout:
    post:
      operationId: testPayoutWebhook
      summary: Test payout webhook
      description: Send a test payout webhook notification to verify your callback endpoint.
      tags:
        - Webhooks
      parameters:
        - in: header
          name: sign
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url_callback
                - currency
                - network
              properties:
                url_callback:
                  type: string
                  minLength: 6
                  maxLength: 150
                currency:
                  type: string
                network:
                  type: string
                uuid:
                  type: string
                  format: uuid
                order_id:
                  type: string
                  minLength: 1
                  maxLength: 32
                status:
                  type: string
                  default: paid
                  enum: [process, check, paid, fail, cancel, system_fail]
      responses:
        '200':
          description: Test webhook sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: integer
                  result:
                    type: array

  /test-webhook/wallet:
    post:
      operationId: testWalletWebhook
      summary: Test wallet webhook
      description: Send a test wallet top-up webhook notification.
      tags:
        - Webhooks
      parameters:
        - in: header
          name: sign
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url_callback
                - currency
                - network
              properties:
                url_callback:
                  type: string
                  minLength: 6
                  maxLength: 150
                currency:
                  type: string
                network:
                  type: string
                uuid:
                  type: string
                  format: uuid
                order_id:
                  type: string
                  minLength: 1
                  maxLength: 32
                status:
                  type: string
                  default: paid
                  enum: [process, check, paid, paid_over, fail, wrong_amount, cancel, system_fail, refund_process, refund_fail, refund_paid]
      responses:
        '200':
          description: Test webhook sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: integer
                  result:
                    type: array

  # ── Payout Endpoints ──────────────────────────────────────────────────────

  /payout:
    post:
      operationId: createPayout
      summary: Create a payout
      description: Create a cryptocurrency payout to an external wallet address.
      tags:
        - Payouts
      parameters:
        - in: header
          name: sign
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
                - currency
                - order_id
                - address
                - is_subtract
              properties:
                amount:
                  type: string
                  description: Payout amount
                currency:
                  type: string
                  description: Currency code (fiat or crypto)
                order_id:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: Unique merchant order identifier
                address:
                  type: string
                  description: Recipient wallet address
                is_subtract:
                  type: boolean
                  description: If true, deduct fee from balance; if false, deduct from payout amount
                network:
                  type: string
                  description: Blockchain network code (required for multi-network cryptos)
                to_currency:
                  type: string
                  description: Target cryptocurrency (required when currency is fiat)
                from_currency:
                  type: string
                  description: Source balance for conversion (USDT only)
                url_callback:
                  type: string
                  description: Webhook URL for status updates
                course_source:
                  type: string
                  enum: [Binance, BinanceP2p, Exmo, Kucoin]
                  description: Exchange rate source
                priority:
                  type: string
                  enum: [recommended, economy, high, highest]
                  description: Withdrawal priority
                memo:
                  type: string
                  minLength: 1
                  maxLength: 30
                  description: TON-specific identifier
      responses:
        '200':
          description: Payout created
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: integer
                  result:
                    $ref: '#/components/schemas/PayoutObject'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /payout/info:
    post:
      operationId: getPayoutInfo
      summary: Get payout information
      description: Retrieve details of a specific payout.
      tags:
        - Payouts
      parameters:
        - in: header
          name: sign
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                uuid:
                  type: string
                  format: uuid
                  description: Payout UUID
                order_id:
                  type: string
                  minLength: 1
                  maxLength: 32
                  description: Payout order ID (takes precedence if both provided)
      responses:
        '200':
          description: Payout information
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: integer
                  result:
                    $ref: '#/components/schemas/PayoutObject'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /payout/list:
    post:
      operationId: listPayouts
      summary: List payout history
      description: Retrieve a paginated list of payouts with optional date filters.
      tags:
        - Payouts
      parameters:
        - in: header
          name: sign
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                date_from:
                  type: string
                  description: Filter from date (YYYY-MM-DD H:mm:ss)
                date_to:
                  type: string
                  description: Filter to date (YYYY-MM-DD H:mm:ss)
      responses:
        '200':
          description: Payout list
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: integer
                  result:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/PayoutObject'
                      paginate:
                        $ref: '#/components/schemas/PaginateResult'

  /payout/services:
    post:
      operationId: listPayoutServices
      summary: List available payout services
      description: Retrieve available payout networks and currencies with limits and commissions.
      tags:
        - Payouts
      parameters:
        - in: header
          name: sign
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Payout services list
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: integer
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/ServiceItem'

  # ── Recurring Payment Endpoints ───────────────────────────────────────────

  /recurrence/create:
    post:
      operationId: createRecurringPayment
      summary: Create a recurring payment
      description: Create a recurring cryptocurrency payment subscription.
      tags:
        - Recurring Payments
      parameters:
        - in: header
          name: sign
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
                - currency
                - name
                - period
              properties:
                amount:
                  type: string
                  description: Payment amount
                currency:
                  type: string
                  description: Currency code
                name:
                  type: string
                  minLength: 3
                  maxLength: 60
                  description: Subscription name
                period:
                  type: string
                  enum: [weekly, monthly, three_month]
                  description: Billing period
                to_currency:
                  type: string
                  description: Target cryptocurrency for conversion
                order_id:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: Merchant order identifier
                url_callback:
                  type: string
                  format: uri
                  description: Webhook endpoint for status updates
                discount_days:
                  type: integer
                  minimum: 1
                  maximum: 365
                  description: Introductory discount period in days
                discount_amount:
                  type: string
                  description: Discount amount in specified currency
                additional_data:
                  type: string
                  description: Extra payment details
      responses:
        '200':
          description: Recurring payment created
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: integer
                  result:
                    $ref: '#/components/schemas/RecurringObject'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /recurrence/info:
    post:
      operationId: getRecurringPaymentInfo
      summary: Get recurring payment information
      description: Retrieve details of a specific recurring payment.
      tags:
        - Recurring Payments
      parameters:
        - in: header
          name: sign
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                uuid:
                  type: string
                  format: uuid
                  description: Recurring payment UUID
                order_id:
                  type: string
                  minLength: 1
                  maxLength: 128
                  description: Order ID (takes precedence if both provided)
      responses:
        '200':
          description: Recurring payment information
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: integer
                  result:
                    $ref: '#/components/schemas/RecurringObject'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /recurrence/list:
    post:
      operationId: listRecurringPayments
      summary: List recurring payments
      description: Retrieve a paginated list of recurring payments.
      tags:
        - Recurring Payments
      parameters:
        - in: header
          name: sign
          required: true
          schema:
            type: string
        - in: query
          name: cursor
          schema:
            type: string
          description: Pagination cursor
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Recurring payments list
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: integer
                  result:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/RecurringObject'
                      paginate:
                        $ref: '#/components/schemas/PaginateResult'

  /recurrence/cancel:
    post:
      operationId: cancelRecurringPayment
      summary: Cancel a recurring payment
      description: Cancel an active recurring payment subscription.
      tags:
        - Recurring Payments
      parameters:
        - in: header
          name: sign
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                uuid:
                  type: string
                  format: uuid
                  description: Recurring payment UUID
                order_id:
                  type: string
                  description: Order ID (takes precedence if both provided)
      responses:
        '200':
          description: Recurring payment cancelled
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: integer
                  result:
                    $ref: '#/components/schemas/RecurringObject'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  # ── Exchange & Market Data Endpoints (v2) ────────────────────────────────

  /user-api/exchange/markets:
    get:
      operationId: listTradingPairs
      summary: List available trading pairs
      description: Retrieve all available cryptocurrency trading pairs for exchange.
      tags:
        - Exchange
      servers:
        - url: https://api.cryptomus.com/v2
      responses:
        '200':
          description: Trading pairs list
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Unique trading pair identifier
                        symbol:
                          type: string
                          description: Trading pair symbol in BASE_QUOTE format
                        baseCurrency:
                          type: string
                        quoteCurrency:
                          type: string
                        baseMinSize:
                          type: string
                        quoteMinSize:
                          type: string
                        baseMaxSize:
                          type: string
                        quoteMaxSize:
                          type: string
                        basePrec:
                          type: string
                        quotePrec:
                          type: string
        '404':
          description: Not found
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /user-api/exchange/markets/price:
    get:
      operationId: getMarketPrice
      summary: Get current market price
      description: Retrieve the current market price for a specific trading pair.
      tags:
        - Exchange
      servers:
        - url: https://api.cryptomus.com/v2
      parameters:
        - in: query
          name: symbol
          required: true
          schema:
            type: string
          description: Trading pair symbol (e.g., TRX_USDT)
      responses:
        '200':
          description: Current market price
          content:
            application/json:
              schema:
                type: object
                properties:
                  price:
                    type: string
                    description: Current asset price
        '404':
          description: Not found
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /user-api/exchange/orders/market:
    post:
      operationId: createMarketOrder
      summary: Create a market order
      description: Execute a market buy or sell order for a cryptocurrency trading pair.
      tags:
        - Exchange
      parameters:
        - in: header
          name: sign
          required: true
          schema:
            type: string
      servers:
        - url: https://api.cryptomus.com/v2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - market
                - quantity
                - direction
                - value
              properties:
                market:
                  type: string
                  description: Trading pair (e.g., TRX_USDT)
                quantity:
                  type: string
                  description: Amount in base currency
                direction:
                  type: string
                  enum: [buy, sell]
                  description: Order direction
                value:
                  type: string
                  description: Limit price in quote currency
                client_order_id:
                  type: string
                  description: Client-generated unique identifier
                tag:
                  type: string
                  description: Broker tag
      responses:
        '200':
          description: Order created
          content:
            application/json:
              schema:
                type: object
                properties:
                  order_id:
                    type: string
                    description: Successfully created order identifier
                  state:
                    type: integer
                    description: Error code (0 = success)
                  message:
                    type: string
        '404':
          description: Not found
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

tags:
  - name: Payments
    description: Create and manage payment invoices for merchant integrations
  - name: Wallets
    description: Create and manage static cryptocurrency wallets
  - name: Webhooks
    description: Test and manage webhook notifications
  - name: Payouts
    description: Create and manage cryptocurrency payouts
  - name: Recurring Payments
    description: Create and manage recurring payment subscriptions
  - name: Exchange
    description: Access exchange rates, trading pairs, and market data