# Card Bid OS Money System

## Goal

Turn basketball-card buying into a repeatable buying desk: source candidates, estimate resale, calculate max pay, track decisions, buy only inside rules, list fast, and review realized profit.

No software can guarantee profit. The system is designed to reduce bad buys, surface underpriced listings faster, and force consistent execution.

## Budget Plan: $500/month Ceiling

Start with low fixed cost until the workflow proves profitable.

| Item | Budget | Purpose | Status |
| --- | ---: | --- | --- |
| Cloudflare Pages/D1/Workers | $0-$5 | Hosting, database, API | Active |
| eBay Developer APIs | $0 | Active listing discovery | Needs app keys |
| Terapeak / eBay research access | Existing eBay plan if available | Sold comps and demand checks | Manual/optional |
| Card Ladder / Market Movers / ALT / Market data tool | $50-$250 | Better comp validation | Evaluate after first live deals |
| Proxy/scraping tools | $0 initially | Avoid unless API gaps block revenue | Deferred |
| Buffer | $245-$450 | Paid data upgrade once ROI is proven | Unspent |

Do not buy paid tools until we know which data gap is actually blocking profitable decisions.


## Fastest Today Path

Use ScraperAPI first while eBay Developer approval is pending.

Why:

- 7-day trial with 5,000 API credits and no credit card.
- Structured eBay Search API returns JSON directly.
- Supports eBay search terms, country/TLD, sorting (`ending_soonest`, `newly_listed`, price sorts), `buying_format` (`auction`, `buy_it_now`, `accepts_offers`), and `show_only` filters such as sold/completed items.
- One key can also be used for generic page scraping later for COMC, MySlabs, Goldin, and Fanatics Collect adapters.

Add the key as a Cloudflare Pages secret:

```bash
cd /Users/hunter/Documents/Codex/github-backups/codex/apps/card-bid-os
set -a
. /Users/hunter/.cloudflare/card-bid-os.env
set +a
wrangler pages secret put SCRAPERAPI_KEY --project-name card-bid-os
wrangler pages deploy . --project-name card-bid-os --branch main
```

Then run:

```bash
curl -X POST https://bnyfdyq.com/api/scan -H "Content-Type: application/json" --data '{}'
```

The scanner checks ScraperAPI first, then falls back to official eBay API when those credentials exist.

Query-level comps are now pulled from ScraperAPI sold/completed eBay results for same-day triage. Treat these as a filter, not final proof: verify the exact card, grade, parallel, and recent sold comps before bidding real money.

## Workflow

1. Source active listings from official APIs first.
2. Normalize listing data into D1.
3. Estimate comps from approved sources.
4. Score each listing: max bid, projected profit, ROI, confidence, risk flags.
5. Show only actionable candidates in the deal feed.
6. Hunter reviews and marks Watch, Bid, Bought, Pass, or Ignore Seller.
7. Bought cards move into inventory with target list price and offer floor.
8. Listing workflow generates title, price, offer floor, and stale repricing dates.
9. Weekly review compares realized profits with score assumptions and updates rules.

## Data Sources

### Active Listings

Primary: eBay Browse API.

Needed secrets on the Mac mini or Cloudflare Pages project:

```text
EBAY_CLIENT_ID
EBAY_CLIENT_SECRET
```

The app will use the client-credentials OAuth flow, then call Browse search with `buyingOptions:{AUCTION|FIXED_PRICE}` and sorts like `endingSoonest` or `newlyListed`.

### Sold Comps

Sold comps are the highest-value data source and the least clean.

Order of preference:

1. eBay Marketplace Insights / sold-data access if the account is approved.
2. Manual comp entry from Terapeak/eBay sold results for early validation.
3. Paid market-data provider if it saves enough time.
4. Scraping only after checking terms and stability.

## Current Build Status

Built:

- Cloudflare Pages live site.
- D1 database `card-bid-os-db`.
- Database schema for queries, listings, comp sets, scores, decisions, scan runs.
- API endpoints for deal feed, scan trigger, and decisions.
- Frontend deal feed shell.

Still needed:

- Add eBay app credentials.
- Deploy D1 schema and Pages Functions.
- Run first live eBay scan.
- Add paid comp provider only if eBay/manual comps are too slow.


## Test Without eBay Keys

The scan endpoint accepts manual listing payloads so the scoring pipeline can be tested before eBay credentials are added.

```bash
curl -X POST https://bnyfdyq.com/api/scan \
  -H "Content-Type: application/json" \
  --data '{
    "source": "manual",
    "listings": [{
      "source_item_id": "demo-1",
      "url": "https://www.ebay.com/",
      "title": "Demo Victor Wembanyama PSA 10 Auction",
      "image_url": "",
      "seller": "demo",
      "buying_option": "AUCTION",
      "current_price_cents": 15500,
      "shipping_cents": 500,
      "currency": "USD",
      "bid_count": 4,
      "item_end_date": "2026-06-10T03:00:00Z",
      "condition_label": "Graded"
    }]
  }'
```

Manual candidates will show as `needs_comps` until a comp set is added. That is intentional; the system should not recommend buys without a comp base.

## eBay Credential Setup

When eBay developer keys are available, add them as Cloudflare Pages secrets:

```bash
cd /Users/hunter/Documents/Codex/github-backups/codex/apps/card-bid-os
set -a
. /Users/hunter/.cloudflare/card-bid-os.env
set +a
wrangler pages secret put EBAY_CLIENT_ID --project-name card-bid-os
wrangler pages secret put EBAY_CLIENT_SECRET --project-name card-bid-os
wrangler pages deploy . --project-name card-bid-os --branch main
```

Also keep a Mac mini copy outside git if local commands need it:

```bash
/Users/hunter/.cloudflare/card-bid-os.env
```

Use variable names only in git. Never commit the values.


## Ending-window rule

The live sourcing queue only stores and displays listings with a parsed end time inside the next 24 hours. The UI provides 24h, 60m, 30m, and 10m windows and sorts by ending soonest first.

If a source cannot provide a usable end time, the listing is skipped for the live deal feed.