openapi: 3.0.3
info:
  title: Spot Market API
  description: Advanced market data and order-book operations. Use the Seller API for the simpler offer workflow.
  license:
    name: MIT
  version: 1.0.0
servers:
- url: https://aispotmarket.com/market/api
  description: Production advanced Market API
paths:
  /v1/account:
    get:
      tags:
      - crate
      summary: Read the authenticated buyer's current ledger balance and reservations.
      description: Read the authenticated buyer's current ledger balance and reservations.
      operationId: get_account
      responses:
        '200':
          description: Current buyer account summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerAccountSummary'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - bearer_buyer: []
  /v1/contracts:
    get:
      tags:
      - crate
      summary: List advanced market contracts owned by the authenticated buyer.
      description: List advanced market contracts owned by the authenticated buyer.
      operationId: market_list_contracts
      responses:
        '200':
          description: Paginated contract history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTicketsResponse'
      security:
      - bearer_buyer: []
    post:
      tags:
      - crate
      summary: Place an advanced capacity contract order directly on the market.
      description: Place an advanced capacity contract order directly on the market.
      operationId: market_create_contract
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContractRequest'
        required: true
      responses:
        '200':
          description: Capacity order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CapacityOrderResponse'
      security:
      - bearer_buyer: []
  /v1/contracts/{id}:
    get:
      tags:
      - crate
      summary: Read one advanced market contract.
      description: Read one advanced market contract.
      operationId: market_get_contract
      parameters:
      - name: id
        in: path
        description: Contract id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Delivery contract
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
      security:
      - bearer_buyer: []
  /v1/markets:
    get:
      tags:
      - crate
      summary: Browse model families, models, regions, and live quotes.
      description: Browse model families, models, regions, and live quotes.
      operationId: list_markets
      responses:
        '200':
          description: Grouped public spot market catalog
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketCatalogResponse'
  /v1/markets/{model_id}/candles:
    get:
      tags:
      - crate
      summary: Read trade-derived OHLCV candles.
      description: Read trade-derived OHLCV candles.
      operationId: list_candles
      parameters:
      - name: model_id
        in: path
        description: Model/instrument id, percent-encoded (openai%2Fgpt-oss-20b)
        required: true
        schema:
          type: string
      - name: region
        in: query
        description: Regional filter
        required: false
        schema:
          type: string
          nullable: true
      - name: interval
        in: query
        description: 1m, 5m, 1h, or 1d
        required: false
        schema:
          type: string
          nullable: true
      - name: from
        in: query
        description: Inclusive RFC 3339 timestamp
        required: false
        schema:
          type: string
          nullable: true
      - name: to
        in: query
        description: Exclusive RFC 3339 timestamp
        required: false
        schema:
          type: string
          nullable: true
      - name: limit
        in: query
        description: Maximum 2000 candles
        required: false
        schema:
          type: integer
          nullable: true
          minimum: 0
      responses:
        '200':
          description: Ascending OHLCV candles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CandleResponse'
  /v1/markets/{model_id}/estimate:
    get:
      tags:
      - crate
      summary: Estimate immediate fill, resting ETA, and a 24-hour limit-price suggestion.
      description: Estimate immediate fill, resting ETA, and a 24-hour limit-price suggestion.
      operationId: estimate_fill
      parameters:
      - name: model_id
        in: path
        description: Model/instrument id, percent-encoded (openai%2Fgpt-oss-20b)
        required: true
        schema:
          type: string
      - name: quantity
        in: query
        description: Requested tokens
        required: true
        schema:
          type: integer
          format: int64
          minimum: 0
      - name: region
        in: query
        description: Regional filter
        required: false
        schema:
          type: string
          nullable: true
      - name: limit_price
        in: query
        description: Limit price per 1,000 tokens
        required: false
        schema:
          type: string
          nullable: true
      - name: horizon_hours
        in: query
        description: Suggestion horizon
        required: false
        schema:
          type: integer
          format: int64
          nullable: true
          minimum: 0
      responses:
        '200':
          description: Explainable non-guaranteed fill guidance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FillEstimateResponse'
  /v1/orderbook:
    get:
      tags:
      - crate
      summary: Stream or snapshot the live order book. WebSocket upgrades use this path.
      description: Stream or snapshot the live order book. WebSocket upgrades use this path.
      operationId: orderbook
      responses:
        '200':
          description: Order-book snapshot or WebSocket upgrade
  /v1/orders:
    get:
      tags:
      - crate
      summary: Search all capacity orders owned by the authenticated buyer.
      description: Search all capacity orders owned by the authenticated buyer.
      operationId: list_orders
      parameters:
      - name: cursor
        in: query
        description: Cursor from the previous page
        required: false
        schema:
          type: string
          nullable: true
      - name: limit
        in: query
        description: Page size, 1-100
        required: false
        schema:
          type: integer
          nullable: true
          minimum: 0
      - name: q
        in: query
        description: Order id, ticket id, or instrument search
        required: false
        schema:
          type: string
          nullable: true
      - name: model_id
        in: query
        description: Exact instrument
        required: false
        schema:
          type: string
          nullable: true
      - name: region
        in: query
        description: Exact region
        required: false
        schema:
          type: string
          nullable: true
      - name: status
        in: query
        description: Order status
        required: false
        schema:
          type: string
          nullable: true
      responses:
        '200':
          description: Paginated order history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOrdersResponse'
      security:
      - bearer_buyer: []
  /v1/orders/{id}:
    get:
      tags:
      - crate
      summary: Poll a capacity order. GTC rests return `open` plus this id.
      description: Poll a capacity order. GTC rests return `open` plus this id.
      operationId: get_order
      parameters:
      - name: id
        in: path
        description: Capacity order id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Capacity order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CapacityOrderResponse'
        '403':
          description: Not the owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '404':
          description: Unknown order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - bearer_buyer: []
    delete:
      tags:
      - crate
      summary: Cancel the unfilled remainder of a resting buyer order.
      description: Cancel the unfilled remainder of a resting buyer order.
      operationId: cancel_order
      parameters:
      - name: id
        in: path
        description: Capacity order id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Order remainder cancelled
        '404':
          description: Open order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - bearer_buyer: []
  /v1/sellers/register:
    post:
      tags:
      - crate
      summary: Register a seller inference endpoint or idempotently refresh its profile.
      description: Register a seller inference endpoint or idempotently refresh its profile.
      operationId: register_seller
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterSellerRequest'
        required: true
      responses:
        '200':
          description: Registered seller
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterSellerResponse'
        '400':
          description: Invalid seller endpoint or request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '409':
          description: Endpoint already belongs to a seller and current credentials were not supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
  /v1/sellers/{id}/asks:
    get:
      tags:
      - crate
      summary: List the authenticated seller's active asks.
      description: List the authenticated seller's active asks.
      operationId: list_seller_asks
      parameters:
      - name: id
        in: path
        description: Seller id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Active seller asks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAsksResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '403':
          description: Wrong seller key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - x_seller_api_key: []
    post:
      tags:
      - crate
      summary: Rest a seller ask on the Spot order book.
      description: |-
        Rest a seller ask on the Spot order book.

        Authenticate with `X-Seller-API-Key`. `id` is the seller id returned at
        registration. Price is a decimal string per 1,000 tokens.
      operationId: submit_ask
      parameters:
      - name: id
        in: path
        description: Seller id returned by POST /v1/sellers/register
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitAskRequest'
        required: true
      responses:
        '200':
          description: Resting ask
          headers:
            RateLimit:
              schema:
                type: string
              description: Remaining quota for the current window
            RateLimit-Policy:
              schema:
                type: string
              description: Advertised per-key quota policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitAskResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '429':
          description: Per-key rate limit exceeded
          headers:
            RateLimit:
              schema:
                type: string
              description: Remaining quota (0 when exhausted)
            Retry-After:
              schema:
                type: string
              description: Seconds to wait before retrying
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - x_seller_api_key: []
  /v1/sellers/{id}/asks/{ask_id}:
    delete:
      tags:
      - crate
      summary: Cancel one active ask owned by the authenticated seller.
      description: Cancel one active ask owned by the authenticated seller.
      operationId: cancel_seller_ask
      parameters:
      - name: id
        in: path
        description: Seller id
        required: true
        schema:
          type: string
      - name: ask_id
        in: path
        description: Ask id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Ask cancelled
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '403':
          description: Wrong seller key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '404':
          description: Active ask not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - x_seller_api_key: []
  /v1/sellers/{id}/capacity:
    post:
      tags:
      - crate
      summary: Report informational capacity for a seller and model.
      description: |-
        Report informational capacity for a seller and model.

        Authenticate with `X-Seller-API-Key`. This updates the dashboard profile; it
        does not create asks or change the order book.
      operationId: report_capacity
      parameters:
      - name: id
        in: path
        description: Seller id returned by POST /v1/sellers/register
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportCapacityRequest'
        required: true
      responses:
        '200':
          description: Capacity snapshot
          headers:
            RateLimit:
              schema:
                type: string
              description: Remaining quota for the current window
            RateLimit-Policy:
              schema:
                type: string
              description: Advertised per-key quota policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportCapacityResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '429':
          description: Per-key rate limit exceeded
          headers:
            RateLimit:
              schema:
                type: string
              description: Remaining quota (0 when exhausted)
            Retry-After:
              schema:
                type: string
              description: Seconds to wait before retrying
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - x_seller_api_key: []
  /v1/sellers/{id}/decisions:
    post:
      tags:
      - crate
      summary: Record the seller automation's decision log.
      description: |-
        Record the seller automation's decision log.

        Authenticate with `X-Seller-API-Key`. Informational: it never changes the
        order book. Spot keeps the newest 200 decisions per seller so an operator
        can read back why capacity was or was not listed; the daemon keeps the
        durable copy locally.
      operationId: report_decisions
      parameters:
      - name: id
        in: path
        description: Seller id returned by POST /v1/sellers/register
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportDecisionsRequest'
        required: true
      responses:
        '200':
          description: Decisions recorded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportDecisionsResponse'
        '400':
          description: Empty batch, oversized batch, or an over-long reason
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '403':
          description: Wrong seller key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - x_seller_api_key: []
  /v1/sellers/{id}/deliveries:
    get:
      tags:
      - crate
      summary: List outstanding reserved lots for the authenticated seller.
      description: List outstanding reserved lots for the authenticated seller.
      operationId: list_seller_deliveries
      parameters:
      - name: id
        in: path
        description: Seller id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Outstanding reserved lots
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSellerDeliveriesResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '403':
          description: Wrong seller key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - x_seller_api_key: []
  /v1/sellers/{id}/reputation:
    get:
      tags:
      - crate
      summary: Read recent public reputation snapshots for a seller.
      description: Read recent public reputation snapshots for a seller.
      operationId: get_seller_reputation
      parameters:
      - name: id
        in: path
        description: Seller id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Current and recent seller reputation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SellerReputationResponse'
        '500':
          description: Reputation store unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
  /v1/sellers/{id}/trades:
    get:
      tags:
      - crate
      summary: List executions belonging to the authenticated seller.
      description: List executions belonging to the authenticated seller.
      operationId: list_seller_trades
      parameters:
      - name: id
        in: path
        description: Seller id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Seller execution history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSellerTradesResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '403':
          description: Wrong seller key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - x_seller_api_key: []
  /v1/trades:
    get:
      tags:
      - crate
      summary: Search all executions owned by the authenticated buyer.
      description: Search all executions owned by the authenticated buyer.
      operationId: list_trades
      parameters:
      - name: cursor
        in: query
        description: Cursor from the previous page
        required: false
        schema:
          type: string
          nullable: true
      - name: limit
        in: query
        description: Page size, 1-100
        required: false
        schema:
          type: integer
          nullable: true
          minimum: 0
      - name: q
        in: query
        description: Trade, leg, or instrument search
        required: false
        schema:
          type: string
          nullable: true
      - name: model_id
        in: query
        description: Exact instrument
        required: false
        schema:
          type: string
          nullable: true
      - name: region
        in: query
        description: Exact region
        required: false
        schema:
          type: string
          nullable: true
      responses:
        '200':
          description: Paginated buyer execution history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTradesResponse'
      security:
      - bearer_buyer: []
components:
  schemas:
    AskSummary:
      type: object
      description: Active seller ask.
      required:
      - ask_id
      - model_id
      - region
      - price
      - capacity
      - remaining
      - created_at
      - expires_at
      properties:
        ask_id:
          type: string
          description: Ask id.
        capacity:
          type: integer
          format: int64
          description: Original offered capacity.
          minimum: 0
        created_at:
          type: string
          description: Creation time.
        expires_at:
          type: string
          description: Expiry time.
        model_id:
          type: string
          description: Instrument.
        price:
          type: string
          description: Limit price per 1,000 tokens.
        region:
          type: string
          description: Delivery region.
        remaining:
          type: integer
          format: int64
          description: Unfilled capacity.
          minimum: 0
    Candle:
      type: object
      description: OHLCV candle derived from executed trades.
      required:
      - time
      - open
      - high
      - low
      - close
      - volume
      properties:
        close:
          type: string
          description: Last execution.
        high:
          type: string
          description: Highest execution.
        low:
          type: string
          description: Lowest execution.
        open:
          type: string
          description: First execution.
        time:
          type: string
          description: Bucket start.
        volume:
          type: integer
          format: int64
          description: Executed tokens.
          minimum: 0
    CandleResponse:
      type: object
      description: Candle history response.
      required:
      - model_id
      - interval
      - candles
      properties:
        candles:
          type: array
          items:
            $ref: '#/components/schemas/Candle'
          description: Candles in ascending time order.
        interval:
          type: string
          description: Bucket interval.
        model_id:
          type: string
          description: Instrument.
        region:
          type: string
          description: Regional filter, if any.
          nullable: true
    CapacityOrderResponse:
      type: object
      description: Response for `POST /v1/contracts` and `GET /v1/orders/{id}`.
      required:
      - order_id
      - status
      - instrument
      - quantity
      - filled
      properties:
        contract:
          allOf:
          - $ref: '#/components/schemas/Contract'
          nullable: true
        filled:
          type: integer
          format: int64
          description: Filled so far.
          minimum: 0
        instrument:
          type: string
          description: Instrument.
        order_id:
          type: string
          description: Buyer order id (the resting or completed bid).
        quantity:
          type: integer
          format: int64
          description: Requested size.
          minimum: 0
        status:
          $ref: '#/components/schemas/CapacityOrderStatus'
    CapacityOrderStatus:
      type: string
      description: Lifecycle of a capacity order.
      enum:
      - open
      - partial
      - filled
      - rejected
      - cancelled
    Contract:
      type: object
      description: Delivery ticket minted when a capacity order fills.
      required:
      - id
      - remaining
      - quantity
      - expires_at
      - delivery_start
      - lots
      properties:
        credential:
          type: string
          description: |-
            Bearer credential (`sk-contract-…`). Present when the caller is
            allowed to see it (create / owner GET).
          nullable: true
        delivery_start:
          type: string
          description: When delivery may begin (forwards may be in the future).
        expires_at:
          type: string
          description: When the ticket stops being deliverable.
        id:
          type: string
          description: Contract identifier.
        lots:
          type: array
          items:
            $ref: '#/components/schemas/ContractLot'
          description: Reserved lots (seller ids only — no endpoints).
        quantity:
          type: integer
          format: int64
          description: Original filled size.
          minimum: 0
        remaining:
          type: integer
          format: int64
          description: Tokens still deliverable.
          minimum: 0
    ContractLot:
      type: object
      description: One reserved seller lot on a delivery ticket.
      required:
      - id
      - seller_id
      - quantity
      - remaining
      - price
      properties:
        id:
          type: string
          description: Lot identifier.
        price:
          type: string
          description: Fill price per 1,000 tokens.
        quantity:
          type: integer
          format: int64
          description: Original lot size.
          minimum: 0
        remaining:
          type: integer
          format: int64
          description: Unburned tokens.
          minimum: 0
        seller_id:
          type: string
          description: Bound seller.
    ContractOrderType:
      type: string
      description: How the bid lifts or joins the book.
      enum:
      - take
      - set
      - limit
      - market
    ContractSplit:
      type: object
      description: Optional routing filters on a capacity buy.
      properties:
        privacy:
          type: string
          description: Privacy / data-handling class.
          nullable: true
        region:
          type: string
          description: Jurisdiction / region (`any` or omitted = sweep).
          nullable: true
        soc2:
          type: boolean
          description: Require SOC 2 Type II. Omitted or false accepts any seller.
        venue_pin:
          type: string
          description: Pin a specific venue / model id.
          nullable: true
        zdr:
          type: boolean
          description: Require zero data retention. Omitted or false accepts any seller.
    CreateContractRequest:
      type: object
      description: Body of `POST /v1/contracts`.
      required:
      - instrument
      - quantity
      properties:
        delivery:
          allOf:
          - $ref: '#/components/schemas/DeliverySpec'
          nullable: true
        instrument:
          type: string
          description: Instrument / model id.
        max_price:
          type: string
          description: Limit price per 1,000 tokens. Required except for `market` orders.
          nullable: true
        order:
          $ref: '#/components/schemas/ContractOrderType'
        quantity:
          type: integer
          format: int64
          description: Token quantity to buy.
          minimum: 0
        split:
          allOf:
          - $ref: '#/components/schemas/ContractSplit'
          nullable: true
        time_in_force:
          $ref: '#/components/schemas/TimeInForce'
        ttl_seconds:
          type: integer
          format: int64
          description: Delivery window after fill (spot tickets). Defaults to 86400.
          nullable: true
          minimum: 0
    DeliverySpec:
      oneOf:
      - type: string
        description: Named tenor (`spot`, `1d`, `1m`).
      - type: object
        description: Explicit delivery window.
        required:
        - start
        - end
        properties:
          end:
            $ref: '#/components/schemas/DateTime'
          start:
            $ref: '#/components/schemas/DateTime'
      description: |-
        Forward delivery specification.

        Untagged so the wire accepts `"1d"`, `"1m"`, `"spot"`, or
        `{"start":"…","end":"…"}`.
    ErrorBody:
      type: object
      required:
      - code
      - error
      properties:
        code:
          type: string
          description: Wire error code.
        error:
          type: string
          description: Human-readable detail.
    EstimateConfidence:
      type: string
      description: Confidence in the historical estimate.
      enum:
      - unavailable
      - low
      - medium
      - high
    FillEstimateResponse:
      type: object
      description: Explainable buy-side fill guidance.
      required:
      - model_id
      - quantity
      - immediate_fill_quantity
      - estimated_notional
      - confidence
      - sample_trades
      - data_window_hours
      - disclaimer
      properties:
        confidence:
          $ref: '#/components/schemas/EstimateConfidence'
        data_window_hours:
          type: integer
          format: int64
          description: Historical lookback in hours.
          minimum: 0
        disclaimer:
          type: string
          description: Human-readable non-guarantee.
        estimated_notional:
          type: string
          description: Estimated immediate notional.
        estimated_seconds:
          type: integer
          format: int64
          description: Estimated seconds for the resting remainder.
          nullable: true
          minimum: 0
        immediate_fill_quantity:
          type: integer
          format: int64
          description: Tokens available immediately at the submitted price.
          minimum: 0
        model_id:
          type: string
          description: Instrument.
        quantity:
          type: integer
          format: int64
          description: Requested tokens.
          minimum: 0
        region:
          type: string
          description: Regional filter.
          nullable: true
        sample_trades:
          type: integer
          description: Number of relevant executions in the sample.
          minimum: 0
        suggested_limit_price:
          type: string
          description: Lowest observed candidate expected to clear within the horizon.
          nullable: true
    ListAsksResponse:
      type: object
      description: Active asks owned by a seller.
      required:
      - asks
      properties:
        asks:
          type: array
          items:
            $ref: '#/components/schemas/AskSummary'
          description: Active asks in reverse chronological order.
    ListSellerDeliveriesResponse:
      type: object
      description: Response for `GET /v1/sellers/{id}/deliveries`.
      required:
      - deliveries
      properties:
        deliveries:
          type: array
          items:
            $ref: '#/components/schemas/SellerDelivery'
          description: Outstanding lots, most-recent first.
    ListSellerTradesResponse:
      type: object
      description: Response for `GET /v1/sellers/{id}/trades`.
      required:
      - trades
      properties:
        trades:
          type: array
          items:
            $ref: '#/components/schemas/TradeRecord'
          description: Recent trades, most-recent-first.
    MarketCatalogResponse:
      type: object
      description: Public model-family catalog.
      required:
      - families
      properties:
        families:
          type: array
          items:
            $ref: '#/components/schemas/MarketFamily'
          description: Grouped market models.
    MarketFamily:
      type: object
      description: Models grouped into a family.
      required:
      - id
      - name
      - models
      properties:
        id:
          type: string
          description: Stable family id.
        models:
          type: array
          items:
            $ref: '#/components/schemas/MarketModel'
          description: Family models.
        name:
          type: string
          description: Display label.
    MarketModel:
      type: object
      description: One tradable model in the public catalog.
      required:
      - id
      - display_name
      - provider
      - family
      - context_window
      - modality
      - regions
      - quotes
      properties:
        context_window:
          type: string
          description: Context window label.
        display_name:
          type: string
          description: Human-friendly model name.
        family:
          type: string
          description: Model family used by the navigator.
        id:
          type: string
          description: Stable model/instrument id.
        modality:
          type: string
          description: Primary modality.
        provider:
          type: string
          description: Provider or capability owner.
        quotes:
          type: array
          items:
            $ref: '#/components/schemas/MarketQuote'
          description: Regional live quotes.
        regions:
          type: array
          items:
            type: string
          description: Regions configured by sellers or the catalog.
    MarketQuote:
      type: object
      description: Live summary for one model and region.
      required:
      - region
      - volume_24h
      properties:
        best_ask:
          type: string
          description: Best resting ask in the region.
          nullable: true
        best_bid:
          type: string
          description: Best compatible resting bid.
          nullable: true
        last_price:
          type: string
          description: Most recent execution price.
          nullable: true
        region:
          type: string
          description: Region represented by this quote.
        volume_24h:
          type: integer
          format: int64
          description: Executed tokens during the trailing 24 hours.
          minimum: 0
    RegisterSellerRequest:
      type: object
      description: |-
        Body of `POST /v1/sellers/register`.

        Registration is idempotent by `endpoint_url`: re-registering the same URL
        updates the existing seller record rather than creating a duplicate.
      required:
      - name
      - endpoint_url
      - supported_models
      - api_key
      properties:
        api_key:
          type: string
          description: Seller-chosen API key used to authenticate subsequent requests.
        endpoint_url:
          type: string
          description: Seller inference endpoint URL (the idempotency key).
        name:
          type: string
          description: Human-readable seller name.
        regions:
          type: array
          items:
            type: string
          description: |-
            Delivery regions for this seller's capacity.

            Omit to keep the current regions when re-registering an existing
            `endpoint_url`, or to default a new seller to `["global"]`. Asks are
            rejected for any region not on this list, so a machine-only seller that
            delivers outside `global` must set it here.
          nullable: true
        supported_models:
          type: array
          items:
            type: string
          description: Models this seller can serve.
    RegisterSellerResponse:
      type: object
      description: Response for `POST /v1/sellers/register`.
      required:
      - seller_id
      - name
      - endpoint_url
      - supported_models
      - api_key
      - registered_at
      properties:
        api_key:
          type: string
          description: Seller API key to present in the `X-Seller-API-Key` header.
        endpoint_url:
          type: string
          description: Seller endpoint URL (echoed).
        name:
          type: string
          description: Human-readable seller name (echoed).
        regions:
          type: array
          items:
            type: string
          description: Delivery regions this seller is registered for.
        registered_at:
          type: string
          description: When the record was (re-)registered.
        seller_id:
          type: string
          description: Stable seller identifier (same across idempotent re-registration).
        supported_models:
          type: array
          items:
            type: string
          description: Models this seller can serve (echoed).
    ReportCapacityRequest:
      type: object
      description: |-
        Body of `POST /v1/sellers/{id}/capacity`.

        Informational only — updates the seller's capacity profile for the
        dashboard. It never creates asks or touches the order book. Token counts are
        `u64`, so non-negativity is enforced by the type and zero is a valid report.
      required:
      - model_id
      - available_tokens
      - queued_tokens
      properties:
        available_tokens:
          type: integer
          format: int64
          description: Tokens the seller can serve right now.
          minimum: 0
        model_id:
          type: string
          description: Model / instrument the capacity applies to.
        queued_tokens:
          type: integer
          format: int64
          description: Tokens currently queued / committed.
          minimum: 0
    ReportCapacityResponse:
      type: object
      description: Response for `POST /v1/sellers/{id}/capacity`.
      required:
      - seller_id
      - model_id
      - available_tokens
      - queued_tokens
      - reported_at
      properties:
        available_tokens:
          type: integer
          format: int64
          description: Tokens the seller can serve right now (echoed).
          minimum: 0
        model_id:
          type: string
          description: Model / instrument the capacity applies to.
        queued_tokens:
          type: integer
          format: int64
          description: Tokens currently queued / committed (echoed).
          minimum: 0
        reported_at:
          type: string
          description: When the profile was recorded.
        seller_id:
          type: string
          description: Seller the profile belongs to.
    ReportDecisionsRequest:
      type: object
      description: Body of `POST /v1/sellers/{id}/decisions`.
      required:
      - decisions
      properties:
        decisions:
          type: array
          items:
            $ref: '#/components/schemas/SellerDecision'
          description: Decisions from one Autopilot tick. Must not be empty.
    ReportDecisionsResponse:
      type: object
      description: Response for `POST /v1/sellers/{id}/decisions`.
      required:
      - seller_id
      - recorded
      properties:
        recorded:
          type: integer
          description: How many decisions this request recorded.
          minimum: 0
        seller_id:
          type: string
          description: Seller the decisions were recorded against.
    SellerDecision:
      type: object
      description: |-
        One Autopilot decision, as reported to the Market.

        Autopilot keeps the durable copy in its own local log; this is the
        operator-facing projection the dashboard reads back.
      required:
      - at
      - sold
      - reason
      properties:
        at:
          type: string
          description: When the decision was taken.
        model_id:
          type: string
          description: |-
            Model the decision applies to. `null` for a cluster-wide decision, such
            as a guardrail that stopped every model at once.
          nullable: true
        price_per_million:
          type: string
          description: Price per one million tokens the decision used, when it had one.
          nullable: true
        reason:
          type: string
          description: Operator-facing explanation, at most 500 characters.
        sold:
          type: boolean
          description: Whether capacity was listed for sale as a result.
        tokens:
          type: integer
          format: int64
          description: Tokens the decision covered, when it listed or would have listed.
          nullable: true
          minimum: 0
    SellerDelivery:
      type: object
      description: A seller's outstanding delivery obligation.
      required:
      - contract_id
      - lot_id
      - buyer_id
      - instrument
      - remaining
      - expires_at
      - delivery_start
      properties:
        buyer_id:
          type: string
          description: Buyer.
        contract_id:
          type: string
          description: Contract this lot belongs to.
        delivery_start:
          type: string
          description: When delivery may begin.
        expires_at:
          type: string
          description: When the obligation expires.
        instrument:
          type: string
          description: Instrument.
        lot_id:
          type: string
          description: Lot identifier.
        remaining:
          type: integer
          format: int64
          description: Unburned tokens this seller still owes.
          minimum: 0
    SellerReputationResponse:
      type: object
      description: Response for `GET /v1/sellers/{id}/reputation`.
      required:
      - seller_id
      - history
      properties:
        current:
          allOf:
          - $ref: '#/components/schemas/SellerReputationSnapshot'
          nullable: true
        history:
          type: array
          items:
            $ref: '#/components/schemas/SellerReputationSnapshot'
          description: Recent snapshots, newest first.
        seller_id:
          type: string
          description: Seller path id.
    SellerReputationSnapshot:
      type: object
      description: One public seller-reputation snapshot.
      required:
      - seller_id
      - score
      - fill_rate
      - latency_adherence
      - quality_rate
      - timestamp
      properties:
        fill_rate:
          type: number
          format: double
          description: Successful fills divided by matched trades.
        latency_adherence:
          type: number
          format: double
          description: Trades within SLA divided by observed trades.
        quality_rate:
          type: number
          format: double
          description: Well-formed responses divided by total responses.
        score:
          type: number
          format: double
          description: Weighted score in `[0, 100]`.
        seller_id:
          type: string
          description: Seller this snapshot describes.
        timestamp:
          type: string
          description: When this snapshot was taken.
    SubmitAskRequest:
      type: object
      description: Body of `POST /v1/sellers/{id}/asks`.
      required:
      - model_id
      - price
      - capacity
      properties:
        capacity:
          type: integer
          format: int64
          description: Token capacity offered. Must be strictly positive.
          minimum: 0
        delivery:
          type: string
          description: |-
            Forward tenor (`1d`, `1m`) or omitted for spot. Rests on a
            `{model}::{tenor}` book when set.
          nullable: true
        model_id:
          type: string
          description: Model / instrument this ask offers. Must be in the seller's models.
        price:
          type: string
          description: Ask limit price per 1000 tokens. Must be strictly positive.
        region:
          type: string
          description: Region where this capacity will be delivered.
        ttl_seconds:
          type: integer
          format: int64
          description: Time-to-live in seconds. Defaults to 300 (5 minutes) when omitted.
          nullable: true
          minimum: 0
    SubmitAskResponse:
      type: object
      description: Response for `POST /v1/sellers/{id}/asks`.
      required:
      - ask_id
      - seller_id
      - model_id
      - price
      - capacity
      - remaining
      - created_at
      - expires_at
      properties:
        ask_id:
          type: string
          description: Newly created ask identifier.
        capacity:
          type: integer
          format: int64
          description: Token capacity offered.
          minimum: 0
        created_at:
          type: string
          description: When the ask was accepted.
        expires_at:
          type: string
          description: When the ask will expire if not refreshed or cancelled.
        model_id:
          type: string
          description: Model / instrument offered.
        price:
          type: string
          description: Ask limit price per 1000 tokens.
        region:
          type: string
          description: Delivery region.
        remaining:
          type: integer
          format: int64
          description: Unfilled token quantity (equals `capacity` at creation).
          minimum: 0
        seller_id:
          type: string
          description: Seller that owns the ask.
    TimeInForce:
      type: string
      description: Time-in-force for a capacity order.
      enum:
      - ioc
      - fok
      - gtc
  securitySchemes:
    bearer_buyer:
      type: http
      scheme: bearer
    x_seller_api_key:
      type: apiKey
      in: header
      name: X-Seller-API-Key