Zorveus Documentation

Allow users to connect their Zorveus AI wallet to your application using Authorization Code with PKCE.

Connect a user's Zorveus wallet to your application, complete the OAuth authorization flow with PKCE, and send an inference request funded by that wallet.

1. Register your app

In app.zorveus.com, create or select a Developer Organization.
Create an application and specify your registered Redirect URIs (e.g. https://myapp.com/oauth/callback).
Note your Client ID (zrv_client_...) and initial Client Secret (zrv_client_secret_...).

2. Select your platform

Choose your development platform or framework to view the step-by-step wallet connection guide:

Platform / Framework:

Step 1: Install dependencies

npm install @zorveus/react @zorveus/sdk

Step 2: Wrap your app in `ZorveusProvider`

Provide your clientId, redirectUri, and optional appId in your root app wrapper:

import React from "react";
import { ZorveusProvider } from "@zorveus/react";

export function AppProviders({ children }: { children: React.ReactNode }) {
  return (
    <ZorveusProvider
      clientId={process.env.NEXT_PUBLIC_ZORVEUS_CLIENT_ID}
      redirectUri="http://localhost:3000/oauth/callback"
      appId={process.env.NEXT_PUBLIC_ZORVEUS_APP_ID}
    >
      {children}
    </ZorveusProvider>
  );
}

Step 3: Add the `<ConnectWalletButton />` component

Render the pre-built wallet connection button in your header or navigation:

import { ConnectWalletButton, useZorveusAuth } from "@zorveus/react";

export function Header() {
  const { isConnected } = useZorveusAuth();

  return (
    <header style={{ display: "flex", justifyContent: "space-between", padding: "16px" }}>
      <h1>My AI SaaS App</h1>
      <ConnectWalletButton
        label="Connect Zorveus Wallet"
        connectedLabel="Wallet Connected"
      />
    </header>
  );
}

Step 4: Execute AI inference with the connected wallet

Use useZorveusInference or useZorveusAuth to run chat completions using the connected user's wallet access token:

import React, { useState } from "react";
import { useZorveusInference, useZorveusAuth } from "@zorveus/react";

export function ChatBox() {
  const { isConnected } = useZorveusAuth();
  const { client, isReady } = useZorveusInference();
  const [output, setOutput] = useState("");

  if (!isConnected) {
    return <p>Please connect your Zorveus wallet above to start generating AI responses.</p>;
  }

  async function handleGenerate() {
    if (!isReady || !client) return;

    const stream = await client.chat.completions.create({
      model: "openai/gpt-4.1-mini",
      messages: [{ role: "user", content: "Write a short product pitch." }],
      stream: true,
    });

    for await (const chunk of stream) {
      const text = chunk.choices[0]?.delta?.content || "";
      setOutput((prev) => prev + text);
    }
  }

  return (
    <div>
      <button onClick={handleGenerate}>Generate</button>
      <pre>{output}</pre>
    </div>
  );
}

3. Handle expiration, errors, and revocation

Use the token response's expires_in value to track expiration. If the token expires or the user revokes access, stop sending inference requests with that token and start the authorization flow again.

Follow Reauthorization when your app needs new scopes or a replacement token.
Follow Revocation when the user disconnects their wallet.
Use OAuth Errors to handle denied consent, invalid state, expired codes, and token exchange failures.

Next steps

OAuth Architecture Deep Dive

Read the full OAuth reference covering reauthorization, scopes, and revocation.

Publishing & App Review

Understand the lifecycle from Draft apps to Public Verified status.

Was this page helpful?

Edit this page on GitHub

OAuth App Quickstart