Getting Started
Introduction
FluxRoute is a Solana-native MCP routing layer for paid AI microservices.
Agents connect through one MCP-facing integration, discover registered provider services, negotiate a per-call payment, and execute the provider request after on-chain verification.
The current implementation includes a Fastify API, service registry, x402-style payment negotiation, SOL and USDC-SPL verification, provider proxying, ledgers, a dashboard shell, an MCP stdio server, and provider SDK helpers.
Getting Started
Quickstart
Run the monorepo locally with Postgres, Redis, JWT keys, and the API.
Install root workspaces, start Postgres and Redis, build packages, run migrations, then start the API, dashboard, MCP server, and landing app as separate processes.
Production uses https://api.fluxroute.xyz for the API and https://dashboard.fluxroute.xyz for the dashboard. Local setup should keep secrets in .env.local and never commit generated keys.
npm install
cd fluxroute-landing && npm install && cd ..
docker compose up -d postgres redis
npm run build:packages
npm run migrate
npm run dev:apiGetting Started
Authentication and API keys
JWT auth protects account routes; generated API keys are shown once and stored hashed.
Email/password registration and login issue RS256 JWTs. API keys are created under authenticated accounts, stored as bcrypt hashes, and revoked through a soft deactivate path.
Wallet authentication verifies a signed nonce message. Nonces are caller-supplied today, so production should add server-issued nonce storage before treating wallet login as hardened.
POST /api/auth/register
POST /api/auth/login
POST /api/auth/api-keys
GET /api/auth/api-keys
DELETE /api/auth/api-keys/:idGetting Started
MCP setup
The MCP stdio server exposes service listing, paid calls, and budget lookup tools.
Configure an MCP client to launch the FluxRoute MCP server with a FluxRoute API key and API URL. The server calls the REST API for discovery, payment negotiation, execution, and budget checks.
{
"mcpServers": {
"FluxRoute": {
"command": "node",
"args": ["apps/mcp-server/dist/index.js"],
"env": {
"FLUXROUTE_API_URL": "https://api.fluxroute.xyz",
"FLUXROUTE_API_KEY": "fr_live_..."
}
}
}
}Core Concepts
Architecture
Vercel serves the public apps; Railway should serve the API, Postgres, and Redis.
The landing and dashboard are separate Next.js apps. The API is a Fastify service with Drizzle/Postgres persistence and Redis payment-status caching.
Canonical production domains are fluxroute.xyz, dashboard.fluxroute.xyz, and api.fluxroute.xyz. Vercel preview URLs are deployment surfaces, not public product URLs.
Core Concepts
Service registry
Providers register HTTPS services with category, pricing, wallet, and endpoint metadata.
Public registry reads list active services and categories. Provider writes require authentication and provider access. Ownership checks guard service updates, deletes, and endpoint creation.
Dashboard registry cards are live API results only. If the API is offline or empty, the dashboard shows an empty/error state rather than fabricated data.
GET /api/services
GET /api/services/categories
GET /api/services/:serviceId
POST /api/services
PUT /api/services/:serviceId
DELETE /api/services/:serviceIdCore Concepts
SOL and USDC-SPL payment flow
Payment negotiation creates a call id; verification binds the transaction memo to that call.
Negotiation returns a 402 response payload with protocol, network, currency, amount, provider wallet, memo/call id, and expiry. Verification checks transaction success, recipient, amount, token mint for USDC, and memo reference.
Execution prevents transaction replay, re-verifies the payment, proxies to the provider HTTPS origin, and records spend/earnings ledgers only after successful provider fulfillment.
POST /api/payments/negotiate
POST /api/payments/verify
GET /api/payments/status/:callId
POST /api/payments/executeSDK and API
Provider SDK
Provider helpers generate payment requirements and Express-style middleware responses.
The SDK helps provider apps return x402-style payment instructions. It does not custody funds or replace on-chain verification by the FluxRoute API.
import { FluxRouteProvider } from "@fluxroute/provider-sdk";
const provider = new FluxRouteProvider({
serviceId: "image-resizer",
priceSol: 0.001,
walletAddress: "So11111111111111111111111111111111111111112",
network: "mainnet-beta"
});SDK and API
API reference
Implemented REST routes are grouped under /api/auth, /api/services, /api/payments, and /api/wallet.
Protected routes accept Bearer JWTs or active FluxRoute API keys, depending on the caller surface. Validation is handled by shared Zod schemas where implemented.
Webhook delivery, hosted checkout, managed wallet key generation, and full dashboard CRUD are not production-complete in this repository and should be treated as roadmap items.
Platform
Security model
Production security depends on strict CORS, RS256 keys, hashed API keys, TLS providers, Redis, and reliable RPC.
The API sets secure baseline headers, enforces Fastify rate limiting, hashes passwords and API keys, rejects insecure provider URLs by default, and stores unique transaction signatures.
After launch setup, rotate shared tokens and add server-issued wallet login nonces before treating wallet login as fully hardened.
Platform
Production checklist
A launch requires DNS, Railway API deployment, migrations, Vercel envs, and smoke tests.
Landing, dashboard, and API domains currently resolve. The Railway API service has Postgres, Redis, JWT keys, Helius Solana RPC, restricted CORS, and migrations configured.
Run lint, typecheck, tests, builds, route smoke tests, API health checks, and browser checks after every production deploy.
npm run lint
npm run typecheck
npm test
npm run build
cd fluxroute-landing && npm run lint && npm run buildPlatform
Troubleshooting
Most production failures show up as unavailable registry data, CORS errors, or failed payment verification.
If the dashboard registry is empty with an API error, verify NEXT_PUBLIC_API_URL, CORS_ORIGIN, API health, Postgres migrations, and Redis connectivity.
If payment verification fails, verify the transaction is confirmed, the memo includes the call id, the recipient wallet matches the provider wallet, and the Solana RPC endpoint can fetch the transaction.