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.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.Integration API (read-only)
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.
On-chain staking
Deposit and withdraw against the Robin contracts. This is how users actually move their tokens into and out of the vault.
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=…).
How users move funds: on-chain staking
Deposits and withdrawals are on-chain calls againstRobinStakingVault (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.
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 for the resolution rules and
transports.
Start here
Quickstart
Resolve a wallet, show APY from the Integration API, and submit your first deposit end to end.
API overview
The
/api/v1 conventions, the index-then-read flow, and the APY breakdown
shape.Deposits & withdrawals
Pull and push deposit paths,
batchWithdraw, sorting rules, and error modes.Architecture
Contracts, the dual-wallet model, TWAP refresh, and how yield is split.
Conventions
Before you write any code, read the shared 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.
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 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 in the sidebar.
Next steps
Quickstart
Wire up APY display and a first deposit in one pass.
API overview
Learn the
/api/v1 conventions and the APY breakdown.