> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibechain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# retard.market API Introduction

> Read the Robinhood Chain V9 market feed, quotes, portfolios, points, media, and realtime events

## Overview

The retard.market API exposes the projection-backed V9 prediction-market feed
on Robinhood Chain. The supported integration contract is V9; older
RetardMarket routes remain key-gated for first-party history and migration
flows but are not the recommended developer surface.

Every HTTP route under `/api/retard` requires a VibeChain API key, including
runtime, health, legacy, and realtime endpoints.

## Create an API key

Create a free caller-specific key before making your first request:

```bash theme={null}
curl -X POST https://build.vibechain.com/apikey/create \
  -H "Content-Type: application/json" \
  -d '{
    "description": "YOUR_PROJECT - retard.market",
    "email": "YOUR_EMAIL"
  }'
```

Send the returned key in the `API-KEY` header on every API request:

```bash theme={null}
curl https://build.vibechain.com/api/retard/v9/runtime \
  -H "API-KEY: YOUR_API_KEY"
```

The API key identifies your workload for quota and abuse control. It is not a
wallet credential and does not replace transaction simulation, slippage
protection, or wallet signatures. Keep it out of source control and URLs.

## Base URL

The current V9 base URL is:

```text theme={null}
https://build.vibechain.com/api/retard/v9
```

The API serves Robinhood Chain (`chainId: 4663`). Read `/runtime` at startup and
fail closed unless both `enabled` and `publicEnabled` are true.

## Quick start

Read the newest projected market:

```bash theme={null}
curl "https://build.vibechain.com/api/retard/v9/markets?cursor=0&limit=1" \
  -H "API-KEY: YOUR_API_KEY"
```

Addresses and integer onchain amounts are returned as strings where precision
matters. WETH values such as `totalSeed`, `backingWeth`, and quote amounts are
denominated in Wei unless a field explicitly says otherwise. Probabilities use
basis points (`10,000 = 100%`).

## Pagination and projection safety

List endpoints use a numeric `cursor` and a `limit` from 1 to 100. Follow
`nextCursor` until it is `null`; do not infer completeness from a short page.

V9 reads come from a finalized MongoDB projection. The API returns a
non-cacheable `503` instead of silently rebuilding stale state from chain or
serving data beyond its freshness bounds. Retry with backoff and keep the last
known-good snapshot marked stale until a fresh read succeeds.

## Realtime stream

`GET /stream` is a Server-Sent Events stream used to invalidate or refresh REST
snapshots. External clients must attach `API-KEY` as a header. Native browser
`EventSource` cannot set headers, so use a fetch-based SSE client or an
EventSource-compatible library that supports request headers. Do not place your
API key in the URL.

Treat stream events as wakeups, not as a replacement for the durable REST
snapshot. Reconnect with backoff and recover through `/markets` after a gap or
`resync` event.

## Rate limits and errors

The default allowance is 100 requests per minute per client IP for a standard
key; approved key multipliers may raise that allowance. A missing key, invalid
key, or exhausted allowance returns the same `429` response:

```json theme={null}
{
  "error": "API_KEY_REQUIRED_OR_RATE_LIMITED",
  "docs": "https://docs.vibechain.com/api-reference/retardmarket-intro"
}
```

| Status | Meaning                                                               |
| ------ | --------------------------------------------------------------------- |
| `400`  | Invalid address, cursor, limit, side, amount, or other request input  |
| `404`  | The requested market does not exist in the official projection        |
| `409`  | The requested action conflicts with the market or transaction state   |
| `429`  | API key missing/invalid or caller quota exhausted                     |
| `503`  | Product disabled, projection stale/unavailable, or realtime not ready |

## Trading boundary

The HTTP API is a read/projection and preparation surface. `/quote` returns a
block-pinned conservative buy preview, but trading and claims still happen in
the audited Robinhood Chain contracts using wallet-signed transactions. The
public [retard.market agent runbook](https://vibechain.com/retard/agents.md)
describes the required runtime, quote, simulation, receipt, and recovery
sequence.

For API support or higher limits, contact
[gm@vibechain.com](mailto:gm@vibechain.com).