---
name: bid-to-rank
description: >
  Sponsor a URL on the bidtorank.dev permanent directory. Use when the user wants
  launch distribution, a ranked listing, or to quote the current board. Also
  covers moving a listing back to #1 — same URL, pay the difference, no account.
---

# Sponsor a ranked listing

Paid sponsorship directory. Rank follows the sponsorship total. Every cleared
payment buys or raises a permanent sponsored listing; there is no prize, winner,
or losing payment. Live rows stay as crawlable links.

Public sponsorships are **closed** until launch. Drafts return 403 unless the
operator sets `BIDTORANK_PUBLIC_BIDS=true`.

## Base

- Site: `https://bidtorank.dev`
- Skill: `https://bidtorank.dev/skill.md`
- Analytics: `https://bidtorank.dev/analytics`

## Flow

1. `GET /v1/board` — ranked live listings (permanent), whether sponsorships are open,
   `launchAt` (ISO date sponsorships open), and `requiredToLeadCents`: the exact
   payment that puts a NEW listing at #1.
2. Optionally `GET /v1/meta?url=https://example.com` — preview of the fetched
   title, one-liner, and favicon used for the listing card.
3. Show the user the price of #1 and the next open rank. Confirm the spend.
4. `POST /v1/drafts` with JSON:
   `{ "url": "https://example.com", "amountCents": 1000 }`
   - `url` must be https
   - `amountCents` is the **target total** for the listing, integer, minimum 100 ($1)
   - `title` / `oneLiner` / `email` are optional — title and one-liner are
     fetched from the URL when omitted
5. If the URL is already live, the API returns `mode: "topup"` and charges only
   the difference (minimum $1 more). No account or session required.
   Otherwise it returns `mode: "new"`, a draft id, and `status: "pending"`.
6. Send the user `checkout` (Stripe Checkout URL). Do not invent a payment page.
7. After Stripe reports `checkout.session.completed`, the listing becomes `live`
   (or the existing sponsorship total is raised).
8. `GET /v1/rank?url=https://example.com` — current rank or `null`.

Do not mark a listing live yourself.

## Pricing

- A listing's placement score is its sponsorship total plus 5% per full day held, up to 10× that total.
- Taking a spot costs the placement score plus $1. Smaller sponsorships still buy a permanent listing at the rank they support.
- A sponsorship total more than 2× the current #1 total pays a 100% direct-move surcharge — the checkout charge is double.
- `requiredToLeadCents` from the board already reflects all of this for #1.

## Move back to #1

Paste the same URL again. Set `amountCents` to the new sponsorship total (current total + raise).
`POST /v1/drafts` detects the live listing, returns `mode: "topup"`, and charges
only the difference. No login.

## Closed board

Sponsorships are gated by launch date: `GET /v1/board` returns `launchAt` (2026-09-01T00:00:00Z)
and drafts/top-ups return `PUBLIC_BIDS_CLOSED` until then. If closed, stop — tell the
user when sponsorships open and quote the live board only. The operator can open sponsorships
early for testing with `BIDTORANK_PUBLIC_BIDS=true`.