AI Credits Widget: buy developer AI credits with G$

[yoniassia]

Short description of the new GoodWidget

Create a minimal AI Credits Widget for the developer persona: a developer buys prepaid AI credits with G$, receives an OpenAI-compatible API key/setup instructions, uses the service from a local AI coding tool, and sees credit balance/usage decrease after successful AI requests.

This issue should define and plan the UI only. The protocol should remain unchanged for MVP: G$ is the user-facing checkout currency, while the backend/operator handles Antseed USDC settlement underneath.

Which repos and packages the AI should work with

Primary UI repo:

• GoodDollar/GoodWidget

Backend / smart-contract reference repo:

• GoodDollar/antseed-integration
  • Agents should read AGENTS.md in that repo before using it as a backend/contracts reference.
  • Use README.md, docs/ARCHITECTURE.md, docs/PAYMENT_FLOW.md, and backend/README.md as the source of truth for the API/payment boundary.
  • Relevant backend/API package: backend/ Cloudflare Worker.
  • Relevant contracts package: contracts/ Foundry project, especially contracts/src/AntseedBuyerOperator.sol and contracts/src/CeloGdAntSeedVault.sol.

Expected GoodWidget package scope:

• Create a new widget package under packages/ai-credits-widget/ (suggested package name: @goodwidget/ai-credits-widget).
• Use existing shared packages:
  • packages/ui for primitives, tokens, cards, buttons, input-like controls, badges/alerts where available.
  • packages/core for GoodWidgetProvider, wallet context, EIP-1193 integration, and host/runtime boundaries.
  • packages/embed for web-component export if the widget follows the claim-widget embedding pattern.
• Use packages/claim-widget as the closest package structure/reference for a publishable widget.
• Add Storybook stories under the widget-specific Storybook folder, following the repository conventions.
• Add Playwright smoke tests under tests/widgets/ai-credits-widget/ with screenshot evidence for the main states.

External/backend contract for this UI spec:

• Use GoodDollar/antseed-integration as the backend + smart-contract reference.
• Treat backend APIs as mocked/fixture-backed for this issue unless a real endpoint is explicitly provided later.
• The backend is expected to own: G$ payment confirmation, credit/bonus ledger, request stream bonus
• The widget should not implement Antseed protocol settlement directly.
• The widget should expose backend/API integration points cleanly, but implementation should remain fixture-driven until a deployed Worker URL/config is provided.

UI implementation reference

No screenshots are provided. Implement using existing GoodWidget visual language and package conventions:

• Use packages/claim-widget as the reference for widget package structure, provider usage, wallet-aware flow, theming support, and embeddable surface.
• Use packages/ui components/tokens/themes instead of custom hardcoded styling.
• Keep the MVP visually simple: one compact card-based flow, clear primary CTA, status badges, and copyable setup snippets.
• The widget should be suitable for embedding in a developer onboarding page or rendered as a standalone mini-app.

Suggested screen structure:

1. Header/hero card: “Use G$ to power your AI coding tools. get up to 20% more credits when buying with G$s”
2. Stepper or progress indicator with 8 steps:
   • Connect wallet
   • Generate random buyer private key or allow user to paste one (explain what buyer is and security considerations)
   • if generated, force user to copy private key. then confirm with user that he saved it.
   • Ask user if he agrees to make us the operator for the buyer (sign in background using buyer key)
   • Buy credits with G$
     • optional single deposit - if buyer balance on base is 0 this needs to be at at least 1$ worth of G$s (to meet minimum first deposit on base) (for 10% bonus)
     • optional monthly stream - at least 1$ worth of g$s per month (for 20% bonus)
     • show user total credits after bonus
     • at least 1 of single deposit or monthly stream should be filled
   • Deposit received on celo
   • Credits distributed on base
   • Show basic usage guide (ie how to install ant seed and put the buyer key)
3. Main action card changes by state.
4. Small usage/balance card visible after credits exist.
5. deposit/usage history

User flows, states and behaviours

Primary happy path

1. Visitor opens the AI Credits Widget.

2. Widget asks the developer to connect wallet.

3. Show checkmark "eligibile for 20% bonus" if wallet verified, if not "get verified to be eligible for 20% bonus" (link to identity verification)

4. After connection, widget shows wallet address and G$ balance.

5. Developer choose buy credits.

6. • Generate random buyer private key or allow user to paste one (explain what buyer is and security considerations) - if generated, force user to copy private key. then confirm with user that he saved it.
   • Ask user if he agrees to make us the operator for the buyer (sign in background using buyer key and submits to backend)
   • Buy credits with G$
     • optional single deposit - if buyer balance on base is 0 this needs to be at at least 1$ worth of G$s (to meet minimum first deposit on base) (for 10% bonus)
     • optional monthly stream - at least 1$ worth of g$s per month (for 20% bonus)
     • show user total credits after bonus
       • G$ amount
       • estimated AI credit value (highlight extra topup amount)
       • estimated credit value per month of chose streaming
       • note that Antseed settlement happens underneath via backend/operator capacity
     • at least 1 of single deposit or monthly stream should be filled
     • Developer confirms “Buy AI credits” (execute buy tx)
   • Deposit received on celo
   • Credits distributed on base
   • Show basic usage guide (ie how to install ant seed and put the buyer key)

7. When payment is confirmed, widget shows:

   • current AI credit balance
   • copy buttons for buyer key
   • antseed guide/setup

8. Developer copies setup into Cursor / Continue / Cline / OpenAI-compatible tool.

9. Widget shows recent usage once requests are billed.

10. Faq: what is antseed, how to get help, how to withdraw credits, what is operator, what is buyer, how to setup antseed for devs, how to use in antstation, antseed channels

Required states

• disconnected: wallet not connected; primary CTA is connect wallet.
• connected_empty: wallet connected, no credits yet; show G$ balance and buy form.
• quote_ready: amount entered; show estimated credits and confirm CTA.
• payment_pending: payment submitted/being confirmed; disable duplicate submit.
• payment_confirmed: credits minted/assigned; show API key and setup instructions.
• has_credits: show balance, setup snippets, and usage log.
• usage_empty: credits exist but no AI requests yet.
• usage_active: show last requests with status/cost/model/timestamp.
• insufficient_g_balance: entered amount exceeds wallet G$ balance.
• insufficient_ai_credits: developer has no remaining credits; show top-up CTA.
• payment_failed: show retry CTA and non-destructive error message.
• backend_unavailable: show degraded state; do not claim payment succeeded.
• unsupported_chain: show instruction to switch to supported network.

Required UI behaviours

• Keep the first version minimal and linear; do not build a marketplace, provider selector, seller dashboard, or org/team billing.
• Setup snippets should be copyable.
• Provide copy blocks where relevant
• Show a plain-English explanation: “You pay with G$; backend handles Antseed settlement underneath.”
• Usage rows should include: model, status, estimated/captured cost, timestamp.
• Do not expose USDC/channel complexity to the developer in the main flow.
• Do not imply native G$ seller settlement in MVP.

Storybook scenarios required

Create stories for at least:

• Disconnected initial state
• Connected with zero credits
• Quote ready
• Payment pending
• Payment confirmed with API key/setup visible
• Has credits with empty usage
• Has credits with recent usage rows
• Insufficient G$ balance
• Payment failed
• Backend unavailable
• Unsupported chain

Use the repository’s wallet fixtures where relevant:

• examples/storybook/fixtures/custodialEip1193.ts
• examples/storybook/fixtures/injectedEip1193.ts

Out of scope for this MVP issue

• Real backend implementation
• Native Antseed protocol changes
• Native G$ seller settlement
• Running a fully funded Antseed buyer node locally per developer
• Marketplace/provider-selection UI
• Subscriptions
• Organization/team billing
• Custom IDE plugin
• Multi-chain checkout UX beyond one supported G$ payment network

Create the plan

Based on the above description create an execution plan in a new sub-issue and preserve the original issue content unchanged.
Do not execute the plan until given instructions to do so.

Sub-issue requirements:

• Title format: [DRAFT][PLAN] <what issue is being planned>
• Type: Task
• Description must start with: [DRAFT] <sub-issue title>
• Link the sub-issue back to this parent issue.

Instructions when creating the plan:

• Map relevant files that are too be used as reference from all repos mentioned, including GoodDollar/antseed-integration/AGENTS.md, README.md, docs/ARCHITECTURE.md, docs/PAYMENT_FLOW.md, backend/README.md, backend/src/types.ts, backend/src/pricing.ts, and the vault contracts under contracts/src/
• import existing @GoodDollar packages
• Map new components that should be created. Assess when a new component should be created in the new savings widget package or made part of the reusable packages/ui

Plan specification required sections:

• Required states, flows, and behaviors
• Execution plan
• acceptance criteria
• human-reviewer checklist