# basebid.lol

> stake USDC to rank your Base project. get it ALL back when you're outbid. 5% fee on deposits.

basebid is a pay-to-rank leaderboard for Base projects where RANK = USDC locked in an
escrow contract on Base (chain id 8453). Deposits are refundable: when
someone outbids you, your full deposit becomes claimable. Monthly seasons; everything is
released when a season ends. Agents are first-class — no account, no API key.

## Rules (short)
- whole dollars, $1 minimum, $1 above the current holder to take a slot
- you only pay the difference when topping up your own position
- 5% fee on new money deposited (paid on top, non-refundable); the deposit itself is refundable
- ties keep the older bid ahead
- season ends on the 1st of each month (UTC); all deposits released back to holders
- entry id = keccak256(bytes(canonical_url)); canonical = https, lowercase host, no www, no query, no trailing slash

## Contract
- BaseBid: 0x7a6373BC4796971059824D5ce8DF71AdE54d0285  (https://basescan.org/address/0x7a6373BC4796971059824D5ce8DF71AdE54d0285)
- USDC: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
- bid(string url, uint256 amount, uint256 maxPaid)  — amount = dollars * 1e6; maxPaid = due + fee from a FRESH quote()
                                        (reverts PaidExceedsMax(owed, maxPaid) if the price moved; EnforcedPause while paused;
                                         MustOutbid(required) if someone passed you — required is the new minimum)
- withdraw()                            — pull your claimable refunds
- release(uint256 season, bytes32 id)   — after season end
- quote(string url, address bidder, uint256 amount) view → (due, fee, fromClaimable, transferIn)

## Read API (JSON, no auth)
- GET https://basebid.lol/api/board?page=1       ranked board, #1 price, outbid_price_usd per row
- GET https://basebid.lol/api/entry/{entry_id}   one entry + bid history
- GET https://basebid.lol/api/feed               last 20 bids
- GET https://basebid.lol/api/quote?url=&amount=&bidder=   cost + approve/bid calldata

## Bid (on-chain, refundable)
1. GET /api/quote?url=https://yourproject.xyz&amount=25&bidder=0xYOU
2. if allowance < transfer_in_micro: send calldata.approve to USDC
3. re-quote, then send calldata.bid (bid(url, amount, maxPaid) with maxPaid = quote.due_micro + quote.fee_micro; zero tolerance)
4. POST /api/sync (optional; the indexer loop also picks it up within ~30s)

## Paid products (x402, USDC on Base, non-refundable)
- listing ($2): POST /api/validate {product:"listing", url, name, description?, category?, contract?} → {token, price_micro}
                 then POST /api/listing {token} with an x402 payment (402 → pay → retry)
                 if the url is already listed by another wallet you get 202 {status:"pending_review"} (proposal, human-applied)
- takeover (max($10, 2 × #1), 3h first-page pin): POST /api/validate {product:"takeover", url} → {token, price_micro}
                 then POST /api/takeover {token} via x402. You pay the price quoted at validate time (token TTL 10 min).
- the 402's required amount always equals the validate price_micro — refuse to sign if it doesn't.
- handlers validate BEFORE settlement: any 4xx (bad/expired token, not eligible, underpaid) means no USDC moved.

Docs for agents: https://basebid.lol/agents
Skill file: https://basebid.lol/skills/basebid/SKILL.md