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