Units, IDs & APY

Robin’s contracts and Integration API share a small set of conventions for amounts, scales, identifiers, and the way Robin’s APY is computed. Get these right once and the rest of the integration follows.

Amounts & scales

All outcome tokens and USDC are 6-decimal fixed-point integers. Prices and vault indices use their own fixed scales.

Constant	Value	Applies to
`UNDERLYING_DECIMALS`	`6`	Outcome-token amounts and USDC. `"1500000"` = 1.5
`PRICE_SCALE`	`1e6`	Prices and TWAP values. `1e6` = 100% (a YES price of `500000` = 0.50)
`INDEX_SCALE`	`1e18`	Vault indices (`lossIndex`, `yieldPerShare`)

The Integration API follows the same numeric model with two presentation rules:

Amounts are returned as 6-decimal integer strings — "1500000" means 1.5. Parse with a bigint, not a float.
APY values are returned as plain numbers in percent — 6 means 6.00%, not 0.06.

{
  // 6-decimal amount string
  "yesAmount": "1500000", // = 1.5 outcome tokens
  // APY number in percent
  "apy": 6, // = 6.00%
}

conditionId

A conditionId is the Polymarket condition id: a bytes32 hex value. It is the primary key that links Robin’s contracts, the Integration API, and Polymarket itself. Use the same conditionId everywhere — on-chain calls, Lens reads, API requests, and Polymarket’s data APIs all key on it. See the API overview for indexing and reading a market by its conditionId.

Side enum

Every market has two sides, encoded as a Solidity enum:

Side	Value
`YES`	`0`
`NO`	`1`

enum Side { YES, NO } // YES = 0, NO = 1

The vault issues one ERC-1155 share token per market per side, so each conditionId has a distinct YES share id and NO share id.

The APY formula

Robin computes a total APY on top of the organic yield. It combines a guarantee-floored base with two bonuses.

total = max(rawOnChainApy × matchedFraction, 6% guarantee)  // base
        + 1%   // matching (minority side only)
        + 1%   // points (× coverage)

Base. The native yield is socialized across the market by TVL — only the matched fraction of the pool actually earns it. That base is then floored at the 6% yield guarantee, so a deposit never accrues less than the guaranteed rate for its staked duration. Matching (+1%). The minority (pool-balancing) side earns an extra 1% APY, scaled by the matchable portion of a deposit — only the tokens that move the pool toward balance qualify. The matching bonus is locked at deposit time and accrues for the life of those shares regardless of later pool state. Points (+1%). Points add up to 1% APY, personalized per wallet by a coverage factor:

coverage     = min(points, stakeInDollars) / stake
pointsBoost  = 1% × coverage

Each point boosts up to $1 of stake. When a wallet holds fewer points than its staked value, only the covered portion earns the boost.

Organic yield vs. the bonus programme

Two payouts, two systems. The organic yield is paid on-chain by the vault via dual-index accounting (lossIndex + yieldPerShare) and settles as part of batchWithdraw. The guarantee, matching, and points bonuses are an off-chain programme run by Robin: they are computed at withdrawal and paid in a single, separate USDC transaction from Robin’s operator wallet — not by the withdraw call.Integrators never handle points directly. The API folds them into the APY breakdown (base / matching / points), so they appear as a line in the response and are summed into the total.

This split is why a withdrawal returns the underlying outcome tokens plus the organic USDC yield, while the bonus USDC arrives afterward in its own transfer. See Withdrawals for the on-chain side and the API overview for the APY breakdown shape.

Amounts & scales

conditionId

Side enum

The APY formula

Organic yield vs. the bonus programme

Next steps

API overview

Architecture

​Amounts & scales

​conditionId

​Side enum

​The APY formula

​Organic yield vs. the bonus programme

​Next steps

API overview

Architecture

Amounts & scales

conditionId

Side enum

The APY formula

Organic yield vs. the bonus programme

Next steps