openapi: 3.0.3
info:
  title: API اطلاعات بازار نوبیتکس
  version: "1.0.0"
  description: |
    APIهای عمومی بازار نوبیتکس شامل دفتر سفارشات، عمق بازار، معاملات اخیر،
    آمار بازار و داده‌های کندل/تاریخچه قیمت.

servers:
  - url: https://apiv2.nobitex.ir
  - url: https://testnetapiv2.nobitex.ir

tags:
  - name: اطلاعات بازار
    description: تمامی متدهای عمومی مربوط به داده‌های بازار

paths:
  /v2/orderbook:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    post:
      tags:
        - اطلاعات بازار
      summary: دریافت دفتر سفارشات
      description: |
        نسخه قدیمی دریافت دفتر سفارشات با ارسال نماد بازار در بدنه درخواست.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/SymbolRequest"
          application/json:
            schema:
              $ref: "#/components/schemas/SymbolRequest"
      responses:
        "200":
          description: موفق
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LegacyOrderBookResponse"
        "400":
          description: نماد نامعتبر
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FailedResponse"

  /v2/orderbook/{symbol}:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    get:
      tags:
        - اطلاعات بازار
      summary: دریافت دفتر سفارشات نسخه ۲
      description: |
        دفتر سفارشات یک بازار مشخص یا همه بازارها را برمی‌گرداند. برای دریافت همه بازارها
        مقدار `all` را به عنوان نماد ارسال کنید.

        توجه: این نسخه برای سازگاری قدیمی نگه داشته شده است.
      parameters:
        - $ref: "#/components/parameters/SymbolPath"
      responses:
        "200":
          description: موفق
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/OrderBookResponse"
                  - $ref: "#/components/schemas/OrderBookAllResponse"
        "400":
          description: نماد نامعتبر
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FailedResponse"

  /v3/orderbook/{symbol}:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    get:
      tags:
        - اطلاعات بازار
      summary: دریافت دفتر سفارشات نسخه ۳
      description: |
        دفتر سفارشات یک بازار مشخص یا همه بازارها را برمی‌گرداند. برای دریافت همه بازارها
        مقدار `all` را به عنوان نماد ارسال کنید.
      parameters:
        - $ref: "#/components/parameters/SymbolPath"
      responses:
        "200":
          description: موفق
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/OrderBookResponse"
                  - $ref: "#/components/schemas/OrderBookAllResponse"
        "400":
          description: نماد نامعتبر
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FailedResponse"

  /v2/depth/{symbol}:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    get:
      tags:
        - اطلاعات بازار
      summary: دریافت عمق بازار
      description: عمق بازار را به صورت داده‌های مناسب نمودار عمق برمی‌گرداند.
      parameters:
        - $ref: "#/components/parameters/SymbolPath"
      responses:
        "200":
          description: موفق
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DepthResponse"
        "400":
          description: نماد نامعتبر
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FailedResponse"

  /v2/trades:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    post:
      tags:
        - اطلاعات بازار
      summary: دریافت معاملات اخیر (نسخه قدیمی)
      description: نسخه قدیمی دریافت معاملات اخیر با ارسال نماد بازار در بدنه درخواست.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/SymbolRequest"
          application/json:
            schema:
              $ref: "#/components/schemas/SymbolRequest"
      responses:
        "200":
          description: موفق
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TradesResponse"
        "400":
          description: نماد نامعتبر
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FailedResponse"

  /v2/trades/{symbol}:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    get:
      tags:
        - اطلاعات بازار
      summary: دریافت معاملات اخیر
      description: لیست آخرین معاملات انجام‌شده برای یک بازار مشخص را برمی‌گرداند.
      parameters:
        - $ref: "#/components/parameters/SymbolPath"
      responses:
        "200":
          description: موفق
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TradesResponse"
        "400":
          description: نماد نامعتبر
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FailedResponse"

  /market/stats:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    get:
      tags:
        - اطلاعات بازار
      summary: آمار بازار
      description: |
        آمار بازار مانند بهترین سفارش خرید/فروش، آخرین قیمت، حجم، کف/سقف روزانه
        و تغییرات روزانه را برای یک یا چند بازار برمی‌گرداند.
      parameters:
        - $ref: "#/components/parameters/SrcCurrency"
        - $ref: "#/components/parameters/DstCurrency"
      responses:
        "200":
          description: موفق
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MarketStatsResponse"
        "400":
          description: ارز نامعتبر
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FailedResponse"
    post:
      tags:
        - اطلاعات بازار
      summary: آمار بازار (POST)
      description: نسخه POST آمار بازار با پارامترهای مشابه نسخه GET.
      requestBody:
        required: false
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/MarketStatsRequest"
          application/json:
            schema:
              $ref: "#/components/schemas/MarketStatsRequest"
      responses:
        "200":
          description: موفق
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MarketStatsResponse"
        "400":
          description: ارز نامعتبر
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FailedResponse"

  /market/udf/history:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    get:
      tags:
        - اطلاعات بازار
      summary: دریافت داده‌های OHLC
      description: |
        داده‌های کندل (Open, High, Low, Close, Volume) را در قالب سازگار با
        TradingView UDF برمی‌گرداند.
      parameters:
        - name: symbol
          in: query
          required: true
          description: نماد بازار، مانند `BTCIRT` یا `BTCUSDT`.
          schema:
            type: string
          example: BTCIRT
        - name: resolution
          in: query
          required: true
          description: تایم‌فریم کندل.
          schema:
            type: string
            enum: ["1", "5", "15", "30", "60", "180", "240", "360", "720", D, 2D, 3D]
          example: "60"
        - name: from
          in: query
          required: false
          description: زمان شروع به صورت timestamp ثانیه.
          schema:
            type: integer
            format: int64
        - name: to
          in: query
          required: true
          description: زمان پایان به صورت timestamp ثانیه.
          schema:
            type: integer
            format: int64
        - name: countback
          in: query
          required: false
          description: تعداد کندل‌های درخواستی قبل از زمان `to`.
          schema:
            type: integer
      responses:
        "200":
          description: موفق، بدون داده یا خطای UDF
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UDFHistoryResponse"
        "400":
          description: نماد نامعتبر
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FailedResponse"

components:
  parameters:
    TraderBotUserAgent:
      name: User-Agent
      in: header
      required: false
      description: |
        برای شناسایی بات، این هدر را در همه درخواست‌های HTTP بات با الگوی
        `TraderBot/<name-and-version>` ارسال کنید. این هدر هنگام ورود خودکار با
        `captcha=api` الزامی و در سایر فراخوانی‌های بات اکیداً توصیه می‌شود.
      schema:
        type: string
      example: TraderBot/MyBot-1.0.0

    SymbolPath:
      name: symbol
      in: path
      required: true
      description: نماد بازار مانند `BTCIRT`، `BTCUSDT` یا مقدار `all`.
      schema:
        type: string
      example: BTCIRT

    SrcCurrency:
      name: srcCurrency
      in: query
      required: false
      description: ارز یا فهرست ارزهای مبدا جداشده با کاما، مانند `btc,eth`.
      schema:
        type: string
      example: btc

    DstCurrency:
      name: dstCurrency
      in: query
      required: false
      description: ارز یا فهرست ارزهای مقصد جداشده با کاما، مانند `rls,usdt`.
      schema:
        type: string
      example: rls

  schemas:
    SymbolRequest:
      type: object
      required:
        - symbol
      properties:
        symbol:
          type: string
          description: نماد بازار.
          example: BTCIRT

    MarketStatsRequest:
      type: object
      properties:
        srcCurrency:
          type: string
          description: ارز یا فهرست ارزهای مبدا جداشده با کاما.
          example: btc,eth
        dstCurrency:
          type: string
          description: ارز یا فهرست ارزهای مقصد جداشده با کاما.
          example: rls,usdt

    FailedResponse:
      type: object
      properties:
        status:
          type: string
          example: failed
        code:
          type: string
          example: InvalidSymbol
        message:
          type: string

    OrderBookLevel:
      type: array
      description: سطح قیمت به صورت `[price, amount]`.
      minItems: 2
      maxItems: 2
      items:
        type: string
      example:
        - "6423000000"
        - "0.011121"

    LegacyOrderBookResponse:
      type: object
      properties:
        status:
          type: string
          example: ok
        bids:
          type: array
          items:
            $ref: "#/components/schemas/OrderBookLevel"
        asks:
          type: array
          items:
            $ref: "#/components/schemas/OrderBookLevel"

    OrderBookResponse:
      allOf:
        - $ref: "#/components/schemas/LegacyOrderBookResponse"
        - type: object
          properties:
            lastUpdate:
              type: integer
              format: int64
              nullable: true
              example: 1657620166710
            lastTradePrice:
              type: string
              example: "6423000000"

    OrderBookAllResponse:
      type: object
      description: پاسخ دریافت دفتر سفارشات برای نماد `all`.
      properties:
        status:
          type: string
          example: ok
      additionalProperties:
        oneOf:
          - $ref: "#/components/schemas/OrderBookResponse"
          - type: string

    DepthResponse:
      allOf:
        - $ref: "#/components/schemas/OrderBookResponse"
        - type: object
          properties:
            lastUpdate:
              type: string
              example: "1657620166710"
            lastTradePrice:
              type: string
              example: "831"

    PublicTrade:
      type: object
      properties:
        time:
          type: integer
          format: int64
          example: 1657621987917
        price:
          type: string
          example: "6415060000"
        volume:
          type: string
          example: "0.000001"
        type:
          type: string
          enum: [buy, sell]
          example: sell

    TradesResponse:
      type: object
      properties:
        status:
          type: string
          example: ok
        trades:
          type: array
          items:
            $ref: "#/components/schemas/PublicTrade"

    MarketStat:
      type: object
      properties:
        isClosed:
          type: boolean
        isClosedReason:
          type: string
          nullable: true
          example: NoData
        bestSell:
          type: string
          nullable: true
        bestBuy:
          type: string
          nullable: true
        volumeSrc:
          type: string
          nullable: true
        volumeDst:
          type: string
          nullable: true
        latest:
          type: string
          nullable: true
        mark:
          type: string
          nullable: true
        dayLow:
          type: string
          nullable: true
        dayHigh:
          type: string
          nullable: true
        dayOpen:
          type: string
          nullable: true
        dayClose:
          type: string
          nullable: true
        dayChange:
          type: string
          nullable: true

    MarketStatsResponse:
      type: object
      properties:
        status:
          type: string
          example: ok
        stats:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/MarketStat"
        global:
          type: object
          properties:
            binance:
              type: object
              additionalProperties: true

    UDFHistoryResponse:
      type: object
      properties:
        s:
          type: string
          enum: [ok, no_data, error]
          example: ok
        t:
          type: array
          items:
            type: integer
            format: int64
        o:
          type: array
          items:
            type: number
        h:
          type: array
          items:
            type: number
        l:
          type: array
          items:
            type: number
        c:
          type: array
          items:
            type: number
        v:
          type: array
          items:
            type: number
        errmsg:
          type: string
          description: پیام خطا در حالت `s=error`.