Add Vana to your own app

The example app is the fastest way to see the flow and stays in sync with the SDK. Follow these steps to build the same integration directly into your own app — the routes and hook below are the ones the example uses.

Install

The snippets below use Next.js App Router, but @opendatalabs/vana-sdk isn’t tied to Next — the server controller runs in any Node backend and the hook works in any React app. Use an existing Next.js project (or adapt the routes to your framework). To start fresh:

npx create-next-app@latest vana-direct-demo --ts --app --eslint --src-dir --import-alias "@/*"
cd vana-direct-demo

Install the Vana SDK:

npm install @opendatalabs/vana-sdk viem

Configure the backend

Set server-side environment variables in .env.local:

.env.local

VANA_APP_PRIVATE_KEY=0x...
VANA_APP_URL=http://localhost:3000
VANA_ENV=production
VANA_NETWORK=moksha

Use VANA_ENV=production for the current Direct app flow. Set VANA_NETWORK=moksha (testnet) while developing, or VANA_NETWORK=mainnet for your live app — see Choose your network. Create lib/vana.ts:

lib/vana.ts

import { createDirectDataController } from "@opendatalabs/vana-sdk/server";

const network = process.env.VANA_NETWORK === "mainnet" ? "mainnet" : "moksha";

export const vana = createDirectDataController({
  env: "production",
  network,
  appPrivateKey: process.env.VANA_APP_PRIVATE_KEY!,
  app: {
    id: "spotify-taste",
    name: "Spotify Taste",
    homepageUrl: process.env.VANA_APP_URL!,
  },
  source: "spotify",
  scopes: ["spotify.profile"],
});

export const appAddress = vana.getAppAddress();

The SDK resolves the escrow contract and escrow gateway from the selected network — you don’t pass an address. Just fund escrow for your app on that network. (Pass an escrow config only to override the defaults for a custom deployment.) Replace source and scopes with values from the selected source detail or connector schema.

Create API routes

Create an access request route:

app/api/vana/request/route.ts

import { vana } from "@/lib/vana";

export async function POST() {
  const request = await vana.createAccessRequest({
    returnUrl: `${process.env.VANA_APP_URL}/connect/return`,
  });

  return Response.json(request);
  // {
  //   requestId: "dcr_123",
  //   approvalUrl: "https://app.vana.org/...",
  //   appAddress: "0x1234..."
  // }
}

Create a return page:

app/connect/return/page.tsx

export default function ConnectReturnPage() {
  return (
    <main>
      <h1>Approval complete</h1>
      <p>You can close this tab and return to the app.</p>
    </main>
  );
}

Vana redirects the approval tab to this page after approval. The original app tab continues polling status and reads the approved data. Create a status route:

app/api/vana/status/route.ts

import { vana } from "@/lib/vana";

export async function GET(request: Request) {
  const requestId = new URL(request.url).searchParams.get("requestId");

  if (!requestId) {
    return Response.json({ error: "Missing requestId" }, { status: 400 });
  }

  const status = await vana.getAccessRequestStatus(requestId);
  return Response.json(status);
  // Approved:
  // {
  //   status: "approved",
  //   personalServerUrl: "https://...",
  //   grantId: "0xabc...",
  //   scope: "spotify.profile"
  // }
}

Create a read route:

app/api/vana/data/route.ts

import { vana } from "@/lib/vana";

export async function GET(request: Request) {
  const requestId = new URL(request.url).searchParams.get("requestId");

  if (!requestId) {
    return Response.json({ error: "Missing requestId" }, { status: 400 });
  }

  const result = await vana.readApprovedData({ requestId });
  return Response.json(result);
}

readApprovedData reads from the user’s Personal Server. If payment is required, the SDK signs the protocol challenge with your app key, pays from your app’s escrow using the network’s escrow contract and gateway, retries with X-PAYMENT, and returns the paid read result. If your app’s escrow balance is unfunded, the read fails with Insufficient finalized balance — fund escrow and retry. readApprovedData reads one scope. Called with no scope, it reads the first scope the user approved. If your request covered several, either name the one you want or read them all:

// One named scope
const skills = await vana.readApprovedData({
  requestId,
  scope: "linkedin.skills",
});

// Every scope the user approved
const { results, errors } = await vana.readAllApprovedData({ requestId });
// results["linkedin.profile"].data, results["linkedin.skills"].data, ...

readAllApprovedData reads the scopes in approval order and returns each one under results, keyed by scope. A scope that fails lands in errors instead of aborting the rest, because the scopes read before it have already settled their fees — check errors before treating the read as complete. If any scope fails, the request is left unacknowledged so the failed scopes stay retryable. Read them with readApprovedData({ requestId, scope }), and let the last of those calls acknowledge.

Each scope is a separate paid read. Reading five scopes settles five data_access fees. Requesting five scopes costs no more than requesting one — the multiplier is at read time, not approval time. Read only the scopes your app uses. See check fees.

Reading several scopes with your own loop needs one extra step: a successful readApprovedData acknowledges the request, which moves it to completed — terminal, and no longer readable. Pass acknowledge: false on every call but the last, or use readAllApprovedData, which acknowledges once at the end.

Every readApprovedData call is a fresh Personal Server read that can settle a fee from your escrow. Cache the result per requestId server-side so repeat calls to your data route don’t re-read (and re-pay) — anyone who obtains a request ID could otherwise replay reads against your escrow. The example app’s data route shows the pattern.

Add React

The frontend calls your backend, opens Vana approval, polls status, asks your backend to read approved data, and renders the returned result.

app/components/ConnectSpotifyButton.tsx

"use client";

import { useDirectVanaConnect } from "@opendatalabs/vana-sdk/react";

async function jsonFetch(path: string, init?: RequestInit) {
  const res = await fetch(path, init);
  if (!res.ok) throw new Error(`${res.status} from ${path}`);
  return res.json();
}

export function ConnectSpotifyButton() {
  const connect = useDirectVanaConnect({
    createRequest: () => jsonFetch("/api/vana/request", { method: "POST" }),
    getStatus: (requestId: string) =>
      jsonFetch(`/api/vana/status?requestId=${encodeURIComponent(requestId)}`),
    readResult: (requestId: string) =>
      jsonFetch(`/api/vana/data?requestId=${encodeURIComponent(requestId)}`),
  });

  return (
    <div>
      <button
        disabled={connect.state.type !== "idle"}
        onClick={() => connect.start()}
        type="button"
      >
        {connect.state.type === "idle" ? "Connect Spotify" : "Connecting..."}
      </button>

      {connect.state.type === "done" ? (
        <pre>{JSON.stringify(connect.state.result, null, 2)}</pre>
      ) : null}

      {connect.state.type === "error" ? (
        <p role="alert">{connect.state.error.message}</p>
      ) : null}
    </div>
  );
}

Render <ConnectSpotifyButton /> from a page in your app.

Polling is bounded by the SDK: useDirectVanaConnect accepts pollIntervalMs and timeoutMs (default 5 minutes, then the flow errors out instead of polling forever). Use these instead of hand-rolling a polling loop — an abandoned approval tab on a hand-rolled loop keeps hitting your backend and the gateway indefinitely.

Get started

Build

Ship

Extend

Add Vana to your own app

Install

Configure the backend

Create API routes

Add React

​Install

​Configure the backend

​Create API routes

​Add React

Install

Configure the backend

Create API routes

Add React