Solana Payments (USDC)

Sign in at marrowstack.dev, open the Solana Payments block, and click Copy all files. Paste lib/solana-payments.ts (~500 lines) into your project. Exports:

• createPaymentRequest() — generates a reference keypair and a payment URI
• verifyPayment() — 6-point on-chain verification (confirmed, recipient, amount, mint, reference, unexpired)
• PaymentButton — React component (wallet adapter required)
• usePaymentStatus() — polls for payment confirmation
• withPaymentGate() — optional x402 pay-per-request middleware
• SQL migration: payments and subscriptions tables

• Next.js 14 or 15, App Router
• Supabase project
• A Solana treasury wallet (the public key that receives USDC)
• A mainnet-beta RPC endpoint (Helius, QuickNode, or similar)
• Wallet adapter (if using the PaymentButton component)

1. Copy the file from the block detail page and paste it into lib/solana-payments.ts.
2. Remove @ts-nocheck from line 1.
3. Install peer dependencies:

npm install @solana/web3.js @solana/spl-token bs58
# If using PaymentButton (wallet adapter):
npm install @solana/wallet-adapter-base @solana/wallet-adapter-react \
    @solana/wallet-adapter-react-ui @solana/wallet-adapter-wallets

Run the MIGRATION constant from solana-payments.ts in Supabase SQL Editor.

Creates:

• payments — reference key, amount, status, tx signature, idempotency guard
• subscriptions — optional recurring payment scaffold with renewal tracking

RLS on both tables: service role has full access; anon is blocked.

Create a payment request (server-side):

import { createPaymentRequest } from '@/lib/solana-payments'
import { NextRequest, NextResponse } from 'next/server'

export async function POST(req: NextRequest) {
  const { amount, userId } = await req.json()
  // amount is in USDC (e.g. 49 for $49)
  const payment = await createPaymentRequest({
    amount,
    userId,
    description: 'MarrowStack block purchase',
  })
  // payment.referenceKey — unique key for this payment
  // payment.paymentUri   — Solana Pay URI for QR codes
  // payment.expiresAt    — ISO timestamp
  return NextResponse.json(payment)
}

Verify payment (server-side, called after buyer pays):

import { verifyPayment } from '@/lib/solana-payments'
import { NextRequest, NextResponse } from 'next/server'

export async function POST(req: NextRequest) {
  const { paymentId, txSignature } = await req.json()
  const result = await verifyPayment({ paymentId, txSignature })
  // result.verified — boolean
  // result.error    — string if verification failed
  if (!result.verified) {
    return NextResponse.json({ error: result.error }, { status: 422 })
  }
  // Mark order as paid, trigger delivery, etc.
  return NextResponse.json({ ok: true })
}

Drop in the PaymentButton (client-side):

'use client'
import { PaymentButton } from '@/lib/solana-payments'

export default function CheckoutPage({ paymentUri }: { paymentUri: string }) {
  return (
    <PaymentButton
      paymentUri={paymentUri}
      onSuccess={(txSig) => fetch('/api/payment/verify', {
        method: 'POST',
        body: JSON.stringify({ txSignature: txSig }),
      })}
      onError={(err) => console.error(err)}
    />
  )
}

1. Call createPaymentRequest({ amount: 1, userId: 'test' }) in a test route. Confirm a row appears in the payments table with status pending.
2. Use the devnet playground to test the full payment flow before spending real USDC on mainnet.
3. On mainnet: send the exact USDC amount to the treasury address and callverifyPayment() with the tx signature. Confirm thepayments row transitions to verified.
4. Attempt to verify the same tx signature a second time.verifyPayment() must return { verified: false, error: 'Already processed' } (idempotency guard).

What this block guarantees:

• 6-point on-chain verification: confirmed finality, exact recipient, exact amount (within tolerance), correct USDC mint, unique reference key, within expiry window.
• Reference keys are single-use. The payments table has a unique constraint on reference keys — double-payment is rejected.
• Verification runs server-side. The client submits a tx signature; the server does not trust the client's claim that payment was made.
• All verification happens before any value is delivered. Never deliver before verifyPayment() returns verified: true.

What you must ensure:

• Verify payment server-side before delivering value — this is the most important rule. Call verifyPayment() in your API route, not on the client.
• Set SOLANA_CLUSTER=mainnet-beta. Never use devnet config in production.
• Keep TREASURY_WALLET_ADDRESS and SUPABASE_SERVICE_ROLE_KEY server-side only.
• Use a dedicated RPC endpoint in production. Public endpoints are rate-limited and unreliable under load.
• Display the USDC mint address to users so they can verify they are sending the correct token.