Solana Faucet API

Small Express API that drips testnet SOL to GitHub-authenticated users. Built for the Pine Stake testnet faucet.

How it works

Users log in with GitHub (OAuth code exchange, no external auth provider), then request SOL to a wallet address. Requests are rate-limited per GitHub account with an 8h cooldown, and gated behind a Cloudflare Turnstile check.

Endpoints

• POST /auth/github/callback — exchanges a GitHub OAuth code for a session cookie (JWT)
• GET /me — returns the logged-in user
• POST /auth/logout — clears the session cookie
• POST /faucet — sends SOL to address (requires login + cfToken from Turnstile)
• GET /faucet-status — cooldown left for the logged-in user
• GET /faucet-balance — current faucet wallet balance and total distributed

Allowed amounts per request: 1, 2, 5 or 10 SOL.

Setup

npm install
npx prisma generate
npx prisma db push
npm start

Environment variables

DATABASE_URL=          # postgres connection string
FRONT_URL=             # frontend origin, used as GitHub OAuth redirect_uri
ALLOWED_ORIGINS=       # comma-separated list of origins allowed by CORS
RPC_URL=               # Solana RPC endpoint (defaults to testnet)
SENDER_SECRET_KEY=     # base58 secret key of the faucet wallet
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
SESSION_SECRET=        # used to sign the auth JWT
TURNSTILE_SECRET_KEY=

Stack

Express, Prisma/Postgres, @solana/web3.js, jose for JWTs.