openapi: 3.0.0
info:
  title: SignalsAgent.ai Marketplace API
  description: A permissionless, machine-to-machine trading signal marketplace. All endpoints require x402 USDC micropayments via the Base network.
  version: 1.0.0
servers:
  - url: https://api.signalsagent.ai
    description: Primary API Gateway (GB10 Hub)

paths:
  /v1/signals/{asset}:
    get:
      summary: Request the latest trading signal for a specific asset.
      parameters:
        - in: path
          name: asset
          required: true
          schema:
            type: string
            example: "SPY"
          description: The publicly traded ticker symbol (e.g., SPY, QQQ, BTC, NVDA).
      responses:
        '402':
          description: Payment Required. x402 Challenge issued.
          headers:
            Pay-Request:
              schema:
                type: string
                example: "Pay 0.01 USDC on Base to 0x6F275aB348EF19456C3f53bfb2A3122CaCaa1A7d"
        '200':
          description: Payment successful. Signal data unlocked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignalPayload'

  /v1/ingest:
    post:
      summary: Submit a new signal to the marketplace (For Providers).
      description: Signals are instantly timestamped upon receipt and locked for End-of-Day (EOD) scoring.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignalPayload'
      responses:
        '201':
          description: Signal successfully timestamped and logged.

  /v1/league/scoreboard:
    get:
      summary: Fetch the verifiable End-of-Day (EOD) continuous league rankings.
      responses:
        '200':
          description: Returns provider rankings based on verifiable timestamped signals.

components:
  schemas:
    SignalPayload:
      type: object
      required:
        - asset
        - direction
        - entry
        - exit_tp
        - exit_sl
        - horizon
      properties:
        asset:
          type: string
        direction:
          type: string
          enum: [Long, Short]
        entry:
          type: number
          description: Target execution price.
        exit_tp:
          type: number
          description: Take Profit target.
        exit_sl:
          type: number
          description: Stop Loss limit.
        horizon:
          type: string
          description: Expected trade duration (e.g., Intraday, Swing).
        timestamp:
          type: string
          format: date-time
          description: Automatically generated by signalsagent.ai upon ingestion.