openapi: 3.0.3
info:
  title: Aladdin Trading API
  description: >-
    The Aladdin Trading API enables order management and trading workflow
    integration with BlackRock's Aladdin investment operating system.
    Available via the asdk_plugin_trading Python package.
  version: 1.0.0
  contact:
    name: Aladdin Studio
    url: https://www.blackrock.com/aladdin/products/apis
  license:
    name: Proprietary
    url: https://www.blackrock.com/aladdin/products/aladdin-studio
  x-generated-from: documentation
servers:
  - url: https://api.blackrock.com/trading/v1
    description: Aladdin Trading API server
security:
  - OAuth2: []
paths:
  /orders:
    get:
      operationId: listOrders
      summary: Aladdin Studio List Orders
      description: >-
        Retrieve a paginated list of trading orders with optional filtering
        by portfolio, status, and date range.
      tags:
        - Orders
      parameters:
        - name: portfolioId
          in: query
          description: Filter orders by portfolio
          schema:
            type: string
            example: PF-123456
        - name: status
          in: query
          description: Filter by order status
          schema:
            type: string
            enum:
              - pending
              - filled
              - partially_filled
              - cancelled
            example: pending
        - name: fromDate
          in: query
          description: Start date filter (YYYY-MM-DD)
          schema:
            type: string
            format: date
            example: "2026-04-01"
        - name: toDate
          in: query
          description: End date filter (YYYY-MM-DD)
          schema:
            type: string
            format: date
            example: "2026-04-19"
      responses:
        '200':
          description: List of orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderList'
              examples:
                listOrders200Example:
                  summary: Default listOrders 200 response
                  x-microcks-default: true
                  value:
                    orders:
                      - orderId: ORD-987654
                        portfolioId: PF-123456
                        securityId: US0378331005
                        side: buy
                        quantity: 100
                        status: pending
                    totalCount: 1
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createOrder
      summary: Aladdin Studio Create Order
      description: >-
        Create a new trading order for a portfolio security. Orders are
        submitted to Aladdin's order management system for processing.
      tags:
        - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
            examples:
              createOrderRequestExample:
                summary: Default createOrder request
                x-microcks-default: true
                value:
                  portfolioId: PF-123456
                  securityId: US0378331005
                  side: buy
                  quantity: 100
                  orderType: market
      responses:
        '201':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              examples:
                createOrder201Example:
                  summary: Default createOrder 201 response
                  x-microcks-default: true
                  value:
                    orderId: ORD-987654
                    portfolioId: PF-123456
                    securityId: US0378331005
                    side: buy
                    quantity: 100
                    status: pending
                    createdAt: "2026-04-19T10:30:00Z"
        '400':
          description: Invalid order parameters
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orders/{orderId}:
    get:
      operationId: getOrder
      summary: Aladdin Studio Get Order
      description: Retrieve details for a specific trading order.
      tags:
        - Orders
      parameters:
        - name: orderId
          in: path
          required: true
          description: Unique order identifier
          schema:
            type: string
            example: ORD-987654
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              examples:
                getOrder200Example:
                  summary: Default getOrder 200 response
                  x-microcks-default: true
                  value:
                    orderId: ORD-987654
                    portfolioId: PF-123456
                    securityId: US0378331005
                    side: buy
                    quantity: 100
                    filledQuantity: 100
                    status: filled
                    averagePrice: 195.00
                    createdAt: "2026-04-19T10:30:00Z"
                    filledAt: "2026-04-19T10:31:05Z"
        '404':
          description: Order not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth 2.0 authentication for trading operations
      flows:
        clientCredentials:
          tokenUrl: https://api.blackrock.com/oauth/token
          scopes:
            trading:read: Read trading data
            trading:write: Create and manage orders
  schemas:
    Order:
      title: Order
      type: object
      description: A trading order in the Aladdin system
      properties:
        orderId:
          type: string
          description: Unique order identifier
          example: ORD-987654
        portfolioId:
          type: string
          description: Portfolio identifier
          example: PF-123456
        securityId:
          type: string
          description: Security identifier
          example: US0378331005
        side:
          type: string
          description: Order side
          enum:
            - buy
            - sell
          example: buy
        quantity:
          type: number
          description: Order quantity in shares or units
          example: 100
        filledQuantity:
          type: number
          description: Quantity filled
          example: 100
        averagePrice:
          type: number
          description: Average execution price
          example: 195.00
        status:
          type: string
          description: Order status
          enum:
            - pending
            - filled
            - partially_filled
            - cancelled
          example: filled
        orderType:
          type: string
          description: Order type
          enum:
            - market
            - limit
            - stop
          example: market
        createdAt:
          type: string
          format: date-time
          description: Order creation timestamp
          example: "2026-04-19T10:30:00Z"
        filledAt:
          type: string
          format: date-time
          description: Order fill timestamp
          example: "2026-04-19T10:31:05Z"
    OrderList:
      title: OrderList
      type: object
      description: Paginated list of trading orders
      properties:
        orders:
          type: array
          items:
            $ref: '#/components/schemas/Order'
        totalCount:
          type: integer
          description: Total number of orders
          example: 42
    OrderRequest:
      title: OrderRequest
      type: object
      description: Request body for creating a new trading order
      required:
        - portfolioId
        - securityId
        - side
        - quantity
      properties:
        portfolioId:
          type: string
          description: Portfolio identifier
          example: PF-123456
        securityId:
          type: string
          description: Security identifier
          example: US0378331005
        side:
          type: string
          description: Order side
          enum:
            - buy
            - sell
          example: buy
        quantity:
          type: number
          description: Order quantity
          example: 100
        orderType:
          type: string
          description: Order type
          enum:
            - market
            - limit
            - stop
          example: market
        limitPrice:
          type: number
          description: Limit price (required for limit orders)
          example: 195.00
tags:
  - name: Orders
    description: Trading order management and execution