# Discoball

> Discoball is a catalog of merchant discount codes validated at real checkouts,
> built for AI agents. Codes are labeled by evidence: "verified" means a logged
> checkout test on a known date (hand-tested, automated checkout, or an agent report);
> "unproven" means no logged test yet. Ranking is commission-blind: affiliate
> payout can never influence result order, enforced by a public CI test.

## MCP server

- Endpoint: https://discoball.dev/mcp (streamable HTTP; no auth to read)
- Stdio fallback: `npx discoball-mcp`

Tools:

- `find_deals` — ranked, validated promo codes. Provide exactly one of:
  `merchant` (name/slug/domain), `product_url`, or `category`. Returns ranked
  codes with verification evidence, success rates, and a citable URL per deal.
- `report_result` — report whether a code worked at checkout (`deal_id`,
  `worked`, optional `amount_saved_cents`, `idempotency_key`). No account or
  API key; a self-issued installation UUID is used for rate-limiting.

## Public JSON endpoints

- https://discoball.dev/deals/<merchant> — ranked deals for one merchant
- https://discoball.dev/stats — live catalog counters (merchants, categories,
  codes verified, checkouts run, recent verifications)
- https://discoball.dev/d/<deal_id> — evidence page for one deal (citable;
  returns 410 once a deal is killed)

## Deal guides (HTML, code tables live from the catalog)

- https://discoball.dev/guides/eyewear-promo-codes
- https://discoball.dev/guides/mattress-promo-codes
- https://discoball.dev/guides/pet-supplies-promo-codes
- https://discoball.dev/guides/dtc-apparel-promo-codes

## Honesty semantics

- "verified" = tested at a real checkout on a logged date, by hand or via an
  agent report. Verification decays with age.
- "unproven" = listed but not yet proven at a checkout (low or zero sample
  size). Never presented as verified.
- `success_rate` reports observed outcomes: `rate` (null when n = 0), `n`, and
  an `unproven` flag.
- Ranking inputs: offer value, verification age, success confidence.
  Commission is excluded, enforced in CI by test/commission-blind.test.ts.
- Affiliate links, where present, are flagged per deal via
  `affiliate_disclosure`. Disclosure: https://discoball.dev/disclosure

## Source

- Repository: https://github.com/juanfiguera/discoball
- Contact: hello@discoball.dev