Skip to main content
@buckspay/nextjs exports two App Router route factories. They act as the BFF (Backend for Frontend) boundary described in Facilitator and BFF: the browser POSTs to your same-origin routes; the routes forward to the facilitator with the secret credentials server-side.
@buckspay/nextjs is server-only. Never import it in a Client Component or a file that ends up in the browser bundle. The API key and provider secrets you pass to these factories are captured in a server closure and are never serialized or echoed to the client.
1
Install
2
pnpm add @buckspay/nextjs @buckspay/core @buckspay/relayer
3
Create the relay route
4
Create app/api/buckspay/relay/route.ts. createRelayRoute returns a (req: Request) => Promise<Response> handler - assign it to POST as required by App Router conventions.
5
// app/api/buckspay/relay/route.ts - SERVER-ONLY
import { createRelayRoute } from "@buckspay/nextjs";

export const POST = createRelayRoute({
  facilitatorUrl: process.env.BUCKSPAY_FACILITATOR_URL!,
  apiKey: process.env.BUCKSPAY_FACILITATOR_API_KEY!, // SERVER-SIDE ONLY
  network: "testnet"
});
6
createRelayRoute accepts a CreateRelayRouteOptions object:
7
OptionTypeDescriptionfacilitatorUrlstringBase URL of the Buckspay facilitatorapiKeystringFacilitator API key - from a server env var, never a literalnetworkNetwork"testnet" or "mainnet"
8
The route validates the incoming RelayPayload with a strict Zod schema before forwarding, so malformed requests are rejected at the BFF layer. On error it returns a coded JSON response ({ error: BuckspayErrorCode }) without leaking the upstream message.
9
Create signer proxy routes (social and email login)
10
If you use social or email-based signers, create proxy routes that forward the auth body to the facilitator’s /auth/* endpoints while injecting the API key server-side.
11
// app/api/buckspay/auth/social/route.ts - SERVER-ONLY
import { createSignerProxyRoute } from "@buckspay/nextjs";
export const POST = createSignerProxyRoute({ provider: "web3auth", network: "testnet" });
12
// app/api/buckspay/auth/email/route.ts - SERVER-ONLY
import { createSignerProxyRoute } from "@buckspay/nextjs";
export const POST = createSignerProxyRoute({ provider: "email", network: "testnet" });
13
createSignerProxyRoute reads BUCKSPAY_FACILITATOR_URL and BUCKSPAY_FACILITATOR_API_KEY from the server environment by default. You can override both via the optional second argument (CreateSignerProxyRouteDeps).
14
Point the browser client at your BFF routes
15
In your browser (or React) code, configure the relayer without an API key - it points at your same-origin BFF routes:
16
import { buckspayFacilitator } from "@buckspay/relayer/buckspay-facilitator";

const relayer = buckspayFacilitator({ url: "/api/buckspay/relay", network: "testnet" });
// No apiKey here - the key lives server-side in the route handler above.

​
Full example

The snippet below shows all three route handlers in a single file for reference. In production, each goes in its own route.ts under app/. 
// Recipe 15 - NEXT.JS BFF (App Router). Three server-only route handlers, packaged.
//
// These are the same-origin endpoints your browser code calls (`/api/buckspay/...`). The
// facilitator apiKey and the provider secrets stay SERVER-SIDE - they are never in the client
// bundle. Each `export const POST` below lives in its own `route.ts` under app/.
import { createRelayRoute, createSignerProxyRoute } from "@buckspay/nextjs";

// app/api/buckspay/relay/route.ts - the gasless relay BFF (the dashboard pattern, packaged).
export const relayPOST = createRelayRoute({
  facilitatorUrl: process.env.BUCKSPAY_FACILITATOR_URL ?? "https://facilitator.example",
  apiKey: process.env.BUCKSPAY_FACILITATOR_API_KEY ?? "", // SERVER-SIDE ONLY
  network: "testnet"
});

// app/api/buckspay/auth/social/route.ts - social signer-proxy (forwards to /auth/social).
// Reads BUCKSPAY_FACILITATOR_URL + BUCKSPAY_FACILITATOR_API_KEY from server env.
export const socialPOST = createSignerProxyRoute({ provider: "web3auth", network: "testnet" });

// app/api/buckspay/auth/email/route.ts - email signer-proxy (forwards to /auth/email).
export const emailPOST = createSignerProxyRoute({ provider: "email", network: "testnet" });

​
Next

Facilitator and BFF

Why the API key must stay server-side and how the BFF slot fits the payment flow.

Web - @buckspay/react

The browser-side hooks that POST to your BFF relay route.