last30days-skill/partner-credits-proposal.md

# Partner Credits: Zero-Registration Free Tier for last30days Users

**Type:** Partnership proposal for ScrapeCreators
**Date:** 2026-03-05
**Status:** Draft proposal

---

## The Pitch

Every last30days user gets 100 free ScrapeCreators credits — Reddit, TikTok, Instagram — without ever visiting scrapecreators.com or creating an account. When they run out, the skill tells them where to upgrade. ScrapeCreators gets a distribution channel. last30days gets a killer default experience.

## The Problem

Right now, new last30days users hit a wall:

1. Install the skill (30 seconds)
2. Try `/last30days AI video tools`
3. Get told they need a `SCRAPECREATORS_API_KEY`
4. Have to go to scrapecreators.com, register, get a key, paste it into `.env`
5. Many never come back

The best Reddit experience requires a key. The friction kills adoption.

## The Proposal: Machine-Bound Partner Tokens

### How It Works

**ScrapeCreators side:**
1. Issue last30days a **partner ID** (e.g., `partner_last30days`)
2. Accept a new header: `X-Partner-Device: <device_hash>`
3. On first request per device hash: allocate 100 credits, no registration needed
4. Track usage: `(partner_id, device_hash) → credits_remaining`
5. When credits hit 0: return `402` with upgrade URL in response body

**last30days side:**
1. On first run, generate a **device fingerprint** and cache it locally
2. If user has no `SCRAPECREATORS_API_KEY`, send requests with partner headers instead
3. When 402 comes back, show a friendly "upgrade" message

That's it. No accounts, no OAuth, no registration flow.

### The Device Fingerprint

```python
import hashlib, platform, uuid, os

def get_device_id():
    """Generate a stable, hard-to-forge device fingerprint."""
    # Use the OS-level machine ID (persists across reinstalls on most systems)
    machine_id = _get_machine_id()

    # Salt with the partner ID so the hash is useless outside this context
    raw = f"last30days:{machine_id}"
    return hashlib.sha256(raw.encode()).hexdigest()

def _get_machine_id():
    """Get the OS hardware/machine ID."""
    if platform.system() == "Darwin":
        # macOS: IOPlatformUUID (hardware-bound, survives OS reinstall)
        import subprocess
        result = subprocess.run(
            ["ioreg", "-rd1", "-c", "IOPlatformExpertDevice"],
            capture_output=True, text=True
        )
        for line in result.stdout.splitlines():
            if "IOPlatformUUID" in line:
                return line.split('"')[-2]

    elif platform.system() == "Linux":
        # Linux: /etc/machine-id (set at install time)
        try:
            return open("/etc/machine-id").read().strip()
        except FileNotFoundError:
            pass

    # Fallback: MAC address + hostname (less stable but reasonable)
    return f"{uuid.getnode()}:{platform.node()}"
```

**Why this works:**
- macOS `IOPlatformUUID` is hardware-bound — can't change it without a new motherboard
- Linux `/etc/machine-id` is set at OS install — persists across reboots
- Hashed with `last30days:` prefix so the raw ID is never sent to ScrapeCreators
- Cached locally in `~/.config/last30days/.device_id` after first generation

### API Request Format

```
# Without partner credits (existing flow — user has their own key)
GET /v1/reddit/search?query=AI+tools
x-api-key: sc_user_abc123

# With partner credits (new — no registration needed)
GET /v1/reddit/search?query=AI+tools
x-api-key: sc_partner_last30days
X-Partner-Device: a1b2c3d4e5f6...  (sha256 hex)
```

ScrapeCreators treats `sc_partner_last30days` as a special key class:
- Requires `X-Partner-Device` header
- Credits tracked per device hash, not per API key
- Rate limited per device (e.g., 10 requests/minute)
- 100 credits per unique device, lifetime

### What Counts as a Credit

One API call = one credit. A typical `/last30days` run uses roughly:
- 2-4 Reddit searches (global + subreddit drilldowns)
- 1-2 TikTok searches + 2-3 transcript fetches
- 1-2 Instagram searches + 2-3 transcript fetches

So ~10-15 credits per run. 100 credits ≈ **7-10 full research runs** before upgrade.

That's enough to get hooked.

## Abuse Prevention

### What we're defending against

| Threat | Likelihood | Impact |
|--------|-----------|--------|
| User spoofs device ID to get infinite credits | Low | Medium |
| Script generates thousands of fake device IDs | Medium | High |
| User shares partner key for non-last30days use | Low | Low |

### Defenses (simplest first)

**1. Hardware-bound device ID (primary defense)**
- macOS IOPlatformUUID can't be changed without hardware swap
- Linux machine-id requires root to change and breaks other software
- Not a cookie or config file — it's the machine itself

**2. Rate limiting per device (ScrapeCreators side)**
- 10 requests/minute per device hash
- Prevents scripted rapid-fire abuse even with valid device IDs
- Normal usage never hits this — a full run takes 60-70 seconds with natural gaps

**3. IP rate limiting on new device registrations (ScrapeCreators side)**
- Max 3 new device hashes per IP per day
- Stops "generate 1000 device IDs from one server" attacks
- Legitimate users: one machine, one device ID, done

**4. Total partner pool cap (safety valve)**
- ScrapeCreators sets a monthly cap on total partner credits (e.g., 50,000/month)
- If last30days goes viral and blows the cap, both parties renegotiate
- Prevents runaway costs from unexpected growth

### What we're NOT doing (intentional simplicity)

- No CAPTCHAs
- No email verification
- No phone verification
- No browser fingerprinting
- No token signing or crypto
- No account creation whatsoever

The goal is zero friction. The device ID is "good enough" — it stops casual abuse and scripts. A determined attacker could maybe get 200-300 free credits by VM gymnastics, but that's not worth defending against when paid plans are cheap.

## User Experience

### First run (no key configured)

```
$ /last30days AI video tools

🔍 Searching Reddit, TikTok, Instagram...
ℹ️  Using 100 free partner credits from ScrapeCreators (93 remaining)
   Get your own key for unlimited use: scrapecreators.com/last30days

[... normal results ...]
```

### Credits running low

```
ℹ️  12 partner credits remaining. Get unlimited access: scrapecreators.com/last30days
```

### Credits exhausted

```
⚠️  Free partner credits used up!

Reddit, TikTok, and Instagram require a ScrapeCreators API key.
Get one at: scrapecreators.com/last30days (100 free credits on signup, then pay-as-you-go)

Continuing with X, YouTube, Hacker News, Polymarket, and web search...
```

Key detail: the skill **doesn't stop working** — it gracefully falls back to the sources that don't need a key. The user still gets value, but they see what they're missing.

### After upgrade

```
$ echo 'SCRAPECREATORS_API_KEY=sc_abc123' >> ~/.config/last30days/.env

# Next run — partner headers no longer sent, user's own key used
```

## What ScrapeCreators Gets

1. **Distribution channel** — every last30days install is a potential paying customer
2. **Zero support burden** — no accounts to manage for free tier users
3. **Qualified leads** — users who exhaust 100 credits are proven power users
4. **Co-marketing** — "Powered by ScrapeCreators" in every skill run
5. **Usage data** — anonymous device-level usage patterns across topics

## What last30days Gets

1. **Zero-config Reddit** — install and go, no registration anywhere
2. **TikTok and Instagram included** — three sources work out of the box
3. **Lower barrier to adoption** — the #1 friction point eliminated
4. **Upgrade path built in** — natural conversion funnel

## Implementation Effort

### ScrapeCreators side (their work)
- [ ] Create partner key class with per-device credit tracking
- [ ] Accept `X-Partner-Device` header on partner keys
- [ ] Return `402` with upgrade URL when credits exhausted
- [ ] Rate limit: 10 req/min per device, 3 new devices/day per IP
- [ ] Dashboard for last30days to see aggregate partner usage

### last30days side (our work)
- [ ] `scripts/lib/device_id.py` — generate and cache device fingerprint (~30 lines)
- [ ] Update `scripts/lib/env.py` — fall back to partner auth when no user key
- [ ] Update `_sc_headers()` in reddit.py, tiktok.py, instagram.py — add partner headers
- [ ] Handle 402 response — show upgrade message, continue with other sources
- [ ] Show credits remaining in run output (from response header)

### Suggested response headers from ScrapeCreators

```
X-Partner-Credits-Remaining: 87
X-Partner-Credits-Total: 100
X-Partner-Upgrade-URL: https://scrapecreators.com/last30days
```

## Open Questions

1. **Credit pool negotiation** — what monthly cap works for ScrapeCreators?
2. **Referral tracking** — should `scrapecreators.com/last30days` give a signup bonus or revenue share?
3. **Credit count per endpoint** — should transcript fetches cost the same as searches?
4. **Expiration** — do unused partner credits expire (e.g., 90 days)?

---

## Summary

One device ID. One partner key. One header. 100 free credits. Zero registration.

The entire abuse prevention is: your computer has a hardware ID that you can't easily change. That's it. Simple, clever, and good enough.