Skip to main content
Start by running the SDK example. It is the fastest way to start: it uses the same backend routes and React hook that a real app uses, but defaults to sample-data mode so you can verify the app shape before registering an app identity, funding escrow, or running a Personal Server.
Requires Node.js 22+ (the Vana SDK’s minimum).
git clone https://github.com/vana-com/vana-sdk.git
cd vana-sdk
npm install
npm run typecheck --workspace @opendatalabs/vana-app-example
npm run dev --workspace @opendatalabs/vana-app-example
Open http://localhost:3000 and click Connect Spotify. The approval tab returns locally, the original tab polls status, and the app reads sample data through the same createAccessRequest, getAccessRequestStatus, and readApprovedData controller methods used in live mode.
If port 3000 is taken, Next.js starts on the next free port (for example http://localhost:3001). Open the port it prints, and set VANA_APP_URL to that same origin so the approval return URL matches.
After the sample flow works, adapt the example to your app. These live in examples/vana-app/lib/vana.ts:
  • Source and app id/name are constants in lib/vana.ts — edit them there.
  • Scopes can be set either in lib/vana.ts or with the VANA_SCOPES env var (comma-separated, for example VANA_SCOPES=spotify.savedTracks,spotify.profile).
  • Sample fixture URL is set with VANA_SAMPLE_DATA_URL (or VANA_SAMPLE_DATA_PATH for a local file).
Reusable sample fixtures belong in vana-com/data-connectors.

​
Test against the live protocol

Copy the example env file: 
cp examples/vana-app/.env.example examples/vana-app/.env.local
Then set VANA_MODE=live (from sample), VANA_APP_PRIVATE_KEY, VANA_APP_URL, VANA_ENV=production, and VANA_NETWORK=moksha (testnet) or mainnet. Keep the private key server-side.
You don’t set the escrow contract address — the SDK resolves it from the network you choose (VANA_NETWORK), along with the escrow gateway. Just fund escrow for your app on that network so paid reads can settle. VANA_ESCROW_CONTRACT, VANA_DP_RPC_URL, VANA_ACCESS_REQUEST_BASE_URL, and VANA_APPROVAL_APP_BASE_URL exist only as optional overrides for custom deployments — leave them unset to use the network defaults.
Prefer to build the integration directly into your own app? See Add Vana to your own app.