> ## 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. # Fetch a signed TWAP oracle update > Returns a signed TWAP price update for the given markets — required before a deposit or withdrawal, since the vault rejects a stake whose TWAP is stale. The response has two modes. On-chain mode (`txHash` present): the oracle already refreshed on-chain and you submit nothing. Signed mode (`markets` + `signature`): prepend `RobinTwapOracle.submitTwap({ markets, signature })` to your deposit/withdraw batch so the refresh and the vault action land atomically. If every returned market has `required: false` and `marketEndedAt: "0"`, the update is a no-op and you can skip `submitTwap`. This is an action, not a data read: it asks Robin's operator-keyed signer for a fresh price (which it may itself submit on-chain). conditionIds are normalized to lowercase. ## OpenAPI ````yaml /openapi/v1.yaml post /twap 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: /twap: post: tags: - TWAP summary: Fetch a signed TWAP oracle update description: > Returns a signed TWAP price update for the given markets — required before a deposit or withdrawal, since the vault rejects a stake whose TWAP is stale. The response has two modes. On-chain mode (`txHash` present): the oracle already refreshed on-chain and you submit nothing. Signed mode (`markets` + `signature`): prepend `RobinTwapOracle.submitTwap({ markets, signature })` to your deposit/withdraw batch so the refresh and the vault action land atomically. If every returned market has `required: false` and `marketEndedAt: "0"`, the update is a no-op and you can skip `submitTwap`. This is an action, not a data read: it asks Robin's operator-keyed signer for a fresh price (which it may itself submit on-chain). conditionIds are normalized to lowercase. operationId: getTwapUpdate requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TwapRequest' responses: '200': description: A TWAP update — either on-chain mode or a signed payload to submit. content: application/json: schema: $ref: '#/components/schemas/TwapUpdate' '400': $ref: '#/components/responses/BadRequest' '429': $ref: '#/components/responses/TooManyRequests' '502': $ref: '#/components/responses/TwapUnavailable' '504': $ref: '#/components/responses/TwapTimeout' components: schemas: TwapRequest: type: object required: - conditionIds properties: conditionIds: type: array minItems: 1 maxItems: 25 description: >- Unique conditionIds for every market in your upcoming deposit/withdraw batch. items: $ref: '#/components/schemas/ConditionId' TwapUpdate: description: > A TWAP update in one of two modes, discriminated by `txHash` (on-chain mode) vs `markets` + `signature` (signed mode). oneOf: - $ref: '#/components/schemas/TwapSignedPayload' - $ref: '#/components/schemas/TwapOnchain' ConditionId: type: string description: 32-byte Polymarket condition id, hex. pattern: ^0x[a-fA-F0-9]{64}$ example: '0xce9a5fa30fe74e323b4a8f15afbb0b7a41a537aa880779ddf7dee22223b2f34a' TwapSignedPayload: type: object description: > Signed mode. Prepend `RobinTwapOracle.submitTwap({ markets, signature })` to your deposit or withdraw batch. Coerce every numeric string to a bigint first. required: - markets - signature properties: markets: type: array items: $ref: '#/components/schemas/TwapDataEntry' signature: type: string pattern: ^0x[a-fA-F0-9]+$ description: >- ECDSA (EIP-712) signature over the batch of TwapData, produced by Robin's operator signer. example: '0xc0ffee00' failed: type: array description: >- Markets the signer could not price (e.g. an unknown conditionId). Usually empty. items: type: object properties: conditionId: type: string error: type: string TwapOnchain: type: object description: > On-chain mode. The oracle already refreshed the TWAP on-chain (`txHash`), so there is nothing to submit — send your deposit/withdraw batch without a `submitTwap` call. required: - txHash properties: txHash: type: - string - 'null' description: >- The on-chain TWAP submission tx hash, or null if the oracle decided no update was needed. example: '0x9f3c00' initialized: type: integer description: >- Count of markets the oracle initialized on-chain as part of this call. skipped: type: boolean reason: type: string 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 TwapDataEntry: type: object description: >- One market's signed TWAP data; maps 1:1 to the on-chain `TwapData` struct passed to `submitTwap`. required: - required - conditionId - startTimestamp - endTimestamp - twapPriceYes - marketEndedAt - marketEndYesPrice properties: required: type: boolean description: >- Whether the oracle considers this market's on-chain TWAP stale and in need of this update. conditionId: $ref: '#/components/schemas/ConditionId' startTimestamp: type: string pattern: ^[0-9]+$ description: >- TWAP window start, unix seconds (string). Coerce to a bigint before submitting on-chain. example: '1718000000' endTimestamp: type: string pattern: ^[0-9]+$ description: TWAP window end, unix seconds (string). example: '1718086400' twapPriceYes: type: string pattern: ^[0-9]+$ description: >- Time-weighted YES price, scaled by PRICE_SCALE (1e6) — "540000" = 54.00%. Range 0–1000000. example: '540000' marketEndedAt: type: string pattern: ^[0-9]+$ description: Unix seconds the market finalized, or "0" if still live. example: '0' marketEndYesPrice: type: string pattern: ^[0-9]+$ description: >- Final YES price at resolution (PRICE_SCALE, 1e6), or "0" if still live. example: '0' responses: BadRequest: description: Invalid parameters (e.g. missing `wallet`, or a non-integer amount). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: bad_request message: wallet is required TooManyRequests: description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limited message: Too many requests TwapUnavailable: description: >- The upstream TWAP signer returned an error or is unreachable. Retry with backoff. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: twap_unavailable message: TWAP service unavailable TwapTimeout: description: The upstream TWAP signer did not respond in time. Retry with backoff. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: twap_timeout message: TWAP service timeout ````