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

# Robin Markets developer documentation

> Integrate Robin Markets to show live staking APY and let your users stake their Polymarket positions for yield.

Robin Markets turns idle Polymarket YES/NO conditional tokens into yield. Users stake the positions they already hold; the vault pairs and merges them to USDC, supplies that USDC to an ERC-4626 yield strategy, and issues ERC-1155 shares. If your interface already has Polymarket market data and a connected wallet, you can add a "stake for yield" option on top of it.

Everything runs on **Polygon (chainId 137)**. All token and USDC amounts are 6-decimal fixed-point integers.

<Note>
  Robin reads from data you already have. The on-chain `conditionId` (a
  `bytes32` Polymarket condition id) is the primary key that links the
  contracts, Robin's API, and Polymarket — so a market you already render by
  `conditionId` maps directly onto Robin.
</Note>

## Two integration surfaces

A complete integration uses two distinct surfaces. One is read-only and tells you what to **show**; the other is the on-chain vault that **moves** funds. Keep them separate in your mental model.

<CardGroup cols={2}>
  <Card title="Integration API (read-only)" icon="chart-line" href="/developers/api-overview">
    Live per-market staking APY, personalized stake quotes, and a wallet's existing positions with accrued yield. This is what you render in your UI.
  </Card>

  <Card title="On-chain staking" icon="cube" href="/developers/deposits">
    Deposit and withdraw against the Robin contracts. This is how users actually move their tokens into and out of the vault.
  </Card>
</CardGroup>

### What you show: the Integration API

The Integration API (`/api/v1`) is a public, read-only HTTP API at `https://app.robin.markets/api/v1`. It has no auth and open CORS, so you can call it directly from the browser. Use it to surface, for the markets and wallets you already display:

* A market's **live staking APY** (`GET /markets/{conditionId}`), broken down into base, matching, and points.
* A **personalized projected APY** for a stake a user is about to make (`GET /markets/{conditionId}/quote?wallet=…`).
* A wallet's **existing Robin positions** with shares, value, and an accrued-yield breakdown (`GET /positions?wallet=…`).

<Warning>
  The Integration API never moves funds and never signs anything. To deposit or
  withdraw, a user signs an on-chain transaction against the contracts.
</Warning>

### How users move funds: on-chain staking

Deposits and withdrawals are on-chain calls against `RobinStakingVault` (`batchDeposit` / `batchWithdraw`), preceded by a fresh-TWAP refresh on `RobinTwapOracle`. The vault is a UUPS-upgradeable singleton and issues one ERC-1155 share token per market per side (Side: `YES=0`, `NO=1`).

The on-chain vault pays only the **organic** yield, accounted via a dual-index scheme (`lossIndex` + `yieldPerShare`). Robin's three bonus streams — the 6% yield guarantee, the +1% matching bonus, and the +1% points boost — are an **off-chain programme**: they are computed at withdrawal and paid in a separate USDC transaction from Robin's operator wallet, not by the `batchWithdraw` call.

<Info>
  A user's Polymarket tokens and shares live in their **Polymarket on-chain
  account**, not their EOA. There are two kinds — a newer **DepositWallet** or a
  legacy **Gnosis Safe proxy** — and the transport differs between them. Resolve
  the wallet once and key every per-user read and write on it. See
  [Architecture](/developers/architecture) for the resolution rules and
  transports.
</Info>

## Start here

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/developers/quickstart">
    Resolve a wallet, show APY from the Integration API, and submit your first deposit end to end.
  </Card>

  <Card title="API overview" icon="plug" href="/developers/api-overview">
    The `/api/v1` conventions, the index-then-read flow, and the APY breakdown
    shape.
  </Card>

  <Card title="Deposits & withdrawals" icon="arrow-right-arrow-left" href="/developers/deposits">
    Pull and push deposit paths, `batchWithdraw`, sorting rules, and error modes.
  </Card>

  <Card title="Architecture" icon="sitemap" href="/developers/architecture">
    Contracts, the dual-wallet model, TWAP refresh, and how yield is split.
  </Card>
</CardGroup>

## Conventions

Before you write any code, read the shared [conventions](/developers/conventions): 6-decimal amounts (as integer strings over the API), APY values as plain percent numbers (`6` = 6.00%), `conditionId` as the cross-system primary key, and `wallet` always meaning the user's resolved Robin staking wallet rather than the EOA.

For the full contract address table and governance details, see the [contracts overview](/contracts/overview).

## Reference code & schemas

A runnable TypeScript example (using viem) covers wallet resolution, pull and push deposits, withdrawal, TWAP refresh, and an `/api/v1` client — reference the [robin-markets-integration](https://github.com/robin-markets/frontend-integration-example) example repo for working code rather than copying it wholesale.

These developer guides cover concepts and flows. The per-endpoint request and response schemas for the Integration API are auto-generated and live under [API Reference](/api-reference) in the sidebar.

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/developers/quickstart">
    Wire up APY display and a first deposit in one pass.
  </Card>

  <Card title="API overview" icon="plug" href="/developers/api-overview">
    Learn the `/api/v1` conventions and the APY breakdown.
  </Card>
</CardGroup>