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

# Units, IDs & APY

> The shared conventions across Robin's contracts and API: 6-decimal amounts, scales, conditionId, the Side enum, and the APY formula.

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

```jsonc theme={null}
{
  // 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](/developers/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`   |

```solidity theme={null}
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.

```text theme={null}
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:

```text theme={null}
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

<Note>
  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.
</Note>

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](/developers/withdrawals) for the on-chain side and the [API overview](/developers/api-overview) for the APY breakdown shape.

## Next steps

<CardGroup cols={2}>
  <Card title="API overview" icon="plug" href="/developers/api-overview">
    Base URL, conventions, the index-then-read flow, and the APY breakdown.
  </Card>

  <Card title="Architecture" icon="sitemap" href="/developers/architecture">
    How the vault, oracle, Lens, and off-chain programme fit together.
  </Card>
</CardGroup>