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

# Market staking APY headline

> Address-agnostic per-side APY headline for one market: socialized base + matching bonus. Points are not personalized here (no wallet) — `apy.maxPointsBoost` is the "up to" ceiling; use the `/quote` endpoint for a wallet's actual points boost.




## OpenAPI

````yaml /openapi/v1.yaml get /markets/{conditionId}
openapi: 3.1.0
info:
  title: Robin Markets Integration API
  version: 1.0.0
  description: >
    Public API for surfacing Robin staking inside a third-party frontend. You
    already have the Polymarket market data; this returns **what Robin computes
    on top**: a market's live staking APY, a personalized projected APY for a
    stake a user is about to make, and the state of a wallet's existing
    positions (shares, value, accrued-yield breakdown, live APY).


    Data endpoints are **read-only**. Two `POST` helpers cover actions a read
    can't: `POST /markets` indexes a market from Polymarket, and `POST /twap`
    returns a signed oracle update you must submit on-chain before depositing or
    withdrawing.


    ### Conventions

    - **Token / USD amounts** are 6-decimal integer strings (`"1500000"` = 1.5).
    Both outcome tokens
      and USDC use 6 decimals. Divide by `1e6` to display.

    - **APY values** are plain numbers in **percent** (`6.0` means 6.00% APY).

    - **`conditionId`** is the Polymarket condition id (bytes32 hex).

    - **`wallet`** is the user's resolved Robin staking wallet (a Polymarket
    DepositWallet or Gnosis
      Safe proxy), **not** the user's EOA.

    - Outcome / side values are `"yes"` / `"no"` (and `"both"` for a
    fully-resolved market).


    ### Auth, CORS & rate limiting

    No authentication. CORS is wide-open (`Access-Control-Allow-Origin: *`), so
    endpoints can be called directly from the browser; each path also answers
    `OPTIONS` preflight. Requests are rate-limited per IP (shared global budget)
    — back off on `429`.


    ### The APY formula

    Every APY is built from three layers: `total = max(nativeApy ×
    matchedFraction, guaranteeFloor) + matchingBonus + pointsBoost`. Base =
    socialized native yield, floored at the guarantee; matching = +1% for the
    pool-balancing (minority) side, scaled by the matchable portion; points = a
    personalized Robin Points boost (never handled directly — it appears as the
    `points` line and is folded into totals).
  license:
    name: See repository
servers:
  - url: https://app.robin.markets/api/v1
    description: Production
security: []
tags:
  - name: Markets
    description: Market-level staking APY and per-wallet quotes/positions.
  - name: Positions
    description: A wallet's existing Robin positions.
  - name: TWAP
    description: Signed oracle price updates required before depositing or withdrawing.
  - name: Capacity
    description: >-
      Two-tier vault deposit capacity (internal guard + external ERC-4626
      headroom).
  - name: Meta
    description: Static integration metadata.
paths:
  /markets/{conditionId}:
    get:
      tags:
        - Markets
      summary: Market staking APY headline
      description: >
        Address-agnostic per-side APY headline for one market: socialized base +
        matching bonus. Points are not personalized here (no wallet) —
        `apy.maxPointsBoost` is the "up to" ceiling; use the `/quote` endpoint
        for a wallet's actual points boost.
      operationId: getMarket
      parameters:
        - $ref: '#/components/parameters/ConditionIdPath'
      responses:
        '200':
          description: Market found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketApy'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  parameters:
    ConditionIdPath:
      name: conditionId
      in: path
      required: true
      description: Polymarket condition id (bytes32 hex).
      schema:
        $ref: '#/components/schemas/ConditionId'
  schemas:
    MarketApy:
      type: object
      required:
        - conditionId
        - question
        - slug
        - image
        - endDate
        - outcomes
        - resolved
        - winningOutcome
        - tvl
        - pool
        - apy
        - vault
      properties:
        conditionId:
          $ref: '#/components/schemas/ConditionId'
        question:
          type: string
        slug:
          type: string
        image:
          type:
            - string
            - 'null'
        endDate:
          type:
            - integer
            - 'null'
          format: int64
          description: Market end date, milliseconds since epoch.
        outcomes:
          type: array
          items:
            type: string
          example:
            - 'Yes'
            - 'No'
        resolved:
          type: boolean
        winningOutcome:
          type:
            - string
            - 'null'
          enum:
            - 'yes'
            - 'no'
            - both
            - null
        tvl:
          $ref: '#/components/schemas/Amount6'
        pool:
          $ref: '#/components/schemas/Pool'
        apy:
          $ref: '#/components/schemas/MarketApyBreakdown'
        vault:
          $ref: '#/components/schemas/Address'
      example:
        conditionId: '0xce9a5fa30fe74e323b4a8f15afbb0b7a41a537aa880779ddf7dee22223b2f34a'
        question: Will Donald Trump win the 2028 US Presidential Election?
        slug: will-donald-trump-win-the-2028-us-presidential-election
        image: https://polymarket-upload.s3.us-east-2.amazonaws.com/...png
        endDate: 1857168000000
        outcomes:
          - 'Yes'
          - 'No'
        resolved: false
        winningOutcome: null
        tvl: '2100000'
        pool:
          matchedFraction: 0
          unmatchedYes: '70000000'
          unmatchedNo: '0'
          minoritySide: 'no'
        apy:
          base: 6
          guaranteeFloor: 6
          matching:
            'yes': 0
            'no': 1
          'yes': 6
          'no': 7
          min: 6
          max: 8
          maxPointsBoost: 1
          nativeApy: 3.48
        vault: '0xcb7444981296d08da7161b75378e3773dbf5d806'
    ConditionId:
      type: string
      description: 32-byte Polymarket condition id, hex.
      pattern: ^0x[a-fA-F0-9]{64}$
      example: '0xce9a5fa30fe74e323b4a8f15afbb0b7a41a537aa880779ddf7dee22223b2f34a'
    Amount6:
      type: string
      description: >-
        A non-negative integer in 6-decimal fixed-point micro-units (e.g.
        "1500000" = 1.5).
      pattern: ^[0-9]+$
      example: '1500000'
    Pool:
      type: object
      description: Current YES/NO pool balance state.
      required:
        - matchedFraction
        - unmatchedYes
        - unmatchedNo
        - minoritySide
      properties:
        matchedFraction:
          type: number
          format: double
          description: >-
            Fraction (0–1) of TVL matched into yield, the multiplier behind
            `apy.base`.
          example: 0.82
        unmatchedYes:
          $ref: '#/components/schemas/Amount6'
        unmatchedNo:
          $ref: '#/components/schemas/Amount6'
        minoritySide:
          type:
            - string
            - 'null'
          enum:
            - 'yes'
            - 'no'
            - null
          description: >-
            The side currently earning the matching bonus, or null when
            balanced.
    MarketApyBreakdown:
      type: object
      required:
        - base
        - guaranteeFloor
        - matching
        - 'yes'
        - 'no'
        - min
        - max
        - maxPointsBoost
        - nativeApy
      properties:
        base:
          allOf:
            - $ref: '#/components/schemas/Apy'
          description: >-
            Socialized native yield (× matched fraction), guarantee-floored.
            Same both sides.
        guaranteeFloor:
          allOf:
            - $ref: '#/components/schemas/Apy'
          description: The guarantee floor baked into `base`.
        matching:
          type: object
          required:
            - 'yes'
            - 'no'
          properties:
            'yes':
              $ref: '#/components/schemas/Apy'
            'no':
              $ref: '#/components/schemas/Apy'
        'yes':
          allOf:
            - $ref: '#/components/schemas/Apy'
          description: base + matching for YES (points NOT included).
        'no':
          allOf:
            - $ref: '#/components/schemas/Apy'
          description: base + matching for NO (points NOT included).
        min:
          allOf:
            - $ref: '#/components/schemas/Apy'
          description: >-
            Lowest a new staker could earn now (= base; majority side, no
            points).
        max:
          allOf:
            - $ref: '#/components/schemas/Apy'
          description: >-
            Highest a new staker could earn now (base + best-side matching +
            full points boost).
        maxPointsBoost:
          allOf:
            - $ref: '#/components/schemas/Apy'
          description: '"Up to" Robin Points ceiling (not personalized).'
        nativeApy:
          type:
            - number
            - 'null'
          format: double
          description: Raw netAPY in percent, or null if temporarily unavailable.
          example: 5.1
    Address:
      type: string
      description: 20-byte EVM address, lowercase hex.
      pattern: ^0x[a-fA-F0-9]{40}$
      example: '0xcb7444981296d08da7161b75378e3773dbf5d806'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - bad_request
                - not_found
                - rate_limited
                - internal
                - twap_unavailable
                - twap_timeout
                - capacity_unavailable
            message:
              type: string
    Apy:
      type: number
      format: double
      description: APY in percent (6.0 = 6.00%).
      example: 6.4
  responses:
    NotFound:
      description: >-
        Market not indexed on Robin — POST /markets to index it from Polymarket
        first.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: not_found
              message: Market not found
    TooManyRequests:
      description: Rate limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
              message: Too many requests

````