Skip to main content

Quick Start

Get up and running with SolvaPay SDK in minutes. These examples are copy-paste ready and work out of the box.

Express.js: Protect an API Endpoint (5 minutes)​

Protect an Express.js API endpoint with paywall protection:

import express from 'express';
import { createSolvaPay } from '@solvapay/server';

const app = express();
app.use(express.json());

// Initialize SolvaPay (works without API key in stub mode)
const solvaPay = createSolvaPay({
  // apiKey: process.env.SOLVAPAY_SECRET_KEY // Optional for production
});

// Create payable handler for your agent
const payable = solvaPay.payable({
  agent: 'agt_YOUR_AGENT',  // Your agent reference from SolvaPay dashboard
  plan: 'pln_YOUR_PLAN'      // Your plan reference
});

// Your business logic
async function createTask(req: express.Request) {
  const { title } = req.body;
  return {
    success: true,
    task: { id: '1', title, createdAt: new Date() }
  };
}

// Protect the endpoint with one line
app.post('/tasks', payable.http(createTask));

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

Test it:

# Make a request (replace with your customer reference)
curl -X POST http://localhost:3000/tasks \
  -H "Content-Type: application/json" \
  -H "x-customer-ref: user_123" \
  -d '{"title": "My task"}'

Next.js: Add Payment Flow (10 minutes)​

1. Set up API Routes​

Create API routes for subscription checking and payment:

// app/api/check-subscription/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { checkSubscription } from '@solvapay/next';

export async function GET(request: NextRequest) {
  const result = await checkSubscription(request);
  return result instanceof NextResponse 
    ? result 
    : NextResponse.json(result);
}
// app/api/create-payment-intent/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { createPaymentIntent } from '@solvapay/next';

export async function POST(request: NextRequest) {
  const { planRef, agentRef } = await request.json();
  
  if (!planRef || !agentRef) {
    return NextResponse.json(
      { error: 'Missing required parameters' },
      { status: 400 }
    );
  }

  const result = await createPaymentIntent(request, { planRef, agentRef });
  return result instanceof NextResponse 
    ? result 
    : NextResponse.json(result);
}

2. Set up Provider​

// app/layout.tsx
import { SolvaPayProvider } from '@solvapay/react';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <SolvaPayProvider
          config={{
            api: {
              checkSubscription: '/api/check-subscription',
              createPayment: '/api/create-payment-intent',
            }
          }}
        >
          {children}
        </SolvaPayProvider>
      </body>
    </html>
  );
}

3. Add Payment Form​

// app/checkout/page.tsx
'use client';

import { PaymentForm } from '@solvapay/react';
import { useRouter } from 'next/navigation';

export default function CheckoutPage() {
  const router = useRouter();

  return (
    <div>
      <h1>Subscribe to Premium</h1>
      <PaymentForm
        planRef="pln_YOUR_PLAN"
        agentRef="agt_YOUR_AGENT"
        onSuccess={() => {
          console.log('Payment successful!');
          router.push('/dashboard');
        }}
        onError={(error) => {
          console.error('Payment failed:', error);
        }}
      />
    </div>
  );
}

MCP Server: Protect MCP Tools (5 minutes)​

Protect MCP (Model Context Protocol) tools with paywall protection:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import { createSolvaPay } from '@solvapay/server';

// Initialize SolvaPay
const solvaPay = createSolvaPay({
  // apiKey: process.env.SOLVAPAY_SECRET_KEY // Optional for production
});

// Create payable handler
const payable = solvaPay.payable({
  agent: 'agt_YOUR_AGENT'
});

// Your tool implementation
async function myTool(args: { input: string }) {
  return {
    success: true,
    result: `Processed: ${args.input}`
  };
}

// Create MCP server
const server = new Server(
  {
    name: 'my-mcp-server',
    version: '1.0.0',
  },
  {
    capabilities: { tools: {} },
  }
);

// Handle tool execution with paywall protection
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  
  if (name === 'my_tool') {
    // Protect the tool with one line
    const handler = payable.mcp(myTool);
    return await handler(args);
  }
  
  throw new Error(`Unknown tool: ${name}`);
});

// Start server
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error('MCP server started');
}

main();

React: Add Payment UI Components (10 minutes)​

1. Set up Provider​

// App.tsx or layout component
import { SolvaPayProvider } from '@solvapay/react';

function App() {
  return (
    <SolvaPayProvider
      config={{
        api: {
          checkSubscription: '/api/check-subscription',
          createPayment: '/api/create-payment-intent',
        }
      }}
    >
      <YourApp />
    </SolvaPayProvider>
  );
}

2. Use Subscription Hook​

// components/Dashboard.tsx
import { useSubscription } from '@solvapay/react';

function Dashboard() {
  const { subscriptions, hasPaidSubscription, isLoading } = useSubscription();

  if (isLoading) return <div>Loading...</div>;

  if (!hasPaidSubscription) {
    return (
      <div>
        <h2>Upgrade to Premium</h2>
        <a href="/checkout">Subscribe Now</a>
      </div>
    );
  }

  return (
    <div>
      <h2>Welcome, Premium User!</h2>
      <p>Active subscriptions: {subscriptions.length}</p>
    </div>
  );
}

3. Add Payment Form​

// components/Checkout.tsx
import { PaymentForm } from '@solvapay/react';

function Checkout() {
  return (
    <div>
      <h1>Subscribe to Premium</h1>
      <PaymentForm
        planRef="pln_YOUR_PLAN"
        agentRef="agt_YOUR_AGENT"
        onSuccess={() => {
          window.location.href = '/dashboard';
        }}
      />
    </div>
  );
}

Next Steps​