generated: '2026-09-03'
method: derived
source: openapi/ontopx402-leaderboard-api-openapi.yml, openapi/ontopx402-bidding-api-openapi.yml
note: >-
  Small by design. There is no account or user entity anywhere in the model — a
  link's URL is its own identity. Rank is not stored; it is computed from the
  lifetime totals on every read.
entities:
- name: Leaderboard
  description: The whole board — count, total_paid_usd, top_amount_usd, to_take_first_usd, entries[].
  fields: [count, total_paid_usd, top_amount_usd, to_take_first_usd, entries]
- name: Entry
  description: One listing. Identified by its url; amount_usd is the lifetime total paid on it; page is its permalink at /e/<slug>.
  fields: [rank, url, name, description, amount_usd, amount_atomic, bids, favicon, first_bid_at, updated_at, page]
  identity: url
- name: EntryLookup
  description: Entry plus lookup-only fields returned by GET /api/entry — listed, and to_pass_the_one_above_usd.
  fields: [listed, to_pass_the_one_above_usd]
- name: BidRequest
  description: The write payload — url, description (max 255 chars), amount (USD, min $1).
  fields: [url, description, amount]
- name: BidSuccess
  description: A settled bid — ok, paid_usd, transaction hash, network (CAIP-2), plus the updated Entry fields.
  fields: [ok, paid_usd, transaction, network, simulated]
- name: PaymentRequired
  description: The x402 v2 challenge returned on 402 — x402Version, resource, accepts[] (Base + Solana USDC), extensions.bazaar.
  fields: [x402Version, error, resource, accepts, extensions]
- name: Error
  description: 'The single error envelope: {"error": "<sentence>"}.'
  fields: [error]
relationships:
- from: Leaderboard
  to: Entry
  type: has_many
  via: entries
- from: EntryLookup
  to: Entry
  type: extends
  via: same shape plus lookup fields
- from: BidRequest
  to: Entry
  type: creates_or_increments
  via: url (a bid on a listed url adds to its total; a new url creates the entry)
- from: BidSuccess
  to: Entry
  type: embeds
  via: entry fields returned inline after settlement
- from: PaymentRequired
  to: BidRequest
  type: prices
  via: accepts[].amount equals the caller-named bid amount in atomic USDC