Build a Vana App - Vana Protocol

Use Vana’s Data Portability API to request user-approved data, read it from the user’s Personal Server, and pay protocol fees from your app’s escrow balance. This guide assumes a web app with a server backend and a React frontend.

Quickstart

Run the example app in sample-data mode. It needs Node.js 22+ and no account, key or funds:

git clone https://github.com/vana-com/vana-sdk.git
cd vana-sdk && npm install
npm run dev --workspace @opendatalabs/vana-app-example

Open http://localhost:3000 and click Connect Spotify. To add Vana to your own app, install the SDK:

npm install @opendatalabs/vana-sdk viem

The whole flow is three server calls:

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

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

const { requestId, approvalUrl } = await vana.createAccessRequest({ returnUrl }); // send the user to approvalUrl
const { status } = await vana.getAccessRequestStatus(requestId);                  // poll while "pending"
const { data } = await vana.readApprovedData({ requestId });                      // read from the user's Personal Server

Add Vana to your own app has the API routes and the React hook around these calls.

Vana runs on two networks. Develop and test on Moksha (testnet) with free faucet VANA, then launch on mainnet by switching one setting — the same app and code carry over. See Choose your network.

What you’ll build

A server controller

Holds your app identity, requested source, requested scopes, and paid reads.

Three backend routes

Create an access request, check approval status, and read approved data.

A React button

Opens Vana approval and renders the returned result.

Two ways to build

Start from the example app

Clone, install, run — the whole flow working locally with sample data and no setup. The same code goes live when you’re ready.Best for seeing how Vana works, and greenfield apps.

Add Vana to your own app

Wire Vana’s primitives into your existing app with @opendatalabs/vana-sdk — request, approve, read. You keep your stack; the SDK handles identity, grants, and payments.Best for adding Vana to a real product on your own stack.

Environments

One setting, VANA_NETWORK, picks the chain, contracts, and escrow. Full comparison and funding instructions: Choose your network.

Moksha testnet (develop + test)
Mainnet (launch)


Account	`account.vana.org/developers`, Protocol network: Testnet
Block explorer	`moksha.vanascan.io`
Fee asset	native VANA
Get funds	`faucet.vana.com/moksha` (free)


Account	`account.vana.org/developers`
Block explorer	`vanascan.io`
Fee asset	USDC.e
Get funds	Fund escrow

Steps

Get set up

Choose your network, create an app identity, check fees, and fund escrow.

Build

Start from the example app or add Vana to your own app, with your source and scopes.

Ship

Test the flow end to end, and keep troubleshooting close.

Extend

Need a source that doesn’t exist yet? Add a connector.

​Quickstart

​What you’ll build

A server controller

Three backend routes

A React button

​Two ways to build

Start from the example app

Add Vana to your own app

​Environments

​Steps

Quickstart

What you’ll build

Two ways to build

Environments

Steps