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).
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 PDP-Connect/data-connectors.

​
Which scopes have sample fixtures

Sample mode only works for scopes that have a fixture in PDP-Connect/data-connectors. Current coverage (authoritative list: fixture-index.json): To use a non-default fixture, point VANA_SAMPLE_DATA_URL at its rawUrl from the fixture index, for example:
Choosing a scope without a fixture 404s at the first read. Either pick a fixture-backed scope for the sample flow and switch scopes when you go live, or supply your own fixture via VANA_SAMPLE_DATA_PATH (local file) / VANA_SAMPLE_DATA_URL — the JSON must match the scope’s schema in data-connectors.

​
Test against the live protocol

Copy the example env file:
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.

​
Deploy to a host

When you deploy (Vercel is the common choice), remember that .env.local is not uploaded — set every variable your app needs (VANA_MODE, VANA_APP_URL, and in live mode VANA_APP_PRIVATE_KEY, VANA_ENV, VANA_NETWORK) in the host’s project settings, and redeploy after changing them. On Vercel: Project Settings → Environment Variables, applied to all environments you use. A deploy without them silently falls back to sample-mode defaults. Also set VANA_APP_URL to the deployed origin so the approval return URL matches.
Prefer to build the integration directly into your own app? See Add Vana to your own app.