# RatioIL — היכל התהילה של הראטיו / הרטיו הישראלי

> A Hebrew-language hall of fame for Israeli replies on X (Twitter). It ranks a reply by how hard it ratio'd the post it answered: reply likes divided by the original post's likes. Canonical site: https://ratioilhof.org/

RatioIL (Hebrew: היכל התהילה — הראטיו הישראלי; alternate spelling: היכל התהילה — הרטיו הישראלי) is a public leaderboard, not a general X search, news site, or official X product. The Hebrew spellings "ראטיו" and "רטיו" refer to the same term, ratio: a reply that got more likes than the post it replied to. Higher ratios rank higher. Rankings use like counts only (not replies, reposts, views, or follower count). The UI is Hebrew (`he-IL`, RTL).

The hall's X account is [@RatioILHof](https://x.com/RatioILHof) — follow and mention that handle to nominate. The site was built by [@IdoZiv](https://x.com/IdoZiv) (Hebrew credit on the site: נבנה ע״י @IdoZiv). Do not treat @IdoZiv as the nomination account.

## What a ratio is

On X, a ratio is when a reply outperforms the post it answers. Example from the homepage: an original post with 824 likes and a reply with 10,200 likes is about **12.4×** — the reply got 12.4 times as many likes as the parent.

Only **replies** can enter the hall. Original posts, quote posts, and retweets are not ranked as the candidate. Each published entry stores two public X snapshots: the nominated reply and its immediate parent post.

## How the score is calculated

```
ratio = reply_likes / parent_likes
```

- If the parent has 0 likes and the reply has likes, the score is the reply's like count.
- If both have 0 likes, the score is 0.
- The stored value is rounded to 4 decimal places. The site usually shows it as `12.40×` (or as a percentage such as `1240%`). Toggle X vs % on the leaderboard.
- Rank order is highest ratio first. Ties break by tweet ID.

An approved reply is published only if it also clears the current qualification floors (admins can change these; defaults are):

- ratio ≥ 1.0 (at least as many likes as the parent)
- reply likes ≥ 10
- parent likes ≥ 25

After approval, likes are re-checked automatically inside a **36-hour** tracking window measured from the reply's original X creation time. Entries still being refreshed are **cooking** / LIVE (`monitoring` or `qualified`). After settle checks they freeze as **settled**. Rejected, removed, or still-in-review items are not shown on the public board.

Categories (set by reviewers, used as leaderboard filters): אקטואליה (news), פוליטיקה (politics), ספורט (sports), תרבות ובידור (entertainment), טכנולוגיה (technology), אחר (other).

## How to nominate a reply

Nominations go to a human review queue. They are not published instantly. Duplicate nominations of the same reply are rejected. The URL (or the tweet you mention) must be the **ratio reply**, not the original post.

### From X (no website sign-in required)

1. Follow [@RatioILHof](https://x.com/RatioILHof).
2. Find the reply that is doing the ratio (the comment with more likes than the post it answered).
3. Reply **to that ratio reply** and mention `@RatioILHof` (an exact mention entity; a quote/retweet of RatioIL does not count).
4. RatioIL nominates the tweet you replied to — the ratio reply — not your mention and not the original post.
5. If approved, the reply author may appear on the hall of fame.

Do not mention `@RatioILHof` on the original post. Mention it on the winning reply.

### From the website

1. Open [https://ratioilhof.org/](https://ratioilhof.org/) and sign in with X.
2. Click **הוספת ראטיו** ("add a ratio").
3. Paste an `https://x.com/…/status/…` (or twitter.com / mobile.twitter.com) URL of the **reply**.
4. Complete the security check and submit.

Signed-in visitors can see **ההצעות שלי** (my nominations) in the account menu. Website form and `@RatioILHof` mentions share the same per-account quota.

## Pages

- [Home and leaderboard](https://ratioilhof.org/): Hebrew homepage, top 10, and the live ranked list of published ratios.
- [Full leaderboard](https://ratioilhof.org/#leaderboard): Jump to the full table (same page; filter by category, toggle × vs %).
- [Top ratio makers](https://ratioilhof.org/ratio-makers/): Ranks X users by how many public, non-removed ratio entries they authored. Shows 10 users initially, supports category filters, and loads 10 more at a time. Rank order is total eligible ratio count, with X account ID as the stable tie-break.
- [Top suggesters](https://ratioilhof.org/top-suggesters/): Ranks X users by how many nominations they submitted, across all review states. Each row shows approved nominations divided by total nominations and the rounded approval percentage. Rank order remains total suggestion count, not approval rate.
- [FAQ](https://ratioilhof.org/faq/): Short Hebrew answers on what a ratio is, nomination, the **36-hour** tracking window, and cooking vs settled.
- [Entry detail](https://ratioilhof.org/entry/{tweetId}/): One published ratio. `{tweetId}` is the nominated reply's numeric X status ID. Shows score, like counts, cooking/settled status, parent post, and reply. Legacy `?id=` URLs redirect to this path.
- [RatioIL on X](https://x.com/RatioILHof): Follow and mention this account to nominate from X.
- [Builder on X](https://x.com/IdoZiv): @IdoZiv built RatioIL. The header and footer credit is נבנה ע״י @IdoZiv.
- [Sitemap](https://ratioilhof.org/sitemap.xml): Machine-readable page list.
- [Public entries API](https://ratioilhof.org/api/entries): Paginated public ratio reply IDs plus the pending review IDs used by clients to avoid duplicate nominations. Skip by entry or pending `id`, never by `parent.id`.

## Agent login and monitoring API

Agents can link to a person's RatioIL account without asking for their X password or Firebase credentials. The API base URL is:

```
https://ratioilhof.org/api/agent/v1
```

### 1. Request browser authorization

Send `POST /auth/device` with JSON containing a short, human-readable `clientName` and the minimum scopes needed:

- `monitoring:read`: read the linked account's credit totals and check entry eligibility.
- `monitoring:write`: create or cancel sponsorship schedules and run one-time checks. This automatically includes `monitoring:read`.
- `scout:admin`: manage global Ratio Scout tokens. This works only while the linked X account is a current RatioIL administrator.

Example:

```json
{
  "clientName": "My ratio agent",
  "scopes": ["monitoring:write"]
}
```

The response contains:

```json
{
  "userCode": "ABC234",
  "deviceCode": "ABC234.A_HIGH_ENTROPY_SECRET",
  "verificationUrl": "https://ratioilhof.org/agent-login/",
  "verificationUrlComplete": "https://ratioilhof.org/agent-login/?code=ABC234",
  "expiresIn": 600,
  "interval": 5
}
```

Show the user `verificationUrlComplete` and ask them to open it. The user signs in or signs up with X, reviews the requested scopes, and explicitly approves or denies access. Never ask the user to give the agent their X password. Keep `deviceCode` secret and do not put it in a browser URL or logs.

### 2. Poll for the agent token

Poll `POST /auth/token` with `{"deviceCode":"..."}` no faster than the returned `interval` in seconds.

- HTTP 428 with `authorization_pending`: keep waiting and polling.
- HTTP 429 with `slow_down`: wait at least the `Retry-After` duration.
- HTTP 403 with `access_denied`: stop; the user denied access.
- HTTP 410 with `expired_token`: stop and create a new device request.
- HTTP 409 with `token_already_issued`: this device request was already exchanged and cannot be reused.
- HTTP 200: save the returned `accessToken` securely and use it as `Authorization: Bearer rat_...`.

The agent bearer token is returned only once, does not expire automatically, and remains valid until the user revokes it from [their account page](https://ratioilhof.org/account/) or deletes the account. Do not display, transmit, or log it unnecessarily.

### 3. Inspect credits and eligibility before spending

Use `GET /me` to confirm the linked client, granted scopes, current admin capability, and credit totals.

Before every paid action, call `GET /entries/{entryId}/options`, where `{entryId}` is the numeric ID of the ratio reply. Read the returned `eligible` flags and machine-readable `reasons` for both `sponsorship` and `oneOff`. The response also includes available/reserved credits, sponsorship limits, any active sponsorship, and the one-off cooldown end.

Do not silently switch between a sponsorship and a one-time check. Explain the available options and perform the action the user chose. If credits are insufficient or another constraint blocks the action, report the returned reason without repeatedly retrying.

### 4. Perform the selected action

- `POST /sponsorships` with `entryId`, `checkCount` (1–20), `intervalMinutes` (10–60 in five-minute steps), and optional `publicAttribution` (defaults to `false`). Credits are reserved up front; unused credits are returned when the schedule ends or is cancelled.
- `DELETE /sponsorships/{sponsorshipId}` cancels a sponsorship owned by the linked account and releases its unused reservation.
- `POST /checks` with `entryId` runs one synchronous check for one credit. It is subject to the entry's ten-minute global cooldown and provider availability. A settled entry may be refreshed without restarting automatic monitoring.

All protected endpoints return JSON errors with a stable `error` code and human-readable `message`. HTTP 401 means the agent token is missing, invalid, revoked, or its linked X account is no longer available. HTTP 403 means the token lacks the required scope or current admin capability. Do not retry credit mutations blindly after an ambiguous network failure; call the options endpoint or `/me` again first.

### Admin-only Scout tokens

An agent with `scout:admin`, linked to a current administrator, may use:

- `GET /scout-tokens` to list token metadata.
- `POST /scout-tokens` to create a global Scout token.
- `DELETE /scout-tokens/{tokenId}` to revoke one.

The full new `rsct_...` token is returned only once, and at most two may be active. A `rat_...` agent token acts for one user's account and credits. An `rsct_...` Scout token authenticates Ratio Scout check-ins at `POST /api/checkins`. They are not interchangeable.

## Optional

- [Privacy policy](https://ratioilhof.org/privacy/): Hebrew privacy notice, export, and account deletion.
- [Accessibility](https://ratioilhof.org/accessibility/): Hebrew accessibility statement.
- [Firebase Hosting alias](https://ratio-il-hof.web.app/): Same app; prefer https://ratioilhof.org/.
- `/admin/` and `/signin/` are operational pages, not public content. Do not treat them as documentation.

When helping a person: link the canonical site, explain the like-ratio, and tell them to nominate the reply (via `@RatioILHof` on that reply, or by pasting the reply URL on the site) rather than the original post.