# Geren Documentation

> Multi-chain RPC proxy platform — developer and AI-agent documentation. Read this first.

This file contains all documentation content in a single document following the llmstxt.org standard.

## Authentication


Geren supports two authentication modes.

## URL-embedded API key

Embed the key directly in the URL. Simplest; suitable for trusted
server-side environments.

```
https://eth-mainnet.gerenchain.io/$YOUR_KEY
```

## Bearer token

Pass the key via the standard `Authorization` header. Recommended when
the key may pass through logs or intermediary proxies.

```bash
curl https://eth-mainnet.gerenchain.io \
  -H "Authorization: Bearer $YOUR_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","id":1}'
```

## Key rotation

Generate the new key first, deploy it, then revoke the old one. Keys
take effect within 30 seconds of creation, so rotation is zero-downtime
when done in that order.

---

## Getting Started


This guide takes you from signup to your first successful JSON-RPC call.

## 1. Create an account

Sign up at [dash.gerenchain.io](https://dash.gerenchain.io). The free
tier is enough to follow this guide end-to-end.

## 2. Generate an API key

From the dashboard, click **Create Key**. Scope it to a single chain to
start (for example, `eth-mainnet`).

## 3. Make a request

```bash
curl https://eth-mainnet.gerenchain.io/$YOUR_KEY \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","id":1}'
```

You should receive the current block height in hex:

```json
{ "jsonrpc": "2.0", "id": 1, "result": "0x12d4f7a" }
```

That's it — you're connected.

## Next steps

- [Authentication](/authentication) — bearer-token flows and key rotation.
- [Rate Limits](/rate-limits) — understand your throughput budget.

---

## Introduction

# Geren Documentation

Geren is a **multi-chain RPC proxy platform** that gives you a single,
fast, authenticated endpoint across 30+ blockchain networks.

This documentation is the authoritative source for both **developers**
and **AI agents** integrating with the platform. AI agents should read
[`/llms.txt`](pathname:///llms.txt) first for a machine-readable index, or
[`/llms-full.txt`](pathname:///llms-full.txt) for the full corpus in one file.

## Where to start

- **[Getting Started](/getting-started)** — integrate in 5 minutes.
- **[Authentication](/authentication)** — API keys and bearer tokens.
- **[Rate Limits](/rate-limits)** — budgets, headers, and backoff.

## What Geren gives you

- One API key across every supported chain.
- Sub-50ms median response times via a multi-tier cache.
- Consistent JSON-RPC semantics regardless of the upstream node.

## For AI agents

The documentation is published as stable, machine-readable Markdown:

- [`/llms.txt`](pathname:///llms.txt) — concise index of every page.
- [`/llms-full.txt`](pathname:///llms-full.txt) — every page concatenated for ingestion.

News, announcements, and engineering posts live separately on the
[blog](https://gerenchain.io/blog) and are considered secondary to this
documentation.

---

## Rate Limits


Geren applies two independent rate-limit budgets to every request.

## Per-key budget

Each API key has a steady-state rate (requests per second) and a short
burst capacity. The exact numbers depend on your plan; check the
dashboard for current values.

## Per-IP budget

A coarse per-source-IP limit protects shared infrastructure. The free
tier limit is 100 RPS per IP, summed across all keys.

## Response headers

Every response includes:

| Header | Meaning |
| --- | --- |
| `X-RateLimit-Limit` | Your steady-state RPS |
| `X-RateLimit-Remaining` | Tokens left in the current window |
| `X-RateLimit-Reset` | Seconds until the bucket refills |
| `Retry-After` | Present only on `429` responses |

## Handling 429s

Back off exponentially. Geren guarantees the bucket refills at the
advertised rate, so a deterministic exponential backoff converges
predictably.

```text
attempt 1 → wait 1s
attempt 2 → wait 2s
attempt 3 → wait 4s
attempt 4 → wait 8s  (cap here)
```