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: مدیریت دفتر آدرس و حالت برداشت امن

security:
  - TokenAuth: []

paths:
  /address_book:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    get:
      operationId: listAddressBook
      tags:
        - دفتر آدرس
      summary: مشاهده لیست آدرس‌های دفتر آدرس
      description: |
        لیست آدرس‌های ثبت‌شده در دفتر آدرس کاربر را برمی‌گرداند.

        ### محدودیت‌ها
        - فراخوانی: ۲۰ درخواست در دقیقه
        - در صورت استفاده از API Key، دسترسی `READ` روی کلید الزامی است.
      parameters:
        - name: network
          in: query
          required: false
          description: فیلتر بر اساس شبکه (مثلاً `BSC`). لیست شبکه‌ها را می‌توانید از [اینجا](/options/get-system-options) مشاهده کنید.
          schema:
            type: string
          example: BSC
      responses:
        "200":
          description: لیست آدرس‌ها
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [ok]
                    example: ok
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/AddressBookEntry"
              examples:
                success:
                  summary: دریافت موفق
                  value:
                    status: ok
                    data:
                      - id: 3
                        title: TetherBinance
                        network: BSC
                        address: "0000xxxx1111zzzz"
                        tag: null
                        createdAt: "2023-08-09T10:12:37+00:00"
                      - id: 4
                        title: BinanceCoinOKX
                        network: BNB
                        address: "0000xxxx2222zzzz"
                        tag: test17280992
                        createdAt: "2023-08-09T10:26:12+00:00"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"

    post:
      operationId: addAddressBook
      tags:
        - دفتر آدرس
      summary: افزودن آدرس به دفتر آدرس
      description: |
        یک آدرس جدید به دفتر آدرس کاربر اضافه می‌کند.

        ### محدودیت‌ها
        - فراخوانی: ۶ درخواست در دقیقه

        ### نکات
        - برای دریافت `otpCode` باید ابتدا از `/v2/otp/request` با `usage=address_book` استفاده شود.
        - اگر حالت `برداشت امن` فعال باشد، پس از افزودن آدرس جدید، برداشت رمزارزی به مدت ۱ ساعت محدود می‌شود.
        - افزودن آدرس از دستگاه ناشناس برای ۱ ساعت پس از ورود به سیستم مجاز نیست.
        - در صورت استفاده از API Key، دسترسی `ADDRESS_BOOK` روی کلید الزامی است. برای دریافت `otpCode` از `/v2/otp/request` با API Key، دسترسی `OTP` نیز لازم است.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddAddressRequest"
            examples:
              without_tag:
                summary: افزودن آدرس بدون تگ
                value:
                  title: TetherBinance
                  network: BSC
                  address: "0000xxxx1111zzzz"
                  otpCode: "123456"
                  tfaCode: "654321"
              with_tag:
                summary: افزودن آدرس با تگ
                value:
                  title: BinanceCoinOKX
                  network: BNB
                  address: "0000xxxx2222zzzz"
                  tag: test17280992
                  otpCode: "123456"
                  tfaCode: "654321"
      responses:
        "200":
          description: نتیجه افزودن آدرس (موفق یا ناموفق)
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/AddAddressSuccessResponse"
                  - $ref: "#/components/schemas/AddAddressFailedResponse"
              examples:
                success:
                  summary: افزودن موفق
                  value:
                    status: ok
                    data:
                      id: 5
                      title: TetherBinance
                      network: BSC
                      address: "0000xxxx1111zzzz"
                      tag: null
                      createdAt: "2023-08-09T10:22:37+00:00"
                failed_duplicated:
                  summary: آدرس تکراری
                  value:
                    status: failed
                    code: DuplicatedAddress
                    message: Duplicated Address!
        "403":
          description: ورود از دستگاه ناشناس — افزودن آدرس به مدت ۱ ساعت محدود شده
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [failed]
                    example: failed
                  code:
                    type: string
                    enum: [NewDeviceLoginRestriction]
                    example: NewDeviceLoginRestriction
                  message:
                    type: string
                    example: Adding address to address book is restricted for 1 hour after logging in from new device.
        "429":
          $ref: "#/components/responses/RateLimitExceeded"

  /address_book/{address_id}/delete:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    delete:
      operationId: deleteAddressBook
      tags:
        - دفتر آدرس
      summary: حذف آدرس از دفتر آدرس
      description: |
        یک آدرس ثبت‌شده در دفتر آدرس را با استفاده از شناسه آن حذف می‌کند.

        ### محدودیت‌ها
        - فراخوانی: ۶ درخواست در دقیقه
        - در صورت استفاده از API Key، دسترسی `ADDRESS_BOOK` روی کلید الزامی است.
      parameters:
        - name: address_id
          in: path
          required: true
          description: شناسه آدرس در دفتر آدرس
          schema:
            type: integer
          example: 5
      responses:
        "200":
          description: حذف موفق
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [ok]
                    example: ok
              examples:
                success:
                  summary: حذف موفق
                  value:
                    status: ok
        "404":
          description: آدرس یافت نشد
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [failed]
                    example: failed
                  code:
                    type: string
                    enum: [NotFound]
                    example: NotFound
                  message:
                    type: string
                    example: address does not exist
        "429":
          $ref: "#/components/responses/RateLimitExceeded"

  /address_book/whitelist/activate:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    post:
      operationId: activateWhitelist
      tags:
        - دفتر آدرس
      summary: فعال کردن برداشت امن
      description: |
        حالت برداشت امن (`Whitelist Mode`) را فعال می‌کند.
        در این حالت برداشت رمزارزی فقط به آدرس‌های موجود در دفتر آدرس مجاز است
        (به جز برداشت در شبکه لایتنینگ).

        ### محدودیت‌ها
        - فراخوانی: ۶ درخواست در دقیقه
        - در صورت استفاده از API Key، دسترسی `ADDRESS_BOOK` روی کلید الزامی است.

        ### نکات
        - اگر حالت برداشت امن از قبل فعال باشد، درخواست موفق می‌شود (بدون تغییر).
      responses:
        "200":
          description: موفق
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [ok]
                    example: ok
              examples:
                success:
                  summary: فعال‌سازی موفق
                  value:
                    status: ok
        "429":
          $ref: "#/components/responses/RateLimitExceeded"

  /address_book/whitelist/deactivate:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    post:
      operationId: deactivateWhitelist
      tags:
        - دفتر آدرس
      summary: غیرفعال کردن برداشت امن
      description: |
        حالت برداشت امن را غیرفعال می‌کند.

        ### محدودیت‌ها
        - فراخوانی: ۶ درخواست در دقیقه

        ### نکات
        - پس از غیرفعال‌سازی، برداشت رمزارزی به مدت ۲۴ ساعت محدود می‌شود.
        - برای دریافت `otpCode` باید ابتدا از `/v2/otp/request` با `usage=deactivate_whitelist` استفاده شود.
        - در صورت استفاده از API Key، دسترسی `ADDRESS_BOOK` روی کلید الزامی است. برای دریافت `otpCode` از `/v2/otp/request` با API Key، دسترسی `OTP` نیز لازم است.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeactivateWhitelistRequest"
            example:
              otpCode: "123456"
              tfaCode: "654321"
      responses:
        "200":
          description: نتیجه غیرفعال‌سازی (موفق یا ناموفق)
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/DeactivateWhitelistSuccessResponse"
                  - $ref: "#/components/schemas/DeactivateWhitelistFailedResponse"
              examples:
                success:
                  summary: غیرفعال‌سازی موفق
                  value:
                    status: ok
                failed_invalid_otp:
                  summary: کد یکبارمصرف نادرست
                  value:
                    status: failed
                    code: InvalidOTP
                    message: OTP is not valid!
        "429":
          $ref: "#/components/responses/RateLimitExceeded"

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

  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: |
        توکن احراز هویت به فرمت `Token <token>`.
        مثال: `Authorization: Token abc123`

  responses:
    RateLimitExceeded:
      description: محدودیت تعداد درخواست‌ها
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: failed
              code:
                type: string
                example: TooManyRequests

  schemas:
    AddressBookEntry:
      type: object
      description: یک آدرس در دفتر آدرس
      properties:
        id:
          type: integer
          description: شناسه یکتای آدرس
          example: 3
        title:
          type: string
          description: عنوان آدرس
          example: TetherBinance
        network:
          type: string
          description: شبکه انتقال
          example: BSC
        address:
          type: string
          description: آدرس کیف‌پول
          example: "0000xxxx1111zzzz"
        tag:
          type: string
          nullable: true
          description: تگ انتقال (در صورت وجود)
          example: sample_tag
        createdAt:
          type: string
          format: date-time
          description: زمان ثبت آدرس
          example: "2023-08-09T10:12:37+00:00"

    AddAddressRequest:
      type: object
      required:
        - title
        - network
        - address
        - otpCode
        - tfaCode
      properties:
        title:
          type: string
          description: عنوان آدرس
          example: TetherBinance
        network:
          type: string
          description: شبکه انتقال
          example: BSC
        address:
          type: string
          description: آدرس کیف‌پول مقصد
          example: "0000xxxx1111zzzz"
        tag:
          type: string
          description: تگ انتقال (در شبکه‌هایی که تگ اجباری است، الزامی است). لیست این شبکه‌ها را از [اینجا](/options/get-system-options) ببینید.
          example: "1234567890"
        otpCode:
          type: string
          description: کد یکبارمصرف (`OTP`) دریافت‌شده از طریق پیامک یا ایمیل
          example: "123456"
        tfaCode:
          type: string
          description: کد احراز هویت دوعاملی (`TOTP`)
          example: "654321"

    DeactivateWhitelistRequest:
      type: object
      required:
        - otpCode
        - tfaCode
      properties:
        otpCode:
          type: string
          description: کد یکبارمصرف (`OTP`) دریافت‌شده از طریق پیامک یا ایمیل
          example: "123456"
        tfaCode:
          type: string
          description: کد احراز هویت دوعاملی (`TOTP`)
          example: "654321"

    AddAddressSuccessResponse:
      type: object
      properties:
        status:
          type: string
          enum: [ok]
          example: ok
        data:
          $ref: "#/components/schemas/AddressBookEntry"

    AddAddressFailedResponse:
      type: object
      description: پاسخ خطا. فیلد `code` نوع خطا را مشخص می‌کند.
      properties:
        status:
          type: string
          enum: [failed]
          example: failed
        code:
          type: string
          description: |
            کد خطا.

            | کد | توضیح |
            |----|-------|
            | `Inactive2FA` | احراز هویت دوعاملی فعال نیست |
            | `InvalidOTP` | کد `OTP` نادرست است |
            | `Invalid2FA` | کد دوعاملی (`TOTP`) نادرست است |
            | `InvalidAddress` | آدرس برای این شبکه معتبر نیست |
            | `InvalidTag` | تگ نامعتبر است |
            | `DuplicatedAddress` | این آدرس قبلاً در دفتر آدرس ثبت شده است |
          example: DuplicatedAddress
        message:
          type: string
          description: توضیح خطا
          example: Duplicated Address!

    DeactivateWhitelistSuccessResponse:
      type: object
      properties:
        status:
          type: string
          enum: [ok]
          example: ok

    DeactivateWhitelistFailedResponse:
      type: object
      description: پاسخ خطا. فیلد `code` نوع خطا را مشخص می‌کند.
      properties:
        status:
          type: string
          enum: [failed]
          example: failed
        code:
          type: string
          description: |
            کد خطا.

            | کد | توضیح |
            |----|-------|
            | `Inactive2FA` | احراز هویت دوعاملی فعال نیست |
            | `InvalidOTP` | کد `OTP` نادرست است |
            | `Invalid2FA` | کد دوعاملی (`TOTP`) نادرست است |
          example: InvalidOTP
        message:
          type: string
          description: توضیح خطا
          example: OTP is not valid!