FlexPay

FlexPay is a hackathon MVP SDK for Solana merchants who want to accept payment in any supported token while receiving quoted USDC settlement through Jupiter. It packages the Jupiter quote and swap flow into two entry points:

• @flexpay/core: headless payment orchestration
• @flexpay/react: drop-in checkout widget

The demo app in apps/demo-store shows the intended judging story: connect a wallet, pay with any funded token, and settle the merchant in USDC.

Why It Fits Jupiter Track

• It expands Jupiter into commerce, not trading.
• It uses Jupiter routing as the core infrastructure layer.
• It gives developers a fast integration path with a widget and a headless client.
• It demonstrates a developer-friendly checkout flow on top of Jupiter Swap API V2.

Bounty Fit Status

Current repo status against the prompt:

• Shipped — multi-API composition: Swap V2 (/order + /execute) powers checkout; Tokens v2 supplies wallet metadata and uses isVerified + organicScore to keep spam tokens out of the picker; Price v3 samples the payment mint at quote time and again right before signing, hard-blocking the flow if drift exceeds 150 bps.
• Shipped — production-shaped SDK: headless @flexpay/core, @flexpay/react widget, @flexpay/server proxy, and a Next.js demo app with stage-aware error UX, RPC 403 hardening, and a live DX telemetry panel on the landing page.
• Shipped — judge-ready narrative: /story page with before/after code diffs for every DX friction we hit, plus a /docs submission guide that maps the repo to the judging rubric.
• In flight: Trigger API fallback when volatility blocks a market fill (planned), Recurring + organic-score DCA carts, Lend-backed checkout rails, and AI-stack benchmarking captured in DX-REPORT.md.

DX-REPORT.md is treated as a required deliverable, not optional polish — read it alongside the demo at apps/demo-store and the narrative at /story.

Monorepo Layout

• packages/core: SDK types, token balance reads, quote fetching, swap transaction build, transaction submission
• packages/react: widget, hooks, styles
• packages/server: Express-compatible proxy/router and reusable proxy helpers
• apps/demo-store: Next.js reference storefront

Local Setup

1. Install dependencies:

pnpm install

2. Copy the environment template and set your merchant wallet plus preferred Jupiter endpoints:

cp .env.example .env.local

3. Start the demo app:

pnpm dev

4. Open the demo storefront and connect a funded mainnet Solana wallet.

5-Minute Integration

import { FlexPayWidget } from "@flexpay/react";

export function Checkout() {
  return (
    <FlexPayWidget
      merchantWallet="YOUR_USDC_DESTINATION"
      amount={29.99}
      rpcEndpoint="https://api.mainnet-beta.solana.com"
      jupiterApiKey={process.env.NEXT_PUBLIC_JUPITER_API_KEY}
      onSuccess={(payment) => console.log(payment.signature)}
    />
  );
}

This is the fastest setup. If you want to keep your key server-side, omit jupiterApiKey and pass quoteApiUrl, swapApiUrl, and tokensApiUrl for your own backend routes.

Architecture

flowchart LR
  A["Customer Wallet"] --> B["FlexPayWidget"]
  B --> C["FlexPay Proxy Routes"]
  C --> D["Jupiter Quote API"]
  C --> E["Jupiter Swap API"]
  B --> F["Solana RPC"]
  E --> G["Unsigned Versioned Transaction"]
  G --> A
  A --> H["Signed Transaction"]
  H --> F
  F --> I["Merchant USDC Account"]

Testing

pnpm test
pnpm typecheck

The repo includes unit tests for @flexpay/core, render tests for @flexpay/react, and route tests for @flexpay/server.

Notes

• This MVP follows the legacy Jupiter exact-output flow described in the project brief so the merchant can target a fixed USDC amount.
• The SDK now targets Jupiter Swap API V2 for direct mode and is designed around a mainnet payment flow.
• Jupiter Tokens API V2 requires an API key. Set FLEXPAY_JUPITER_API_KEY in .env.local so the widget can resolve wallet token metadata.
• Direct client-side mode is also supported with NEXT_PUBLIC_JUPITER_API_KEY, but that exposes a browser-usable key to the client.
• Jupiter is effectively a mainnet integration. Devnet SOL and devnet SPL faucet tokens are useful for wallet testing, but not for a real Jupiter payment route.
• The /dashboard page is presentation-only in this MVP. Persisted merchant reporting should be wired through webhook storage or on-chain indexing next.