openapi: 3.1.0
info:
  title: Chatito Agent API
  version: 3.3.0-public-catalog
  summary: Strategy API for AI agents + public catalog/status
  description: |
    Paper-first trading automation platform. Phase 3 Lab + paper lifecycle.
    Public (no key): /public/catalog and /public/status for plans and onboarding.
    Starter paper on mint: if the owner has no running Predictions paper, key mint
    may auto-create a paper Late Edge book (origin agent_starter). See mint field
    starter_books and GET /me → starter_books. Never arms live. List before create.
    Live capital stays under human control. Not financial advice.
    Docs: https://chatito.ai/agent-api.md
  contact:
    url: https://chatito.ai/contact.md
servers:
  - url: https://app.chatito.com/api/agent/v1
    description: Production via app edge (Phase 1)
security:
  - AgentKey: []
paths:
  /public/catalog:
    get:
      summary: Plans, scopes, prices, human mint path (no auth)
      operationId: agentPublicCatalog
      security: []
      responses:
        "200":
          description: Public catalog
        "429":
          description: Rate limited
        "503":
          description: Agent API disabled
  /public/status:
    get:
      summary: Lightweight Agent API status (no auth)
      operationId: agentPublicStatus
      security: []
      responses:
        "200":
          description: Status
        "429":
          description: Rate limited
  /public/bootstrap:
    post:
      summary: Create claim-code bootstrap (free or paid Lab)
      operationId: agentPublicBootstrapCreate
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                scopes:
                  type: array
                  items:
                    type: string
                client_hint:
                  type: string
                intent:
                  type: string
                  enum: [mint_key, lab_month, lab_year]
                chain:
                  type: string
                  enum: [base, polygon]
      responses:
        "200":
          description: code + claim_url + poll + siwe paths
        "429":
          description: Rate limited
  /public/bootstrap/{code}:
    get:
      summary: Poll bootstrap; secret once after claim/pay
      operationId: agentPublicBootstrapPoll
      security: []
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Status; may include secret once
        "404":
          description: Unknown code
  /public/bootstrap/{code}/siwe/prepare:
    post:
      summary: SIWE message to bind wallet (Phase 3)
      operationId: agentPublicBootstrapSiwePrepare
      security: []
      responses:
        "200":
          description: message + nonce
  /public/bootstrap/{code}/siwe/verify:
    post:
      summary: Verify SIWE; invoice (paid) or mint (free)
      operationId: agentPublicBootstrapSiweVerify
      security: []
      responses:
        "200":
          description: need_payment + invoice or claimed key
  /public/bootstrap/{code}/confirm:
    post:
      summary: Confirm onchain payment; grant Lab + mint key
      operationId: agentPublicBootstrapConfirm
      security: []
      responses:
        "200":
          description: claimed + secret once in response
  /me:
    get:
      summary: Account + capacity for key owner
      operationId: agentMe
      responses:
        "200":
          description: |
            Agent account. Includes starter_books (agent_starter origin books when present).
        "401":
          description: Invalid key
  /health:
    get:
      summary: Venue health aggregate
      operationId: agentHealth
      responses:
        "200":
          description: Health
  /strategies:
    get:
      summary: List owned strategies (polymarket default · cex · dex)
      operationId: agentListStrategies
      parameters:
        - name: book
          in: query
          schema:
            type: string
            enum: [paper, live]
            default: paper
        - name: venue
          in: query
          description: polymarket (default) | cex | dex
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 25
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Strategy list
    post:
      summary: Create paper strategy (Predictions or CEX/DEX)
      operationId: agentCreateStrategy
      description: |
        Predictions kinds crypto_* or venue=cex|dex + kind dca_in|dca_out|limit.
        Never arms live.
      parameters:
        - name: Idempotency-Key
          in: header
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                kind:
                  type: string
                venue:
                  type: string
                  description: cex | dex for crypto paper books
                name:
                  type: string
                activate:
                  type: boolean
                params:
                  type: object
                symbol:
                  type: string
                quote_amount_usd:
                  type: number
      responses:
        "200":
          description: Created or waitlisted
        "403":
          description: scope_required
  /strategies/{strategy_id}:
    get:
      summary: Strategy detail
      operationId: agentGetStrategy
      parameters:
        - name: strategy_id
          in: path
          required: true
          schema:
            type: string
        - name: book
          in: query
          schema:
            type: string
            enum: [paper, live]
      responses:
        "200":
          description: Detail
        "404":
          description: Not found
  /strategies/{strategy_id}/equity:
    get:
      summary: Equity series
      operationId: agentEquity
      parameters:
        - name: strategy_id
          in: path
          required: true
          schema:
            type: string
        - name: book
          in: query
          schema:
            type: string
        - name: period
          in: query
          schema:
            type: string
            enum: [day, week, month, all]
      responses:
        "200":
          description: Equity points
  /strategies/{strategy_id}/stats:
    get:
      summary: Strategy statistics + Lab evaluation (sample_tier, promote/kill)
      operationId: agentStats
      parameters:
        - name: strategy_id
          in: path
          required: true
          schema:
            type: string
        - name: book
          in: query
          schema:
            type: string
            enum: [paper, live]
            default: paper
      responses:
        "200":
          description: |
            Stats with n_settled, sample_tier, evidence, evaluation
            (promote_passes, kill_candidate, …), lab lifecycle, gates thresholds.
  /lab/gates:
    get:
      summary: Lab sample / promote / kill gate catalog
      operationId: agentLabGates
      responses:
        "200":
          description: Thresholds + sample_tier legend (read scope)
  /strategies/{strategy_id}/fills:
    get:
      summary: Recent fills (capped)
      operationId: agentFills
      parameters:
        - name: strategy_id
          in: path
          required: true
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            maximum: 50
      responses:
        "200":
          description: Fills
  /markets/heat:
    get:
      summary: CEX or DEX Heat board
      operationId: agentHeat
      parameters:
        - name: venue
          in: query
          required: true
          schema:
            type: string
            enum: [cex, dex]
        - name: mode
          in: query
          schema:
            type: string
            default: balanced
        - name: limit
          in: query
          schema:
            type: integer
            default: 25
      responses:
        "200":
          description: Heat board
        "503":
          description: Venue unavailable
  /keys/me:
    get:
      summary: Presenting key metadata
      operationId: agentKeyMe
      responses:
        "200":
          description: Key metadata
  /templates:
    get:
      summary: List paper strategy templates
      operationId: agentTemplates
      parameters:
        - name: venue
          in: query
          description: omit for Predictions · cex | dex for CEX/DEX kinds
          schema:
            type: string
      responses:
        "200":
          description: Templates
  /strategies/{strategy_id}/paper/enable:
    post:
      summary: Enable paper trading
      operationId: agentEnablePaper
      parameters:
        - name: strategy_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Enabled
  /strategies/{strategy_id}/pause:
    post:
      summary: Pause paper trading
      operationId: agentPause
      parameters:
        - name: strategy_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Paused
  /strategies/{strategy_id}/kill:
    post:
      summary: Soft kill (stop paper, keep data)
      operationId: agentKill
      parameters:
        - name: strategy_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Soft killed
  /webhooks:
    get:
      summary: List webhooks
      operationId: agentListWebhooks
      responses:
        "200":
          description: Webhook list
        "403":
          description: scope_required (webhooks:manage)
    post:
      summary: Register webhook
      operationId: agentCreateWebhook
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url:
                  type: string
                events:
                  type: array
                  items:
                    type: string
                    enum:
                      - strategy.created
                      - strategy.paused
                      - strategy.killed
                      - fill.paper
                description:
                  type: string
                secret:
                  type: string
      responses:
        "200":
          description: Created (includes secret once)
  /webhooks/{webhook_id}:
    patch:
      summary: Update webhook
      operationId: agentPatchWebhook
      parameters:
        - name: webhook_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Updated
    delete:
      summary: Revoke webhook
      operationId: agentDeleteWebhook
      parameters:
        - name: webhook_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Revoked
  /webhooks/{webhook_id}/test:
    post:
      summary: Send synthetic test delivery
      operationId: agentTestWebhook
      parameters:
        - name: webhook_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Delivery attempt result

components:
  securitySchemes:
    AgentKey:
      type: http
      scheme: bearer
      bearerFormat: chk
      description: Agent API key from Settings → Agent API (chk_…)