> ## 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.

# Prepare Settlement

> Compute the TWAP resolution price for an expired option series and return a signed EIP-712 settlement attestation.

Compute the resolution price for an expired option series and return a signed settlement attestation. The relay reads on-chain series metadata and resolves the price via a tiered waterfall: if the underlying Polymarket market has closed it uses the settled YES outcome, otherwise it computes a time-weighted average (TWAP) of the YES token's price from the Polymarket CLOB `prices-history` endpoint over the 30-minute window ending at expiry, then signs an EIP-712 `SettlementAttestation` with the resolution signer's key. If that window has no price data, the relay declines to sign and the series is escalated to manual review.

The returned attestation can be relayed on-chain by anyone via [`settleWithAttestation()`](/api-reference/contracts/settle) on `ConvallaxCore`.

<Warning>
  This endpoint should be restricted in production. It is intended for cron jobs and internal automation, not public access.
</Warning>


## OpenAPI

````yaml api-reference/openapi.json POST /settlement/prepare
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:
  /settlement/prepare:
    post:
      tags:
        - Settlement
      summary: Prepare Settlement Attestation
      description: >-
        For an expired series, resolve the price via a tiered waterfall (settled
        Polymarket outcome if the market has closed, otherwise a time-weighted
        average price of the YES token over the 30-minute window ending at
        expiry, sourced from the Polymarket CLOB `prices-history` endpoint), and
        return a signed EIP-712 `SettlementAttestation` that anyone can submit
        to `ConvallaxCore.settle()`. If the TWAP window has no price data, the
        series is escalated to manual review and no attestation is returned.
      operationId: prepareSettlement
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettlementInput'
      responses:
        '200':
          description: Signed settlement attestation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementResponse'
        '400':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
components:
  schemas:
    SettlementInput:
      type: object
      required:
        - seriesId
      properties:
        seriesId:
          type: string
          description: Series ID (uint256) as a decimal or hex string.
          example: '98765432109876543210'
    SettlementResponse:
      type: object
      properties:
        success:
          type: boolean
          const: true
        seriesId:
          type: string
          example: '98765432109876543210'
        resolutionBps:
          type: integer
          description: Settlement price in basis points of $1 (0–100).
          example: 73
        validUntil:
          type: integer
          description: Attestation expiry (Unix seconds).
          example: 1735690500
        signature:
          type: string
          description: EIP-712 SettlementAttestation signature by the resolution signer.
          example: 0xabcdef...
        meta:
          $ref: '#/components/schemas/SettlementMeta'
    SettlementMeta:
      type: object
      properties:
        method:
          type: string
          description: Resolution tier that produced the price.
          enum:
            - official
            - twap
          example: twap
        twap:
          type: number
          description: Time-weighted average YES price in [0, 1] (when method is twap).
          example: 0.732145
        pointCount:
          type: integer
          description: Number of in-window price samples used for the TWAP.
          example: 28
        yesPrice:
          type: number
          description: Settled YES token price in [0, 1] (when method is official).
          example: 1
        windowStart:
          type: integer
          description: TWAP window start (Unix seconds).
          example: 1735687800
        windowEnd:
          type: integer
          description: TWAP window end = expiry (Unix seconds).
          example: 1735689600
    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'

````