openapi: 3.0.3
info:
  title: Telegram Earn API
  version: 0.1.0
  description: OpenAPI schema for the Telegram Earn backend. Includes auth, investments,
    referrals, transactions, and payments.
paths:
  /api/commissions/:
    get:
      operationId: commissions_list
      description: Authenticated access to commissions earned by the user.
      parameters:
      - name: ordering
        required: false
        in: query
        description: Which field to use when ordering the results.
        schema:
          type: string
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      tags:
      - commissions
      security:
      - jwtAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedCommissionList'
          description: ''
  /api/commissions/{id}/:
    get:
      operationId: commissions_retrieve
      description: Authenticated access to commissions earned by the user.
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this commission.
        required: true
      tags:
      - commissions
      security:
      - jwtAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Commission'
          description: ''
  /api/investments/:
    get:
      operationId: investments_list
      description: Authenticated CRUD (create/list/retrieve) for a user's investments.
      parameters:
      - name: ordering
        required: false
        in: query
        description: Which field to use when ordering the results.
        schema:
          type: string
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      tags:
      - investments
      security:
      - jwtAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedInvestmentList'
          description: ''
    post:
      operationId: investments_create
      description: Create a new investment, deducting balance from user's credit_balance.
      tags:
      - investments
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Investment'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Investment'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Investment'
        required: true
      security:
      - jwtAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Investment'
          description: ''
        '400':
          description: 'Validation error. Possible reasons: amount below minimum ($10),
            invalid amount format, or insufficient balance. Error format: {"amount":
            ["error message"]}'
  /api/investments/{id}/:
    get:
      operationId: investments_retrieve
      description: Authenticated CRUD (create/list/retrieve) for a user's investments.
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this investment.
        required: true
      tags:
      - investments
      security:
      - jwtAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Investment'
          description: ''
    put:
      operationId: investments_update
      description: Authenticated CRUD (create/list/retrieve) for a user's investments.
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this investment.
        required: true
      tags:
      - investments
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Investment'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Investment'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Investment'
        required: true
      security:
      - jwtAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Investment'
          description: ''
    patch:
      operationId: investments_partial_update
      description: Authenticated CRUD (create/list/retrieve) for a user's investments.
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this investment.
        required: true
      tags:
      - investments
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedInvestment'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedInvestment'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedInvestment'
      security:
      - jwtAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Investment'
          description: ''
    delete:
      operationId: investments_destroy
      description: Authenticated CRUD (create/list/retrieve) for a user's investments.
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this investment.
        required: true
      tags:
      - investments
      security:
      - jwtAuth: []
      responses:
        '204':
          description: No response body
  /api/rewards/:
    get:
      operationId: rewards_list
      description: Read-only access to rewards tied to the authenticated user.
      parameters:
      - name: ordering
        required: false
        in: query
        description: Which field to use when ordering the results.
        schema:
          type: string
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      tags:
      - rewards
      security:
      - jwtAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedRewardList'
          description: ''
  /api/rewards/{id}/:
    get:
      operationId: rewards_retrieve
      description: Read-only access to rewards tied to the authenticated user.
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this reward.
        required: true
      tags:
      - rewards
      security:
      - jwtAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reward'
          description: ''
  /api/transactions/:
    get:
      operationId: transactions_list
      description: Authenticated access to the current user's transaction history.
      parameters:
      - name: ordering
        required: false
        in: query
        description: Which field to use when ordering the results.
        schema:
          type: string
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      tags:
      - transactions
      security:
      - jwtAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTransactionList'
          description: ''
  /api/transactions/{id}/:
    get:
      operationId: transactions_retrieve
      description: Authenticated access to the current user's transaction history.
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this transaction.
        required: true
      tags:
      - transactions
      security:
      - jwtAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
          description: ''
  /api/users/auth/telegram/:
    post:
      operationId: users_auth_telegram_create
      description: Authenticate a user via Telegram WebApp initData and issue JWTs.
      tags:
      - users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TelegramAuthRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TelegramAuthRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/TelegramAuthRequest'
        required: true
      security:
      - jwtAuth: []
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelegramAuthResponse'
          description: ''
        '400':
          description: Missing or invalid init_data/start_param
        '401':
          description: Telegram signature validation failed
  /api/users/auth/telegram/dev/:
    post:
      operationId: users_auth_telegram_dev_create
      description: Development-only Telegram auth helper. Validates a signed initData
        payload and returns JWTs plus signature debug info. Only available when DEBUG=True
        and ENABLE_DEV_TELEGRAM_AUTH=True.
      tags:
      - users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TelegramAuthRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TelegramAuthRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/TelegramAuthRequest'
        required: true
      security:
      - jwtAuth: []
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelegramAuthResponse'
          description: ''
        '400':
          description: Missing init_data
        '401':
          description: Signature validation failed
        '404':
          description: Dev auth disabled
  /api/users/telegram/webhook/:
    post:
      operationId: users_telegram_webhook_create
      description: Webhook for Telegram bot updates. Returns ok/forbidden depending
        on the configured webhook secret.
      tags:
      - users
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: {}
          application/x-www-form-urlencoded:
            schema:
              type: object
              additionalProperties: {}
          multipart/form-data:
            schema:
              type: object
              additionalProperties: {}
      security:
      - jwtAuth: []
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelegramWebhookResponse'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelegramWebhookResponse'
          description: ''
components:
  schemas:
    Commission:
      type: object
      description: Read-only serializer for commissions earned by an upline user.
      properties:
        id:
          type: integer
          readOnly: true
        upline_user:
          type: integer
          readOnly: true
        downline_user:
          type: integer
          readOnly: true
        reward:
          type: integer
          readOnly: true
        level:
          type: integer
          readOnly: true
        commission_rate:
          type: string
          format: decimal
          pattern: ^-?\d{0,3}(?:\.\d{0,2})?$
          readOnly: true
        amount:
          type: string
          format: decimal
          pattern: ^-?\d{0,12}(?:\.\d{0,8})?$
          readOnly: true
        status:
          allOf:
          - $ref: '#/components/schemas/CommissionStatusEnum'
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        distributed_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
      required:
      - amount
      - commission_rate
      - created_at
      - distributed_at
      - downline_user
      - id
      - level
      - reward
      - status
      - upline_user
    CommissionStatusEnum:
      enum:
      - pending
      - distributed
      type: string
      description: |-
        * `pending` - Pending
        * `distributed` - Distributed
    Investment:
      type: object
      description: Create/read investments with tier auto-calculation.
      properties:
        id:
          type: integer
          readOnly: true
        amount:
          type: string
          format: decimal
          pattern: ^-?\d{0,12}(?:\.\d{0,8})?$
        tier:
          allOf:
          - $ref: '#/components/schemas/TierEnum'
          readOnly: true
        daily_reward_rate:
          type: string
          format: decimal
          pattern: ^-?\d{0,3}(?:\.\d{0,2})?$
          readOnly: true
        duration_days:
          type: integer
          readOnly: true
        status:
          allOf:
          - $ref: '#/components/schemas/InvestmentStatusEnum'
          readOnly: true
        start_date:
          type: string
          format: date-time
          readOnly: true
        end_date:
          type: string
          format: date-time
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
      required:
      - amount
      - created_at
      - daily_reward_rate
      - duration_days
      - end_date
      - id
      - start_date
      - status
      - tier
      - updated_at
    InvestmentStatusEnum:
      enum:
      - pending
      - active
      - completed
      type: string
      description: |-
        * `pending` - Pending
        * `active` - Active
        * `completed` - Completed
    PaginatedCommissionList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/Commission'
    PaginatedInvestmentList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/Investment'
    PaginatedRewardList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/Reward'
    PaginatedTransactionList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
    PatchedInvestment:
      type: object
      description: Create/read investments with tier auto-calculation.
      properties:
        id:
          type: integer
          readOnly: true
        amount:
          type: string
          format: decimal
          pattern: ^-?\d{0,12}(?:\.\d{0,8})?$
        tier:
          allOf:
          - $ref: '#/components/schemas/TierEnum'
          readOnly: true
        daily_reward_rate:
          type: string
          format: decimal
          pattern: ^-?\d{0,3}(?:\.\d{0,2})?$
          readOnly: true
        duration_days:
          type: integer
          readOnly: true
        status:
          allOf:
          - $ref: '#/components/schemas/InvestmentStatusEnum'
          readOnly: true
        start_date:
          type: string
          format: date-time
          readOnly: true
        end_date:
          type: string
          format: date-time
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
    Reward:
      type: object
      description: Read-only serializer for daily rewards.
      properties:
        id:
          type: integer
          readOnly: true
        investment:
          type: integer
          readOnly: true
        amount:
          type: string
          format: decimal
          pattern: ^-?\d{0,12}(?:\.\d{0,8})?$
          readOnly: true
        reward_date:
          type: string
          format: date
          readOnly: true
        calculated_at:
          type: string
          format: date-time
          readOnly: true
        distributed_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
      required:
      - amount
      - calculated_at
      - distributed_at
      - id
      - investment
      - reward_date
    TelegramAuthRequest:
      type: object
      description: Incoming payload for Telegram WebApp authentication.
      properties:
        init_data:
          type: string
          description: Telegram initData string from the WebApp
        start_param:
          type: string
          description: Optional referral/start parameter passed from Telegram
      required:
      - init_data
    TelegramAuthResponse:
      type: object
      description: Token pair plus user payload after Telegram auth.
      properties:
        access:
          type: string
        refresh:
          type: string
        user:
          $ref: '#/components/schemas/TelegramAuthenticatedUser'
      required:
      - access
      - refresh
      - user
    TelegramAuthenticatedUser:
      type: object
      description: User details returned after a successful Telegram auth.
      properties:
        id:
          type: integer
          readOnly: true
        telegram_user_id:
          type: integer
          readOnly: true
        username:
          type: string
          nullable: true
        first_name:
          type: string
        last_name:
          type: string
          nullable: true
        language_code:
          type: string
          nullable: true
        photo_url:
          type: string
          format: uri
          nullable: true
        credit_balance:
          type: string
          format: decimal
          pattern: ^-?\d{0,12}(?:\.\d{0,8})?$
        referral_code:
          type: string
        referred_by:
          type: integer
          nullable: true
          description: ID of the referring user, if provided
      required:
      - credit_balance
      - first_name
      - id
      - referral_code
      - telegram_user_id
    TelegramWebhookResponse:
      type: object
      description: Acknowledgement returned to Telegram webhooks.
      properties:
        ok:
          type: boolean
        error:
          type: string
          nullable: true
      required:
      - ok
    TierEnum:
      enum:
      - 1
      - 2
      - 3
      - 4
      - 5
      - 6
      type: integer
      description: |-
        * `1` - Tier 1: ≤ $100
        * `2` - Tier 2: ≤ $500
        * `3` - Tier 3: ≤ $1,000
        * `4` - Tier 4: ≤ $2,000
        * `5` - Tier 5: ≤ $5,000
        * `6` - Tier 6: > $5,000
    Transaction:
      type: object
      description: Read-only view of wallet-impacting transactions.
      properties:
        id:
          type: integer
          readOnly: true
        transaction_type:
          allOf:
          - $ref: '#/components/schemas/TransactionTypeEnum'
          readOnly: true
        amount:
          type: string
          format: decimal
          pattern: ^-?\d{0,12}(?:\.\d{0,8})?$
          readOnly: true
        status:
          allOf:
          - $ref: '#/components/schemas/TransactionStatusEnum'
          readOnly: true
        balance_before:
          type: string
          format: decimal
          pattern: ^-?\d{0,12}(?:\.\d{0,8})?$
          readOnly: true
        balance_after:
          type: string
          format: decimal
          pattern: ^-?\d{0,12}(?:\.\d{0,8})?$
          readOnly: true
        blockchain:
          type: string
          readOnly: true
          nullable: true
          description: Blockchain for deposits/withdrawals (e.g., tron, bnb).
        transaction_hash:
          type: string
          readOnly: true
          nullable: true
        data:
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
      required:
      - amount
      - balance_after
      - balance_before
      - blockchain
      - created_at
      - data
      - id
      - status
      - transaction_hash
      - transaction_type
      - updated_at
    TransactionStatusEnum:
      enum:
      - pending
      - processing
      - completed
      - cancelled
      - forfeited
      type: string
      description: |-
        * `pending` - Pending
        * `processing` - Processing
        * `completed` - Completed
        * `cancelled` - Cancelled
        * `forfeited` - Forfeited
    TransactionTypeEnum:
      enum:
      - deposit
      - withdrawal
      - investment
      - reward
      - commission
      type: string
      description: |-
        * `deposit` - Deposit
        * `withdrawal` - Withdrawal
        * `investment` - Investment
        * `reward` - Reward
        * `commission` - Commission
  securitySchemes:
    jwtAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
