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/AgentCreditVault.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: wallet-auth session, G$ payment confirmation, credit ledger, API key creation, request authorization/hold, capture/release, and usage log.
• 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.”
2. Stepper or progress indicator with 4 steps:
   • Connect wallet
   • Buy credits with G$
   • Copy API setup
   • Track usage
3. Main action card changes by state.
4. Small usage/balance card visible after credits exist.

User flows, states and behaviours

Updated MVP architecture decision

Use a backend-first hosted OpenAI-compatible API for the minimal MVP.

Primary MVP flow:

Developer coding tool → hosted backend OpenAI-compatible API → Antseed buyer/network → streamed response

Developer setup shown by the widget:

OPENAI_BASE_URL=https://<backend-domain>/v1
OPENAI_API_KEY=<developer_platform_key>

Important clarification:

• The existing antseed buyer start proxy is not assumed to forward requests to our backend.
• A local branded antproxy wrapper may be added later, but it is not required for this MVP.
• If a local proxy section is included, it must be clearly marked as “optional / coming next” unless a real wrapper command exists.

Primary happy path

1. Visitor opens the AI Credits Widget.
2. Widget asks the developer to connect wallet.
3. After connection, widget shows wallet address and G$ balance.
4. Developer choose one time purchase vs monthly streaming (10% topup vs 20% topup for streaming)
5. Developer enters how much G$ to spend (for the one time purchase or monthly stream if he chose streaming).
6. Widget shows a simple quote:
   • 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
7. Developer confirms “Buy AI credits”.
8. Widget displays pending payment state.
9. When payment is confirmed, widget shows:
   • current AI credit balance
   • generated API key, masked by default
   • copy buttons for API key and setup env vars
10. Developer copies setup into Cursor / Continue / Cline / OpenAI-compatible tool.
11. Widget shows recent usage once requests are billed.

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 API key but 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.
• API key should be masked by default with show/hide and copy action.
• Setup snippets should be copyable.
• Provide copy blocks for at least:
  • generic OpenAI-compatible env vars
  • Cursor/Continue-style base URL/API key configuration text
• Show a plain-English explanation: “You pay with G$; backend handles Antseed settlement underneath.”
• Usage rows should include: model, status, estimated/captured cost, timestamp.
• Request billing language should use hold/capture/release semantics:
  • authorize/hold before request
  • capture after successful billable response
  • release on failed/non-billable response
• 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

[reaworks-ops]

One acceptance layer I would add to this MVP is an AI credits purchase receipt checklist, separate from the UI states. The user should be able to answer: did my G$ payment actually become usable AI credits, and what proof can support/debug it?

For one purchase flow, I’d capture: quote_id, connected wallet/address, G$ amount, backend/operator settlement ref for the Antseed USDC side, API-key/setup issuance id, first OpenAI-compatible request id, credit balance before/after, failure state, and the cure/refund/manual-review rule if payment confirms but credits do not appear. That keeps the protocol unchanged while making the buyer/developer trust boundary explicit.

If GoodDollar wants a small outside support pass, ReaWorks can do a $100 docs/support PR: add a non-normative receipt checklist + UI acceptance copy + one mock JSON fixture for quote_ready -> payment_confirmed -> has_credits. Buyer sends the intended API/usage sample and any settlement field names to avoid exposing secrets; proof is a PR/patch with the checklist and fixture that reviewers can replay against the planned UI states.