Set Up a Next.js App Router API Proxy for ParaLens

The easiest way to integrate ParaLens into a Next.js app is to create an API route that proxies requests. This hides the Railway URL from client-side code, forwards future API keys securely via server-side environment variables, and gives you a single place to add caching or logging as your app grows.

Prerequisites

Next.js 13+ with the App Router (app/ directory)
TypeScript (recommended — types shown throughout this guide)

Setup

Create the API route file

Create a new file at app/api/analyze/route.ts. Next.js will automatically expose this as POST /api/analyze when the app is running.

// app/api/analyze/route.ts
export async function POST(request: Request) {
  const body = await request.json();

  const response = await fetch(`${process.env.PARALENS_API_URL}/analyze`, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(body),
    cache: 'no-store',
  });

  const data = await response.json();
  return Response.json(data, { status: response.status });
}

The route reads PARALENS_API_URL from the server environment and forwards the request body as-is. The upstream HTTP status is preserved so your frontend error handling works correctly.

Add the environment variable

Add the Railway base URL to .env.local. This file is read only by Next.js server-side code and is never included in the client bundle.

# .env.local
PARALENS_API_URL=https://paralens-production.up.railway.app

Never prefix this variable with NEXT_PUBLIC_. Public variables are embedded in the client bundle and visible to anyone who inspects your JavaScript. Keep the Railway URL server-side only.

Call the proxy from your frontend

In any client component, call /api/analyze instead of the Railway URL directly.

// lib/analyze.ts
import type { TxReport } from '@/types/paralens';

export async function analyze(txHash: string): Promise<TxReport> {
  const response = await fetch('/api/analyze', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ chain: 'ethereum', tx_hash: txHash }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error ?? 'Analysis failed');
  }

  return response.json(); // TxReport
}

(Optional) Add response caching

Ethereum transactions are immutable once confirmed, so the same hash will always produce the same report. Add caching at the proxy layer to avoid redundant upstream calls.See the Adding Caching section below for an in-memory and Redis example.

Adding Caching

Because confirmed transactions never change, you can safely cache responses indefinitely. A 24-hour TTL is a practical default that balances freshness with performance. In-memory cache — suitable for single-instance deployments or development:

// app/api/analyze/route.ts
const cache = new Map<string, { data: unknown; expiresAt: number }>();
const TTL_MS = 24 * 60 * 60 * 1000; // 24 hours

export async function POST(request: Request) {
  const body = await request.json();
  const cacheKey = `${body.chain}:${body.tx_hash}`;

  const cached = cache.get(cacheKey);
  if (cached && Date.now() < cached.expiresAt) {
    return Response.json(cached.data);
  }

  const response = await fetch(`${process.env.PARALENS_API_URL}/analyze`, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(body),
    cache: 'no-store',
  });

  const data = await response.json();

  if (response.ok) {
    cache.set(cacheKey, { data, expiresAt: Date.now() + TTL_MS });
  }

  return Response.json(data, { status: response.status });
}

Redis cache — recommended for multi-instance or serverless deployments (e.g., Vercel). Use ioredis or the @upstash/redis client:

// app/api/analyze/route.ts
import { Redis } from '@upstash/redis';

const redis = Redis.fromEnv();
const TTL_SECONDS = 86400; // 24 hours

export async function POST(request: Request) {
  const body = await request.json();
  const cacheKey = `paralens:${body.chain}:${body.tx_hash}`;

  const cached = await redis.get(cacheKey);
  if (cached) {
    return Response.json(cached);
  }

  const response = await fetch(`${process.env.PARALENS_API_URL}/analyze`, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(body),
    cache: 'no-store',
  });

  const data = await response.json();

  if (response.ok) {
    await redis.set(cacheKey, data, { ex: TTL_SECONDS });
  }

  return Response.json(data, { status: response.status });
}

Future API Key Support

ParaLens does not require authentication today, but future-compatible clients should be prepared to send an x-api-key header. When API keys are introduced, update your proxy to read PARALENS_API_KEY from the server environment and forward it — no changes needed in your frontend components.

// app/api/analyze/route.ts
const response = await fetch(`${process.env.PARALENS_API_URL}/analyze`, {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    ...(process.env.PARALENS_API_KEY && { 'x-api-key': process.env.PARALENS_API_KEY }),
  },
  body: JSON.stringify(body),
  cache: 'no-store',
});

Add the key to .env.local when you receive one:

# .env.local
PARALENS_API_URL=https://paralens-production.up.railway.app
PARALENS_API_KEY=your-api-key-here

Never expose your Railway URL or API key in client-side code or public environment variables (i.e., variables prefixed with NEXT_PUBLIC_). Always read credentials in server-only code such as API routes, Server Components, or getServerSideProps.

Next Steps

Now that your proxy is set up, head to Dashboard Layouts to learn how to use classification.intent_kind to choose the right UI layout for each transaction type.

Get Started

Use Cases

Integration Guides

Help

Set Up a Next.js App Router API Proxy for ParaLens

Prerequisites

Setup

Adding Caching

Future API Key Support

Next Steps

​Prerequisites

​Setup

​Adding Caching

​Future API Key Support

​Next Steps

Prerequisites

Setup

Adding Caching

Future API Key Support

Next Steps