kite

Imported from Zyaxxy/kite (AGENTS.md). Install upstream with npx skills add Zyaxxy/kite. Copyright stays with the author.

AGENTS.md

Project: Kite (Non-Custodial Neo-Brokerage on Solana)

Kite is a self-custody interface for tokenized equities on Solana. It offers 12 curated thematic stock baskets (e.g. SOL-MAG7, SOL-AI, SOL-CHIPS), automated non-custodial recurring investing (SIP / DCA) via Solana Subscriptions and the on-chain kite_guard Anchor program, deep stock research (1-year charts, technicals, fundamentals, news, corporate actions), and real-time market breadth and sentiment — all without holding user funds in any vault.

Both a paper-trading sandbox ($10,000 virtual USD) and wallet-approved mainnet trading are supported. Web and mobile share a single SDK.

Target: Solana Foundation $100,000 Tokenized Stocks Hackathon (Deadline: Friday, 18 September, 4:00pm ET).

Workspace Architecture

kite/
  ├── apps/
  │   ├── web/                     # Next.js 15.5 App Router dApp (Privy + Wallet Adapter, Tailwind CSS)
  │   └── mobile/                  # React Native / Expo dApp (MWA on Android, Privy web flow on iOS)
  ├── packages/
  │   ├── sdk/                     # Shared TypeScript SDK (@kite/sdk) — markets, baskets, paper, research, trading, recurring
  │   └── anchor/                  # Solana smart contract: kite_guard (on-chain execution guard for recurring investments)
  ├── docs/                        # Architecture docs, protocol security, deployment readiness, trading setup
  ├── package.json                 # Monorepo workspaces root (pnpm 10.31.0)
  └── turbo.json                   # Build orchestrator (Turborepo)

Environment & Tooling

• Node.js: v24.12.0, pnpm: 10.31.0 (pinned lockfile)
• Web: Next.js 15.5, Tailwind CSS, @solana/wallet-adapter-react, Privy for email/social sign-in
• Mobile: Expo / React Native, @solana-mobile/mobile-wallet-adapter-protocol (Android MWA), Privy web flow (iOS/Expo web)
• Smart Contract: Anchor framework (packages/anchor), program kite_guard (8Fm9HENPAFnyo6L8cHJFx62HHsZ6ez6CPUDuzgKAzrjs); V2 CPI implementation requires a separate devnet upgrade
• Transaction Format: Solana V1 transactions composed via Jupiter Swap V2 build API. No ALTs for new transactions.

Key Commands

# Build shared SDK (required before web/mobile)
pnpm build:sdk

# Run web dApp locally (http://localhost:3000)
pnpm dev:web

# Run mobile app locally
pnpm dev:mobile

# Build web for production
pnpm build:web

# Build Anchor smart contract
pnpm build:anchor

# Run Anchor tests
pnpm test:anchor

# Run SDK tests
node --test packages/sdk/test/*.test.cjs

Core Product Features

1. Dual Trading Modes

• Paper Trading: Every device starts with $10,000 virtual USD. Simulates buys, sells, basket orders, stock-to-stock swaps, and recurring plans at live reference prices. Device-local, never backfills missed intervals. Not a forecast.
• Actual Trading: Non-custodial mainnet via connected Solana wallets (Phantom, Solflare) or Privy embedded wallets. Quotes and executes V1 transactions through Jupiter.

2. Thematic Stock Baskets (12 curated)

Baskets are allocation definitions, not synthetic tokens. Buying a basket delivers individual tokenized equities directly to the user's wallet via a single atomic V1 transaction. Equal-weight allocation using the Largest Remainder Method (Hare-Niemeyer) in BigInt arithmetic — zero dust leakage. If any constituent is missing or unpriced, the basket is marked unavailable.

3. Recurring Investing (SIP / DCA)

• Paper: Local plans with configurable cadence (daily/weekly/bi-weekly/monthly). Runs due installments only while the app is open.
• Devnet — Kite Guard V2: Stock/basket plans delegate to a plan PDA through official Solana Subscriptions. Guard atomically collects, swaps through official Raydium devnet CPMM, and verifies delivery to owner ATAs. Collectors only pay fees. Owner-approved pools/minimum outputs are fixed; failed legs roll back the installment. Test tokens and pools must be provisioned separately. Mainnet wallet recurring is disabled. See docs/kite-guard-protocol.md.

4. Stock Research Suite (5-tab panel)

• Overview: 1-year daily OHLCV chart (Yahoo Finance), interactive SVG scrubber, period selectors (1M/3M/6M/1Y), day and 52-week range bars, company profile (Wikipedia + Yahoo Finance).
• Technicals: SMA 20/50/200, RSI-14, 20-day average volume, trend badge.
• Fundamentals: Annual/quarterly — revenue, gross profit, operating income, net income, cash flows, EPS, margins. Historical revenue bar chart.
• News: Real-time stock-specific Google News RSS feed.
• Events: Dividends, splits, SEC filings.

5. Market Pulse (Real-Time Breadth & Sentiment)

Real advancing/declining/unchanged asset counts with a visual breadth bar. 24h trading volume. Top mover leaderboards (volume, gainers, losers). No fabricated sentiment scores.

6. Portfolio, Activity & Watchlist

Holdings breakdown with cost basis and unrealized PnL. Order activity log. CSV export. Bookmarkable watchlist with live pricing.

Issuer & Market Data Sources

• xStocks (https://api.xstocks.fi): Public US equities and ETFs as Token-2022/SPL tokens on Solana mainnet.
• PreStocks (https://prestocks.com): Pre-IPO private company exposure. Paused/withdrawn listings are flagged.
• Jupiter: Token market prices (tokens-v2, price-v3 APIs), swap routing (Swap V2 build API).
• Yahoo Finance: OHLCV historical bars, fundamental timeseries, company metadata.
• Wikipedia API: Company profile descriptions.
• Google News RSS: Market and stock-specific headlines.
• Pyth Network: Real-time equity oracle feeds (reference price comparison).
• Solscan: On-chain explorer links for mints and transactions.

No charts, sentiment, or news are manufactured. Missing prices fail closed as "unavailable."

API Surface (apps/web/app/api/)

Secrets remain on the web server; only public app IDs and RPC config are in NEXT_PUBLIC_* / EXPO_PUBLIC_* variables.

Code Guidelines & Standards

TypeScript / Frontend (apps/web, apps/mobile, packages/sdk)

• Write modular, strictly-typed TypeScript without any where possible.
• Shared business logic, types, and oracle helpers MUST live in packages/sdk so both web and mobile share a single source of truth.
• Web uses @solana/wallet-adapter-react and dynamic imports for wallet modal components to prevent SSR hydration mismatches.
• Mobile uses @solana-mobile/mobile-wallet-adapter-protocol for non-custodial signing with Phantom, Solflare, or Seed Vault on Solana Saga / Seeker.
• No fabricated data — missing values render as "unavailable" rather than synthetic fallbacks.

Anchor / Smart Contract (packages/anchor)

• Program: kite_guard — Anchor 1.2; V2 must be deployed separately.
• PDA pattern: [b"plan_v2", owner_pubkey, funding_mint_pubkey, nonce_u64_le].
• Instructions: create_plan_v2, execute_swap_v2, close_plan_v2, protocol_version. Legacy create/execute reject; legacy close retains rent recovery.
• Invariants: weights total 10,000 bps, max 20 assets subject to transaction limits, cadence at least 60s, duration at most 365 days, immutable owner destinations/pools/output floors. Devnet only.

Primitives & Protocols

• Jupiter: Atomic multi-leg swaps using the Swap V2 build API. Token prices via tokens-v2 and price-v3.
• Solana Subscriptions: Official program (De1egAFMkMWZSN5rYXRj9CAdheBamobVNubTsi9avR44) bounds the devnet plan PDA delegation. The Guard PDA, not a keeper wallet, signs collection CPI.
• Kite Guard: V2 collects and swaps atomically via Subscriptions and Raydium devnet CPMM. The transient plan ATA must return to its starting balance; all outputs go to the owner. No cron worker or mainnet recurring deployment is included.
• Pyth Network: Real-time equity oracle feeds for underlying share price references (@pythnetwork/pyth-solana-receiver).
• SPL Token / Token-2022: Direct wallet holdings. No synthetic basket mint or Kite vault. Reject unsupported extensions rather than bypassing their checks.
• Privy: Email/social sign-in with embedded Solana wallet creation. Secrets server-side only.

Key Design Principles

• No Kite Vault: Tokens go directly to the user's wallet. No counterparty risk.
• No Fabricated Data: All market data, charts, sentiment, and news are sourced from verifiable external providers.
• Fail-Closed: Missing prices, unresolved issuers, or halted assets block trading rather than allowing degraded execution.
• Self-Custody by Design: Wallet-approved transactions only. Users can revoke delegations and reclaim rent at any time.

Reference Documentation

• Kite Guard Protocol — Smart contract architecture
• V2 Architecture & Roadmap — Composable brokerage milestones
• Mainnet Data — Issuer endpoints and data pipeline
• Mainnet Trading — Trading setup, environment variables, limitations
• Deployment Readiness — Deployment and rollback verification
• Stock Research — Research suite architecture
• Wallet Swaps — Swap execution details
• Protocol Security — Security model