# IGdek

> Mobile-optimized 9:16 media for trading cards. Per $4.99 batch (1–5 cards): one reel video, one editable slide deck, full carousel sequence. Format-agnostic, deployable on any social or marketplace surface. We make the media; you move the cards.

## What This Service Does

IGdek generates mobile-optimized 9:16 media for trading cards. You provide a PSA cert number or card photos. **Per $4.99 batch (up to 5 cards), we return a ZIP containing exactly one reel.mp4 video, one editable portrait.pptx slide deck, and a 1080×1920 carousel PNG sequence covering every card in the batch.** Generation takes 8-25 seconds. The output is format-agnostic — yours to deploy on any social or marketplace surface (TikTok, Facebook, eBay listing photos, LinkedIn, Discord, a card-show projector loop, a printed flyer, anywhere mobile). We make the media; you move the cards.

## What you get per batch

- **1 reel.mp4** — single 1080×1920 video stitching every card in the batch with dissolve transitions.
- **1 portrait.pptx** — single editable 9:16 PowerPoint deck containing every card as slides.
- **N carousel PNGs** — `carousel-01.png` through `carousel-NN.png`, frame count scales with cards in the batch (typically 3 frames per card: hero, back, summary).

So 25 cards = 5 batches × $4.99 = **$24.95** = 5 reel.mp4 files + 5 portrait.pptx files + a contiguous carousel-NN.png sequence per batch. NOT 25 reels and 25 decks.

## Three Paths (For Humans)

- [/cert](https://igdek.com/cert) — paste up to 25 PSA cert numbers in one Polar payment, processed in batches of 5 ($4.99 each). The most direct path for graded PSA cards.
- [/upload](https://igdek.com/upload) — for non-PSA grades (SGC, BGS, CGC, CSG, raw) or pre-2021 PSA certs without on-file images.
- [/agent](https://igdek.com/agent) — for users driving a chat agent (ChatGPT with Custom GPT Action, Claude with MCP, Cursor, custom code) that calls our API directly. No re-checkout per card; one conversation handles a stack.

## Cost

- Lookups: Require minimum $4.99 balance but do not deduct. Card image URLs require $9.98+ balance.
- Generation: $4.99 per job (1-5 cards per job), deducted from prepaid balance before work starts. Failed jobs refunded.

## For Agents and Integrators

- [Agent menu (markdown)](/.well-known/agent.md) — narrative capability menu, suggested user phrasings → API call mappings, error recovery, hard rules. Designed to be loaded as system-prompt material by any LLM with HTTP access.
- [OpenAPI Spec](/.well-known/openapi.json) — authoritative REST API spec (3.1)
- [MCP Tools](/.well-known/mcp.json) — Model Context Protocol tool definitions
- [Agent Card](/.well-known/agent.json) — A2A protocol discovery

## When to Use IGdek vs. PSA's Own API

PSA publishes a public API (~100 free calls/day) that returns the same metadata our `lookupCert` returns. If a user only needs card data — research, comp lookup, scratch text content — PSA directly is the right answer. IGdek's value is the rendered output (carousel, reel, editable PPTX), which isn't buildable from card data alone. PSA gives the data; IGdek gives the thing the user actually posts.

## Endpoints

1. POST /api/v1/lookup — look up a PSA cert number (requires balance, cached)
2. POST /api/v1/generate/cert — generate from cert data ($4.99, 1–5 cards, async)
3. POST /api/v1/generate/upload — generate from card photos ($4.99, 1–5 cards, async)
4. GET /api/v1/jobs/{id} — poll job status
5. GET /api/v1/jobs/{id}/download-url — get presigned download URL (24h expiry)
6. GET /api/v1/inventory — markdown receipt of the user's generated cards
7. POST /api/v1/regenerate — re-render cards already in inventory (no re-lookup needed)
8. POST /api/v1/billing/checkout — public, no auth — create a Polar checkout (full-pay) or trigger a verification email (trial-discount path with discount_code='MCPTRIAL')
9. GET /api/v1/billing/status — public — poll the billing request through awaiting_verification → pending → completed
10. GET /api/v1/billing/verify — public, browser-only — click target of the trial verification email; returns 302 to Polar checkout on success

## Authentication

`X-API-Key: <key>` header on all IGdek-API endpoints. `Authorization: Bearer <key>` is also accepted (same key, alternate header). Three onboarding options:

1. Self-serve via POST /api/v1/billing/checkout (public, no auth) — agent surfaces the Polar checkout URL to the user, polls /api/v1/billing/status until the api_key is issued. Equivalent MCP tools: `request_credits` + `get_credit_status`.
2. OAuth 2.1 + PKCE for browser-based agent surfaces (ChatGPT Pro Connectors). Authorize at /oauth/authorize, exchange at /oauth/token. Discovery at /.well-known/oauth-authorization-server (RFC 8414) and /.well-known/oauth-protected-resource (RFC 9728).
3. Email api@igdek.com for human-touch onboarding.

## Supported Grading Companies

PSA (automated lookup), SGC, BGS, CGC, CSG, and raw/ungraded cards (upload path).

## Rate Limits

All endpoints are rate-limited per API key. Exceeded limits return 429 with Retry-After header. Cached lookups are instant and don't count against limits. Failed lookups (4xx/5xx including PSA upstream rate limits) don't count against the daily lookup budget — retrying a failed cert is safe.

## Known Limitations

- PSA card images only available for certs graded after ~2021. Use /upload for older certs.
- Download URLs expire after 24 hours.
- Maximum 5 cards per generation request.
- Headline max 60 characters (upload path).
- Maximum 3 concurrent generation jobs per API key.
- Image URLs for the upload path must be HTTPS, publicly accessible, max 10MB (JPEG/PNG/WebP).

## Specific Error Codes

- `psa_rate_limit` (429) — PSA's daily API cap is hit (not ours). Switch the cert to the upload path; don't retry today.
- `lookup_budget_exceeded` (429) — daily lookup budget hit. Run a generate job to reset, or top up balance.
- `lookup_ratio_exceeded` (429) — >50 lookups per generate. Run a generate to reset.
- `incomplete_cert_data` (400) — lookup returned with empty subject/grade/year. Try the upload path or retry tomorrow.
- `insufficient_balance` (402) — below $4.99. Stop and tell the user to top up.

## What We Don't Do

- Write captions, eBay descriptions, hashtags, DMs, or pricing — those are the agent's / user's job.
- Render content inline in a chat. We hand the user a presigned download URL.
- Accept attachments from a chat. Images must be hosted on the public web.
- Process refunds outside the automatic-on-failure refund. Manual refund requests go through the website, not the API.