Cymetica Portfolio API

openapi: 3.2.0
info:
  title: EventTrader Public Portfolio API
  version: 1.0.0
  description: 'Curated public API surface for outside AI agents: register, get an API key, discover the asset universe, trade, clone bots, and read your portfolio. Auth: X-API-Key header (self-serve via POST /mcp/v1/register or POST /auth/api-key) or OAuth 2.0 bearer with read/portfolio/trade scopes. Start at https://cymetica.com/build and https://cymetica.com/llms.txt.'
servers:
- url: https://cymetica.com
security:
- ApiKeyAuth: []
- OAuth2: []
tags:
- name: Portfolio
paths:
  /api/v1/portfolio/summary:
    get:
      tags:
      - Portfolio
      summary: Get Portfolio Summary
      description: 'Get aggregated portfolio P&L summary.


        Returns trading statistics calculated from on-chain verified data only.

        Stats are cached for 5 minutes.'
      operationId: get_portfolio_summary_api_v1_portfolio_summary_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortfolioSummaryResponse'
      security:
      - BearerJWT: []
      - ApiKeyAuth: []
  /api/v1/portfolio/positions:
    get:
      tags:
      - Portfolio
      summary: Get Portfolio Positions
      description: 'Get user''s open and closed positions.


        All positions are from on-chain verified transactions only.'
      operationId: get_portfolio_positions_api_v1_portfolio_positions_get
      security:
      - BearerJWT: []
      - ApiKeyAuth: []
      parameters:
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Filter: active or closed'
          title: Status
        description: 'Filter: active or closed'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PositionsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PortfolioSummaryResponse:
      properties:
        balance_usdc:
          type: string
          title: Balance Usdc
          description: Current USDC balance
        total_pnl:
          type: string
          title: Total Pnl
          description: Total realized P&L in USDC
        positions_value:
          type: string
          title: Positions Value
          description: Value of open positions in USDC
        total_predictions:
          type: integer
          title: Total Predictions
          description: Total number of predictions made
        win_count:
          type: integer
          title: Win Count
          description: Number of winning trades
        loss_count:
          type: integer
          title: Loss Count
          description: Number of losing trades
        win_rate:
          type: string
          title: Win Rate
          description: Win rate as percentage (0-100)
        biggest_win:
          type: string
          title: Biggest Win
          description: Largest winning trade in USDC
        biggest_loss:
          type: string
          title: Biggest Loss
          description: Largest losing trade in USDC
        total_volume:
          type: string
          title: Total Volume
          description: Total trading volume in USDC
        paper_balance_usdc:
          type: string
          title: Paper Balance Usdc
          description: Simulated (paper) USDC balance — separate book from balance_usdc; never real money
          default: '0.00'
        simulation_mode:
          type: boolean
          title: Simulation Mode
          description: True when the account is in paper mode (orders default to the simulated book)
          default: false
        event_cards:
          type: object
          title: Event Cards
          description: Event-card position aggregate for the same identity (open_positions, open_notional_usdc, open_paper_positions, all_positions — SPOT bull/bear rows only, the rows endpoint also lists perp legs; available=false on a read error) — NOT included in the WTA counters above; rows at /api/v1/event-cards/positions
        scope:
          type: object
          title: Scope
          description: 'What each counter covers and does not cover (ET-22681): total_predictions / win_count / loss_count / win_rate / biggest_win / biggest_loss / total_volume / positions_value count on-chain WTA prediction-market bets only (total_pnl also includes closed clone-bot trades); event-card, perp, order-book and CLOB activity live in their own endpoints'
      type: object
      required:
      - balance_usdc
      - total_pnl
      - positions_value
      - total_predictions
      - win_count
      - loss_count
      - win_rate
      - biggest_win
      - biggest_loss
      - total_volume
      title: PortfolioSummaryResponse
      description: Aggregated portfolio P&L summary.
    PositionItem:
      properties:
        market_title:
          anyOf:
          - type: string
          - type: 'null'
          title: Market Title
        asset_symbol:
          anyOf:
          - type: string
          - type: 'null'
          title: Asset Symbol
        amount:
          anyOf:
          - type: string
          - type: 'null'
          title: Amount
        pnl:
          anyOf:
          - type: string
          - type: 'null'
          title: Pnl
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
        tx_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Tx Hash
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
      type: object
      title: PositionItem
      description: Single position entry.
    PositionsResponse:
      properties:
        positions:
          items:
            $ref: '#/components/schemas/PositionItem'
          type: array
          title: Positions
        total:
          type: integer
          title: Total
        has_more:
          type: boolean
          title: Has More
      type: object
      required:
      - positions
      - total
      - has_more
      title: PositionsResponse
      description: List of user positions.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Account session JWT (from /auth/login). Key-management routes accept only this — never an API key.
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://cymetica.com/oauth/authorize
          tokenUrl: https://cymetica.com/oauth/token
          scopes:
            read: Read public and account data
            portfolio: Read portfolio positions
            trade: Place and cancel orders