# Skooby implementation and launch guide

Prepared September 12, 2026. Main website: [skooby.app](https://skooby.app). The code is complete for the features described below; some provider-backed features remain disabled pending account configuration and verification. No account approval, crypto purchase or real-money casino is implied by a successful code build.

## 1. Choose the application you are running

| Folder | Purpose | Runtime |
| --- | --- | --- |
| Website root | Existing Skooby tracker, research, memberships, pages and wallet payments | Sites / Vinext / Cloudflare Workers / D1 |
| `examples/web3-starter` | Standalone Web2-to-Web3 app with Privy, Wagmi, Viem and Pinata | Next.js App Router / Node |
| `examples/transak-broker` | Private service that creates Transak purchase sessions | Node 22.13+ behind HTTPS, approved fixed outbound IP, Upstash Redis |

The standalone starter is a real Next.js app. The live Skooby website uses a Next-compatible edge runtime and its existing Sites account identity. These are separate applications, not interchangeable deployment folders. Social login in the starter does not grant a paid Skooby membership.

The complete source download includes these folders, the UI assets, routes, tests, example configuration and this guide. It excludes real secrets, dependencies, build output and the original hosting project identifier. The original source remains attached to the existing Site. Do not deploy a new copy against an existing production account database until identity and migration behavior are reviewed.

## 2. What is already operating, and what still needs activation?

| Feature | Implemented behavior | Activation status |
| --- | --- | --- |
| Homepage and funnel | Responsive van scene, tracker, 16 original articles, landing pages, two companion tools | Published |
| Search memberships | Seven-day eligible trial; $14.99/month Search | Stripe configured; uncompleted Checkout Sessions validated |
| AI memberships | $24.99/month Follow, $49.99/month All Features; server quotas | Closed until AI credentials, credits, checks and `AI_ENABLED=true` |
| ChainGPT | Server adapter with bounded input/output and history disabled | Account credentials and live check required |
| Crypto APIs | Confirmed native balance lookup on configured supported networks | Account key and network coverage check required |
| Wallet Pay | Compatible installed Coinbase Wallet, MetaMask and Rainbow; native ETH/POL preview and wallet authorization | Code published; no payment sent in validation |
| Privy and token gate | Email/Google/wallet login, embedded wallets, ERC-721/ERC-20 checks | Runnable starter; Privy app and real token contract required |
| Public IPFS | Authenticated, size-limited text/JSON upload with quota | Runnable starter; Pinata and Redis configuration required |
| Crypto purchases | Authenticated signed session route, fee disclosure and private broker | Disabled until partner approval, fee, payout and infrastructure setup |
| Casino Lab | Free browser blackjack with no deposits, wagers or prizes | Published; no real-money operator hosted |

## 3. Run the standalone Web3 application

Extract the starter or enter `examples/web3-starter`. Use Node 22.13+:

```bash
npm install
cp .env.example .env.local
npm run typecheck
npm run dev
```

The main toolkit guide includes the exact fresh-app initialization command and all five requested code modules. Its dependency set is pinned: Next 16.3.4, React 19.2.6, Privy React 3.42.0, Privy Wagmi 4.0.17, Wagmi 3.7.7 and Viem 2.56.0. Keep the lockfile generated by your package manager. When running nested commands from a pnpm workspace, use the standalone folder and `pnpm --ignore-workspace` to avoid modifying the parent application.

### Provider setup

1. Open the [Privy dashboard](https://dashboard.privy.io) and sign into your developer account. Browser inspection in this work session reached an email login form; no account sign-in or app creation was completed.
2. Create or select the Skooby development application. Enable email, Google and wallet login. Configure Google OAuth as instructed by the dashboard. Enable embedded Ethereum wallets and required external wallets.
3. Add the exact development origin and your separate Web3 deployment's HTTPS origin to Privy's allowed domains. Set public `NEXT_PUBLIC_PRIVY_APP_ID` and server-only `PRIVY_APP_SECRET`.
4. Choose Base or Polygon. Set `NEXT_PUBLIC_CHAIN`, public browser RPCs and the matching server `RPC_URL`. Public RPC keys must be restricted; server secrets never belong in `NEXT_PUBLIC_*` variables.
5. Set a real deployed `NEXT_PUBLIC_GATE_CONTRACT`, `NEXT_PUBLIC_GATE_STANDARD=erc721` or `erc20`, and a positive token minimum. Do not deploy a token or NFT just to satisfy the example unless that is a separately approved product decision.
6. Configure a scoped Pinata JWT, gateway hostname and Upstash REST URL/token. Use development accounts first. The upload route stays unavailable without durable quota storage.

### How the code fits together

| File | Responsibility |
| --- | --- |
| `src/components/Web3Provider.tsx` | Privy → per-mount QueryClient → Privy-aware Wagmi; Base and Polygon |
| `src/components/ConnectButton.tsx` | Login modal, wallet readiness, active wallet selection and logout |
| `src/components/TokenGate.tsx` | User-facing balance preview, loading/error states and protected API request |
| `src/lib/auth.ts` | Privy access-token verification and authoritative linked-wallet ownership |
| `src/lib/gate.ts` | Server RPC chain verification, same-block balance and decimals reads |
| `src/app/api/exclusive/route.ts` | Rechecks identity and token eligibility before returning private content |
| `src/components/IpfsUpload.tsx` | FormData upload with explicit public-publication consent |
| `src/app/api/upload/route.ts` | Server-only Pinata JWT, file validation, body limits and quota |
| `src/lib/upload-quota.ts` | Atomic per-user daily allowance backed by Redis |

The client is not an authorization boundary. Always verify the access token, linked wallet and chain balance on each protected endpoint. A wallet address supplied by the browser is not proof of ownership. Already delivered content cannot be recalled when tokens move.

### Deploy the starter

Use a host that supports Next.js App Router Node server routes; a static-only host cannot run the token gate or upload API. Set server secrets through the host's secret manager. Set `APP_ORIGIN` to the exact deployed HTTPS origin. Public `NEXT_PUBLIC_*` configuration is compiled into the client, so rebuild after changing it.

```bash
npm run typecheck
npm run build
npm start
```

A production build has been checked locally with the installed SDK types. Real login, wallet linking, RPC token ownership and Pinata uploads still require your provider configuration. Test rejected signatures, expired login, a wallet belonging to another user, wrong-chain RPC, insufficient tokens, six-decimal ERC-20s, oversized files and missing public consent before launch.

To migrate the live Skooby member identity to Privy later, use an explicit account-linking migration: authenticate the existing member, verify the Privy identity server-side and attach a unique mapping in D1. Never merge accounts solely because the client supplies an email address. Preserve existing Stripe customer/subscription ownership and trial start dates. This identity migration is not silently performed by the starter.

## 4. Activate AI and chain balances on Skooby

For ChainGPT, choose the provider explicitly and keep sales closed while verifying:

```dotenv
AI_PROVIDER=chaingpt
CHAINGPT_API_KEY=SET_IN_SERVER_SECRET_MANAGER
AI_ENABLED=false
```

Use `scripts/verify-provider.mjs` from a protected development environment. The ChainGPT check makes one real model request and consumes provider credits; it never prints credentials or model output.

```bash
node --env-file=.env.local scripts/verify-provider.mjs chaingpt
```

Then test the member research flow with development access, including exhausted daily quota, failed upstream requests and questions containing untrusted text. Set the provider's budget and alert limits. Only after successful verification, set `AI_ENABLED=true` in the Site's runtime settings and publish. A key alone cannot open AI subscriptions. Changing providers does not send a failed request to a second company automatically.

For Crypto APIs, set the server-only `CRYPTOAPIS_API_KEY`, plus `CHECK_ADDRESS` and `CHECK_CHAIN` in your local check environment. Run:

```bash
node --env-file=.env.local scripts/verify-provider.mjs cryptoapis
```

Repeat for Ethereum, Base and Polygon as supported by your purchased API plan. Confirm the result is a confirmed native balance; it does not represent complete ERC-20/NFT holdings. The live route enforces Search access and a 30-attempt daily allowance. Account-specific schema/coverage has not been verified without a key.

## 5. Membership billing

The production Stripe catalog contains Search at $14.99, Follow at $24.99 and All Features at $49.99 per month in USD. The eligible seven-day trial can begin without a card. A separate Checkout authorization starts recurring membership billing after the remaining trial. The final 48 hours of the local trial defer checkout until expiration rather than charging early.

Server environment settings are listed in the root `.env.example`. Production Stripe values have already been configured outside source control. `STRIPE_BILLING_ENABLED` is the billing switch. AI plan checkout additionally requires `AI_ENABLED` and the selected provider key. Card, Link and eligible Cash App Pay are configured in Skooby's payment method configuration. Cash App availability is subject to Stripe and customer eligibility.

The webhook at `/api/stripe-webhook` validates Stripe's signature and reconciles canonical subscription state. Checkout completion alone does not grant arbitrary access; ownership and the actual subscription are verified. Account cancellation opens the configured Stripe billing portal. Do not replace those checks with a client success URL or a Cash App screenshot.

Validation to date: three live Checkout Sessions were created and expired without completing a payment. This does not constitute a completed customer renewal, failed-payment or cancellation test. Complete those lifecycle checks in an isolated Stripe test setup before relying on them operationally. Rotate the Stripe secret previously shared in chat through a secure owner-controlled flow and update the hosted secret; never paste replacement credentials into this guide or public code.

## 6. Enable optional crypto purchases

The code now includes the actual `/api/purchase-session` route and `examples/transak-broker`; see that folder's complete README. Do not enable the route by adding a direct legacy query-string widget link.

The route authenticates the member, validates USD amounts using integer cents, checks explicit consent and reserves a daily request allowance. It sends an HMAC-signed request to the private broker. The broker enforces a timestamp window, single-use nonce, exact originating domain, valid client IP, global quota and coordinated token refresh. Returned links must use the exact production Transak host.

Activation requires your Transak partner approval, verified stablecoin payout details, the agreed fee, allowed frontend domain, approved static outbound IPs, trustworthy client-IP forwarding and production API credentials. Those are account and infrastructure requirements, not code placeholders. The broker has a container recipe and local verification suite but has not been provisioned or connected to a real provider account.

After staging validation, configure the production broker and Site environment exactly as its guide specifies. The source defaults to `ONRAMP_ENABLED=false`; only enable it after a correct production quote is observed. The public Skooby route rejects staging widget URLs.

The 2% calculator illustrates $1 on $50 or $2 on $100. It cannot guarantee a fixed $1–$2 minimum. Configure the agreed commission in the provider dashboard and reconcile earned revenue from provider order records. The current code does not automatically book commissions, submit orders or collect a separate Stripe crypto fee. `$swerveoff` is not a stablecoin payout address.

## 7. Wallet payments and Casino Lab

`/pay` supports installed wallets that advertise EIP-6963. The user connects, enters and separately verifies the full recipient, previews the chain/amount/estimated execution fee and explicitly requests wallet authorization. Transfer Check rejects address mismatch, invalid checksum, known burns, wrong network, unsupported precision and coded recipients. It cannot guarantee ownership, reputation, total L2 fees or successful execution. No payment was sent while testing.

The downloadable Privy app adds social login and mobile/external wallet connections after configuration; it does not link Skooby to the owner's Coinbase exchange account or settle research subscriptions in crypto.

`/casinos` is free browser blackjack. Real-money casino operation, deposits, withdrawals and operator embeds remain outside the activated product. A licensed operator agreement, jurisdiction controls and an appropriate payment provider would be required for a separate implementation. Do not connect gambling payments to these Stripe research memberships.

## 8. Publish, verify and maintain the existing Site

The existing application uses Sites hosting, D1 migrations and a public audience. Continue editing the existing project instead of creating another copy just to publish a change. Use the Sites build and hosting workflow, and retain the current domain/audience. The downloadable source intentionally omits the existing project identifier so an imported copy cannot accidentally target that project.

Useful local checks:

```bash
pnpm exec tsc --noEmit
node tests/core.mjs
node --test examples/transak-broker/broker.test.mjs
pnpm build
```

The broker tests use mocked provider responses. They cover signed requests, replay, wrong origin/IP, precision limits, encrypted caching, restart reuse, concurrent refresh, redirect validation and storage failure. They are not a provider approval or live purchase test. Use separate secrets and databases for any staging copy.

Back up account data using your hosting provider's supported export process before schema migrations. Monitor webhook failures, upstream availability and spending limits. Clear operational logs of authorization headers, signed checkout URLs and raw private inputs. Do not run the Sites header-based identity code behind an untrusted host that accepts arbitrary identity headers.

## 9. Domains and discovery

`https://skooby.app` is canonical; `koobycrypto.com` is configured to forward to it while retaining path and query. Retain HTTPS on both names. If moving hosting, preserve that permanent redirect and verify it through the registrar/host's domain configuration before cutover.

Sitemap, robots, canonical, Open Graph and Twitter metadata are implemented. Original blog content and free calculators form the organic funnel. Submit the canonical sitemap to an owner-verified Search Console property and monitor indexing; metadata and extra domains do not guarantee rank. No dark-web pages, unsolicited promotional posts or backlink campaigns were published.

## 10. Disable a service safely

- AI: set `AI_ENABLED=false`, publish and review affected subscribers through billing support.
- Purchase links: set `ONRAMP_ENABLED=false` and publish; stop broker ingress for immediate suspension. Previously authorized provider orders are not canceled by this switch.
- New subscriptions: set `STRIPE_BILLING_ENABLED=false` and publish. This does not cancel existing recurring subscriptions; manage them through Stripe.
- Uploads: remove or revoke the Pinata upload credential and disable the UI. Existing public IPFS copies may remain accessible elsewhere.

Restore a known working Site version if a release fails, preserving compatible environment settings and database schema. A code rollback alone does not reverse a payment, provider order or database migration.

## Primary implementation references

- [Privy with Wagmi](https://docs.privy.io/wallets/connectors/ethereum/integrations/wagmi)
- [Privy access tokens](https://docs.privy.io/authentication/user-authentication/access-tokens)
- [Viem contract reads](https://viem.sh/docs/contract/readContract)
- [Pinata public file upload](https://docs.pinata.cloud/sdk/upload/public/file)
- [ChainGPT API](https://docs.chaingpt.org/dev-docs-b2b-saas-api-and-sdk/web3-ai-chatbot-and-llm-api-and-sdk/javascript/api-reference)
- [Crypto APIs EVM balances](https://developers.cryptoapis.io/v-2.2024-12-12-175/RESTapis/address-latest-evm/get-address-balance-evm/get)
- [Transak secure sessions](https://docs.transak.com/api/public/create-widget-url)
- [Transak partner revenue](https://docs.transak.com/guides/managing-partner-payouts-and-configuring-partner-fees)