> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convallax.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit Quote

> Submit or update a draft quote for an open quote request. Returns a server-generated quoteId. Authenticated via the X-API-Key header.

Submit or update a draft quote for an open quote request. This is channel 2 of the [three-channel maker transport](/guides/market-maker) — you receive requests over the [SSE stream](/api-reference/market-maker/quote-stream) and reply here over REST.

Only the **latest quote per maker per request** is kept — re-POST for the same `requestId` to update your quote at any time while the request is open. The response returns a **server-generated** `quoteId` that is stable across updates for the same maker + request; you use it to [confirm](/api-reference/market-maker/confirm-quote) if you win.

<Note>
  You do not include your `makerId` — the relay derives it from your authenticated API key. The `quote.maker` wallet **is** required and is written into the on-chain order.
</Note>

## Quote validation

A quote must pass these checks to be eligible for winner selection:

| Check         | Requirement                                |
| ------------- | ------------------------------------------ |
| `requestId`   | Must match an active (open) quote request  |
| `quote.side`  | Must match the taker's requested side      |
| `quote.size`  | ≥ 50% of requested size                    |
| `quote.price` | Must be in `(0, 1)`                        |
| No-arbitrage  | Price ≤ maximum payoff for the option type |

## Maker solvency check

The relay verifies **on-chain** that your `quote.maker` wallet can actually fund the prospective fill before the quote is accepted, and again at commit time:

* **Selling options (taker buys):** your wallet must hold — and have approved to **ConvallaxCore** — enough USDC for the max-loss collateral of the fill.
* **Buying options (taker writes):** your wallet must hold — and have approved to the **Settlement contract** — enough USDC for the premium.

If the check fails, the submission is rejected with **HTTP 422** and an error of `maker_insufficient_balance` or `maker_insufficient_allowance`; the `detail` field states the wallet, amounts, and (for allowance failures) the spender address to approve. Balance/allowance reads are cached for a few seconds, so a top-up may take a moment to be recognised.


## OpenAPI

````yaml api-reference/openapi.json POST /v1/mm/quotes
openapi: 3.1.0
info:
  title: Convallax RFQ API
  version: 3.0.0
  description: >-
    REST surface for the Convallax options protocol — a non-custodial
    request-for-quote marketplace for European calls and puts on Polymarket YES
    outcomes, settled on Polygon.


    **Wire format**: JSON. Successful responses include `"success": true`;
    failures return `{ "success": false, "error": "..." }`.


    **Authentication**: Takers (traders) need no API key — authorization happens
    on-chain at `fill()`. Market makers authenticate with a per-MM API key sent
    as `X-API-Key` (or `?apiKey=`).


    **Streaming**: Quote-request and live-pricing streams use Server-Sent Events
    and the post-trade channel uses WebSocket; those are documented in the
    guides and are not part of this request/response reference.
servers:
  - url: https://api.convallax.com
    description: Production
security: []
tags:
  - name: Series
    description: Browse registered option series available for trading.
  - name: Trading
    description: Open quote requests, read live quotes, and commit to the best price.
  - name: Market Maker
    description: >-
      Submit quotes and confirmation signatures. Authenticated with a per-MM API
      key.
  - name: Settlement
    description: Compute TWAP resolution prices and sign settlement attestations.
  - name: Testnet
    description: Polygon Amoy testnet USDC faucet.
  - name: User
    description: >-
      Account profile and self-serve API keys. Authenticated with a Privy access
      token.
paths:
  /v1/mm/quotes:
    post:
      tags:
        - Market Maker
      summary: Submit Quote
      description: >-
        Submit or update a draft quote for an open quote request. Only the
        latest quote per maker per request is kept — re-POST to update. Returns
        a server-generated `quoteId` (stable across updates) used to confirm if
        you win.
      operationId: submitQuote
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitQuoteInput'
      responses:
        '200':
          description: Quote accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitQuoteResponse'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '409':
          $ref: '#/components/responses/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    SubmitQuoteInput:
      type: object
      required:
        - requestId
        - quote
      properties:
        requestId:
          type: string
          description: The requestId from the quote_request event you are quoting.
          example: req-789
        quote:
          $ref: '#/components/schemas/QuoteSubmission'
    SubmitQuoteResponse:
      type: object
      properties:
        success:
          type: boolean
          const: true
        quoteId:
          type: string
          description: Server-generated quote ID, stable across updates.
          example: 8f3c2b1a-1d2e-4c3b-9a8f-6e5d4c3b2a1f
    QuoteSubmission:
      type: object
      required:
        - maker
        - side
        - price
        - size
      properties:
        maker:
          type: string
          description: >-
            Your own wallet address. Becomes Order.maker; your signature must
            recover to it.
          example: '0x1234000000000000000000000000000000abcd'
        side:
          type: string
          enum:
            - buy
            - sell
          description: Must match the taker's requested side.
          example: buy
        price:
          type: number
          description: >-
            Price per ONE option, in (0, 1). Must be <= max payoff (1 - K for
            calls, K for puts).
          example: 0.18
        size:
          type: number
          description: >-
            On a buy: the max whole options you'll write at this price (>= 1);
            the actual fill is min(floor(budgetUsd / price), size). On a sell:
            the contracts you'll take (>= 50% of the requested size).
          example: 100
        expires_in_ms:
          type: number
          example: 5000
    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          const: false
        error:
          type: string
          description: Human-readable error message.
          example: Quote request not found or expired
  responses:
    Error:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Maker API key (env-issued or self-serve from the dashboard). Maps to a
        stable `makerId`.
      x-default: mk_live_alpha_xxx

````