openapi: 3.0.3
info:
  title: TronCastle Energy API
  version: 1.0.1
  description: API for purchasing and managing delegated Energy on TronCastle.
servers:
  - url: https://api.troncastle.com

paths:
  /api/v1/account:
    get:
      summary: Get account information
      operationId: get_account
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Account details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      balance:
                        type: number
                      discount_level:
                        type: string
                      discount_level_human:
                        type: string
                      discount_percent:
                        type: number
                      total_energy_delegated:
                        type: number
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'

  /api/v1/estimate:
    post:
      summary: Estimate Energy purchase cost
      operationId: estimate_energy
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount, type]
              properties:
                amount:
                  type: number
                  description: Amount of energy requested
                type:
                  type: string
                  enum: [ENERGY]
                  description: Must be "ENERGY"
                duration_hours:
                  type: integer
                  description: Duration of delegation in hours (1 or 24)
      responses:
        '200':
          description: Estimated cost
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      energy_amount:
                        type: number
                      duration_hours:
                        type: number
                      price_trx:
                        type: number
                      price_usd:
                        type: number
                      discount_percent:
                        type: number
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        '422':
          description: Validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'

  /api/v1/buy:
    post:
      summary: Buy delegated Energy
      operationId: buy_energy
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount, type, wallet_for_energy]
              properties:
                amount:
                  type: number
                type:
                  type: string
                  enum: [ENERGY]
                wallet_for_energy:
                  type: string
                duration_hours:
                  type: integer
                  description: Duration of delegation in hours (1 or 24)
      responses:
        '200':
          description: Purchase completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      invoice_id:
                        type: string
                      balance_before:
                        type: number
                      balance_after:
                        type: number
                      amount_trx:
                        type: number
        '400':
          description: Bad request (e.g., insufficient balance)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'

  /api/v1/orders:
    get:
      summary: Get list of orders
      operationId: list_orders
      security:
        - ApiKeyAuth: []
      parameters:
        - in: query
          name: page
          schema:
            type: integer
          description: Page number (default 1)
        - in: query
          name: per_page
          schema:
            type: integer
          description: Items per page (default 50)
      responses:
        '200':
          description: List of orders. Use /orders/{id} to get details of a specific order (fill transaction IDs).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        nanoid:
                          type: string
                        amount_trx:
                          type: number
                        energy:
                          type: number
                        status:
                          type: string
                        wallet_for_energy:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                        energy_delegated_at:
                          type: string
                          format: date-time
                          nullable: true
                        energy_expires_at:
                          type: string
                          format: date-time
                          nullable: true
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                      per_page:
                        type: integer
                      total_items:
                        type: integer
                      total_pages:
                        type: integer
                      has_next_page:
                        type: boolean
                      has_prev_page:
                        type: boolean
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'

  /api/v1/orders/{id}:
    get:
      summary: Get details of a specific order
      operationId: get_order
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      order:
                        type: object
                        properties:
                          id:
                            type: string
                          amount_trx:
                            type: number
                          energy:
                            type: number
                          status:
                            type: string
                          wallet_for_energy:
                            type: string
                          created_at:
                            type: string
                            format: date-time
                          energy_delegated_at:
                            type: string
                            format: date-time
                            nullable: true
                          energy_expires_at:
                            type: string
                            format: date-time
                            nullable: true
                          delegate_error_msg:
                            type: string
                            nullable: true
                      fills:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                            energy_provided:
                              type: number
                            energy_delegated_at:
                              type: string
                              format: date-time
                              nullable: true
                            delegated_tn_id:
                              type: string
                              nullable: true
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'

  /api/v1/balance-operations:
    get:
      summary: Get list of balance operations
      operationId: list_balance_operations
      security:
        - ApiKeyAuth: []
      parameters:
        - in: query
          name: page
          schema:
            type: integer
        - in: query
          name: per_page
          schema:
            type: integer
      responses:
        '200':
          description: List of balance operations
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        nanoid:
                          type: string
                        amount:
                          type: number
                        balance:
                          type: number
                        notes:
                          type: string
                        invoice_id:
                          type: integer
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                      per_page:
                        type: integer
                      total_items:
                        type: integer
                      total_pages:
                        type: integer
                      has_next_page:
                        type: boolean
                      has_prev_page:
                        type: boolean
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Token

  schemas:
    error_response:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Short error code identifier
            message:
              type: string
              description: Human-readable error description
            request_id:
              type: string
              description: ID correlating request and error details
      required:
        - error