openapi: 3.0.3
info:
  title: StoneX Clearing API
  description: >-
    The StoneX Clearing REST API provides programmatic access to accounts,
    trading, and document management for institutional clearing clients.
    Uses OAuth 2.0 authentication with JWT tokens (10-hour lifetime).
    Available in UAT and production environments.
  version: '1.0'
  contact:
    url: https://docs.clearing.stonex.com/
servers:
  - url: https://api.clearing.stonex.com
    description: StoneX Clearing Production
  - url: https://api.clearing.uat.stonex.com
    description: StoneX Clearing UAT (Test)
tags:
  - name: Authentication
    description: OAuth 2.0 token management.
  - name: Accounts
    description: Account information and management.
  - name: Trading
    description: Trade submission and management.
  - name: Documents
    description: Document retrieval and management.
paths:
  /auth/token:
    post:
      operationId: getAuthToken
      summary: Get Authentication Token
      description: >-
        Obtain a JWT access token using OAuth 2.0 client credentials.
        The token is valid for 10 hours and must be passed as a Bearer
        token in the Authorization header.
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - client_id
                - client_secret
              properties:
                client_id:
                  type: string
                  description: OAuth 2.0 client ID.
                client_secret:
                  type: string
                  description: OAuth 2.0 client secret.
                grant_type:
                  type: string
                  enum: [client_credentials]
                  default: client_credentials
      responses:
        '200':
          description: JWT access token returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          description: Invalid credentials.
  /accounts:
    get:
      operationId: listAccounts
      summary: List Accounts
      description: Retrieve a list of clearing accounts accessible to the authenticated client.
      tags:
        - Accounts
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
          description: Page number.
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
          description: Results per page.
      responses:
        '200':
          description: Accounts list returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountList'
        '401':
          description: Unauthorized.
  /accounts/{accountId}:
    get:
      operationId: getAccount
      summary: Get Account
      description: Retrieve details of a specific clearing account.
      tags:
        - Accounts
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: string
          description: Unique account identifier.
      responses:
        '200':
          description: Account details returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '401':
          description: Unauthorized.
        '404':
          description: Account not found.
  /accounts/{accountId}/positions:
    get:
      operationId: getAccountPositions
      summary: Get Account Positions
      description: Retrieve current positions for a clearing account.
      tags:
        - Accounts
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: string
          description: Account identifier.
      responses:
        '200':
          description: Account positions returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PositionList'
        '401':
          description: Unauthorized.
        '404':
          description: Account not found.
  /accounts/{accountId}/balances:
    get:
      operationId: getAccountBalances
      summary: Get Account Balances
      description: Retrieve cash, margin, and P&L balances for a clearing account.
      tags:
        - Accounts
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: string
          description: Account identifier.
      responses:
        '200':
          description: Account balances returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balance'
        '401':
          description: Unauthorized.
        '404':
          description: Account not found.
  /trades:
    post:
      operationId: submitTrade
      summary: Submit Trade
      description: Submit a trade for clearing and settlement.
      tags:
        - Trading
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TradeRequest'
      responses:
        '201':
          description: Trade submitted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trade'
        '400':
          description: Invalid trade request.
        '401':
          description: Unauthorized.
    get:
      operationId: listTrades
      summary: List Trades
      description: Retrieve a list of trades with optional filtering.
      tags:
        - Trading
      parameters:
        - name: account_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by account ID.
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: [pending, confirmed, settled, cancelled]
          description: Filter by trade status.
        - name: from_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Start date filter.
        - name: to_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: End date filter.
      responses:
        '200':
          description: Trades list returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradeList'
        '401':
          description: Unauthorized.
  /trades/{tradeId}:
    get:
      operationId: getTrade
      summary: Get Trade
      description: Retrieve details of a specific trade.
      tags:
        - Trading
      parameters:
        - name: tradeId
          in: path
          required: true
          schema:
            type: string
          description: Trade identifier.
      responses:
        '200':
          description: Trade details returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trade'
        '401':
          description: Unauthorized.
        '404':
          description: Trade not found.
  /documents:
    get:
      operationId: listDocuments
      summary: List Documents
      description: Retrieve a list of clearing documents.
      tags:
        - Documents
      parameters:
        - name: account_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by account ID.
        - name: document_type
          in: query
          required: false
          schema:
            type: string
          description: Filter by document type.
        - name: from_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Start date filter.
        - name: to_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: End date filter.
      responses:
        '200':
          description: Documents list returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentList'
        '401':
          description: Unauthorized.
  /documents/{documentId}:
    get:
      operationId: getDocument
      summary: Get Document
      description: Retrieve a specific clearing document.
      tags:
        - Documents
      parameters:
        - name: documentId
          in: path
          required: true
          schema:
            type: string
          description: Document identifier.
      responses:
        '200':
          description: Document returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '401':
          description: Unauthorized.
        '404':
          description: Document not found.
components:
  schemas:
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: JWT Bearer access token.
        token_type:
          type: string
          description: Token type (Bearer).
        expires_in:
          type: integer
          description: Token expiry in seconds (36000 = 10 hours).
    Account:
      type: object
      properties:
        id:
          type: string
          description: Unique account identifier.
        name:
          type: string
          description: Account name.
        account_type:
          type: string
          description: Account type classification.
        status:
          type: string
          enum: [active, inactive, suspended]
          description: Account status.
        currency:
          type: string
          description: Base currency (ISO 4217).
        created_at:
          type: string
          format: date-time
          description: Account creation timestamp.
    AccountList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Account'
        total:
          type: integer
        page:
          type: integer
        page_size:
          type: integer
    Balance:
      type: object
      properties:
        account_id:
          type: string
          description: Account identifier.
        cash_balance:
          type: number
          description: Cash balance.
        margin_used:
          type: number
          description: Margin currently in use.
        margin_available:
          type: number
          description: Available margin.
        unrealized_pnl:
          type: number
          description: Unrealized profit and loss.
        realized_pnl:
          type: number
          description: Realized profit and loss.
        currency:
          type: string
          description: Balance currency (ISO 4217).
        as_of:
          type: string
          format: date-time
          description: Balance timestamp.
    Position:
      type: object
      properties:
        account_id:
          type: string
          description: Account identifier.
        symbol:
          type: string
          description: Instrument symbol.
        quantity:
          type: number
          description: Position size (positive = long, negative = short).
        average_price:
          type: number
          description: Average cost basis.
        market_price:
          type: number
          description: Current market price.
        market_value:
          type: number
          description: Current market value.
        unrealized_pnl:
          type: number
          description: Unrealized profit and loss.
    PositionList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Position'
        account_id:
          type: string
        as_of:
          type: string
          format: date-time
    TradeRequest:
      type: object
      required:
        - account_id
        - symbol
        - side
        - quantity
      properties:
        account_id:
          type: string
          description: Account to book the trade against.
        symbol:
          type: string
          description: Instrument symbol.
        side:
          type: string
          enum: [buy, sell]
          description: Trade direction.
        quantity:
          type: number
          description: Trade quantity.
        price:
          type: number
          description: Trade price (required for limit orders).
        trade_date:
          type: string
          format: date
          description: Trade date.
        settlement_date:
          type: string
          format: date
          description: Settlement date.
    Trade:
      type: object
      properties:
        id:
          type: string
          description: Unique trade identifier.
        account_id:
          type: string
          description: Account identifier.
        symbol:
          type: string
          description: Instrument symbol.
        side:
          type: string
          enum: [buy, sell]
        quantity:
          type: number
        price:
          type: number
        status:
          type: string
          enum: [pending, confirmed, settled, cancelled]
        trade_date:
          type: string
          format: date
        settlement_date:
          type: string
          format: date
        created_at:
          type: string
          format: date-time
    TradeList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Trade'
        total:
          type: integer
        page:
          type: integer
    Document:
      type: object
      properties:
        id:
          type: string
          description: Document identifier.
        account_id:
          type: string
          description: Associated account.
        document_type:
          type: string
          description: Type of document (e.g., statement, confirmation).
        date:
          type: string
          format: date
          description: Document date.
        url:
          type: string
          format: uri
          description: Download URL for the document.
    DocumentList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Document'
        total:
          type: integer
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: JWT token from /auth/token endpoint. Valid for 10 hours.
security:
  - BearerAuth: []