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

# Integration API overview

> The read-only /api/v1 surface: base URL, conventions, the index-then-read flow, and the APY breakdown — endpoint schemas live in the API Reference.

The Robin Integration API is a read-only HTTP surface for reading live APY, personalized deposit quotes, and a wallet's vault positions. It never moves funds — every data read is pure, and the two `POST` helpers only index market metadata (`POST /markets`) and return a signed TWAP update you submit before staking (`POST /twap`). To move funds, you submit transactions to the on-chain vault (see [Deposits](/developers/deposits)).

## Base URL & access

The API is served under a single base URL:

```text theme={null}
https://app.robin.markets/api/v1
```

* **No auth.** Every endpoint is open — no API key, no signing.
* **Open CORS.** Calls work directly from the browser; no proxy required.
* **Per-IP rate limit.** Exceeding it returns HTTP `429`. Back off and retry.
* **Preflight.** Every path answers `OPTIONS` for CORS preflight.

<Note>
  There is no per-user authentication. The API personalizes reads by the
  `wallet` query parameter. You tell it which wallet to read, and it returns
  that wallet's data.
</Note>

## Conventions

These conventions apply to every endpoint. The full request/response schemas for each are in the **API Reference**.

| Convention    | Rule                                                                                                      |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| Amounts       | 6-decimal integer **strings** — `"1500000"` means `1.5`. Never floats.                                    |
| APY values    | Plain **numbers in percent** — `6` means `6.00%`.                                                         |
| `conditionId` | Polymarket condition id as a `bytes32` hex string; the primary key across contracts, API, and Polymarket. |
| `wallet`      | The user's **resolved Robin staking wallet**, NOT their EOA. See [Wallets](/developers/wallets).          |
| Errors        | Envelope: `{ "error": { "code", "message" } }`.                                                           |

<Warning>
  Always pass the resolved DepositWallet or legacy Safe proxy as `wallet` —
  never the connected EOA. The EOA holds no shares or positions, so reads keyed
  on it return empty. See [Wallets](/developers/wallets) for resolution.
</Warning>

## Indexing: read-only reads + one write

<Steps>
  <Step title="Read the market">
    Call a read endpoint (e.g. `GET /markets/{conditionId}`).
  </Step>

  <Step title="Handle not-indexed-yet">
    If you get a `404`, or the id lands in `notFound`, the market simply has not been indexed.
  </Step>

  <Step title="Index from Polymarket">
    `POST /markets` with the missing `conditionId`s. Robin pulls them from Polymarket and returns the `{ markets, notFound }` payload — already containing the freshly indexed market data, so you can use it immediately.
  </Step>
</Steps>

<Tip>
  A `conditionId` still in `notFound` after `POST /markets` does not exist on
  Polymarket. Treat that as a hard not-found.
</Tip>

## The APY breakdown

Both market and quote responses expose the bonus programme APY as a structured breakdown rather than a single opaque number. The split mirrors the on-/off-chain boundary: the vault pays only organic yield on-chain via dual-index accounting, while guarantee, matching, and points are an off-chain programme Robin computes at withdrawal and pays in a separate USDC transaction.

<Note>
  * **Market headlines** give per-side `base + matching`, plus a **min–max APY range** and a `maxPointsBoost` ceiling — the spread reflects how much organic yield, matching, and points a deposit could earn depending on size and the pool's balance.
  * **Personalized quotes** return `projectedApy { total, base, matching, points }` for the supplied `wallet` and amounts — the realistic APY that wallet would lock in.
  * **Points are abstracted away.** You never handle points directly; they appear only as the `points` line in the breakdown and folded into `total`.
</Note>

See [Conventions](/developers/conventions) for the full APY formula and how `base`, `matching`, and `points` are computed.

## Next steps

<CardGroup cols={3}>
  <Card title="Quickstart" icon="rocket" href="/developers/quickstart">
    Resolve a wallet, read a market, and submit your first deposit.
  </Card>

  <Card title="Conventions" icon="ruler" href="/developers/conventions">
    Units, scales, ids, and the full APY formula.
  </Card>

  <Card title="Deposits" icon="arrow-down-to-bracket" href="/developers/deposits">
    The on-chain pull and push deposit flows.
  </Card>
</CardGroup>