openapi: 3.0.3
info:
  title: Aevo Exchange Private REST Account Orders API
  description: Authenticated REST API for Aevo exchange providing account management, order placement and management, position tracking, portfolio data, transfers, withdrawals, and trading history. Requires AEVO-KEY and AEVO-SECRET authentication headers obtained via cryptographic key registration.
  version: 1.0.0
  contact:
    name: Aevo Support
    url: https://docs.aevo.xyz/
servers:
- url: https://api.aevo.xyz
  description: Aevo Exchange production server
security:
- AevoKey: []
  AevoSecret: []
tags:
- name: Orders
  description: Order management endpoints
paths:
  /orders:
    get:
      tags:
      - Orders
      summary: Get open orders
      description: Returns all open orders for the authenticated account.
      operationId: getOrders
      responses:
        '200':
          description: List of open orders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      tags:
      - Orders
      summary: Create order
      description: Places a new order on the exchange. Requires a cryptographically signed payload.
      operationId: postOrders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '200':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      tags:
      - Orders
      summary: Cancel all orders
      description: Cancels all open orders for the authenticated account.
      operationId: deleteOrdersAll
      responses:
        '200':
          description: All orders cancelled
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /orders/{order_id}:
    get:
      tags:
      - Orders
      summary: Get order by ID
      description: Returns details for a specific order.
      operationId: getOrderById
      parameters:
      - name: order_id
        in: path
        required: true
        description: Order hash identifier.
        schema:
          type: string
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      tags:
      - Orders
      summary: Amend order
      description: Amends an existing order.
      operationId: amendOrder
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: string
                limit_price:
                  type: string
      responses:
        '200':
          description: Order amended
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      tags:
      - Orders
      summary: Cancel order
      description: Cancels a specific order by ID.
      operationId: deleteOrder
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Order cancelled
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /order-history:
    get:
      tags:
      - Orders
      summary: Get order history
      description: Returns historical orders for the authenticated account.
      operationId: getOrderHistory
      parameters:
      - name: start_time
        in: query
        required: false
        schema:
          type: integer
      - name: end_time
        in: query
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 10
          maximum: 50
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: Order history
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                  order_history:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /batch-orders:
    post:
      tags:
      - Orders
      summary: Place batch orders
      description: Places multiple orders in a single request.
      operationId: postBatchOrders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                orders:
                  type: array
                  items:
                    $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '200':
          description: Batch orders created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  responses:
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized - missing or invalid authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Malformed request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    CreateOrderRequest:
      type: object
      required:
      - instrument
      - maker
      - is_buy
      - amount
      - limit_price
      - salt
      - signature
      - timestamp
      properties:
        instrument:
          type: integer
          description: Instrument ID number
        maker:
          type: string
          description: Ethereum address of account
        is_buy:
          type: boolean
          description: True for long, false for short
        amount:
          type: string
          description: Contract quantity in 6 decimals
        limit_price:
          type: string
          description: Order price in 6 decimals
        salt:
          type: string
          description: Random number for order uniqueness
        signature:
          type: string
          description: Signed order payload hash
        timestamp:
          type: string
          description: UNIX timestamp in seconds
        post_only:
          type: boolean
        reduce_only:
          type: boolean
        time_in_force:
          type: string
          enum:
          - GTC
          - IOC
        mmp:
          type: boolean
        stop:
          type: string
          enum:
          - STOP_LOSS
          - TAKE_PROFIT
        trigger:
          type: number
          description: Stop order trigger price
        close_position:
          type: boolean
        partial_position:
          type: boolean
        parent_order_id:
          type: string
        perps_plus:
          type: boolean
        self_trade_prevention:
          type: string
          enum:
          - EXPIRE_NONE
          - EXPIRE_MAKER
          - EXPIRE_TAKER
    Order:
      type: object
      properties:
        order_id:
          type: string
        account:
          type: string
        instrument_id:
          type: string
        instrument_name:
          type: string
        instrument_type:
          type: string
          enum:
          - OPTION
          - PERPETUAL
          - SPOT
        order_type:
          type: string
          enum:
          - limit
          - market
        side:
          type: string
          enum:
          - buy
          - sell
        amount:
          type: string
        price:
          type: string
        avg_price:
          type: string
        filled:
          type: string
        order_status:
          type: string
          enum:
          - filled
          - partial
          - opened
          - cancelled
          - expired
          - rejected
          - stop_order
        post_only:
          type: boolean
        reduce_only:
          type: boolean
        time_in_force:
          type: string
          enum:
          - GTC
          - IOC
        initial_margin:
          type: string
        option_type:
          type: string
          enum:
          - call
          - put
        iv:
          type: string
        expiry:
          type: string
        strike:
          type: string
        created_timestamp:
          type: string
        timestamp:
          type: string
        system_type:
          type: string
          enum:
          - API
          - WEB
          - MOBILE_WEB
          - MOBILE_APP
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
  securitySchemes:
    AevoKey:
      type: apiKey
      in: header
      name: AEVO-KEY
      description: API key obtained from Aevo account settings
    AevoSecret:
      type: apiKey
      in: header
      name: AEVO-SECRET
      description: API secret obtained from Aevo account settings