TIAN Points API

User (browser)
  │
  ├─ Logs in via Privy (shared App ID across all askTIAN sites)
  │   └─ Receives a short-lived access token (privyToken)
  │
  ├─ Calls your product backend
  │   └─ Sends { privyToken } in the request body
  │
  └─ Your backend calls wallet.asktian.com/api/v1
      ├─ POST /api/v1/auth/verify   → verify identity + get balance + sessionToken
      ├─ POST /api/v1/points/deduct → charge the user (pass sessionToken)
      └─ Returns feature result to user

npm install @privy-io/react-auth

// main.tsx — wrap your app once
import { PrivyProvider } from "@privy-io/react-auth";

<PrivyProvider
  appId={import.meta.env.VITE_PRIVY_APP_ID}  // same App ID as wallet.asktian.com
  config={{
    loginMethods: ["wallet", "email", "google", "twitter"],
    appearance: { theme: "dark" },
  }}
>
  <App />
</PrivyProvider>

// In any component that calls your backend
import { usePrivy } from "@privy-io/react-auth";

function useTianRequest() {
  const { getAccessToken, authenticated } = usePrivy();

  return async (endpoint: string, body: object = {}) => {
    if (!authenticated) throw new Error("Not logged in");

    // Always call getAccessToken() fresh — it auto-refreshes
    const privyToken = await getAccessToken();

    const res = await fetch(endpoint, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ ...body, privyToken }),
    });

    if (res.status === 402) {
      // Redirect user to top up
      window.location.href = "https://wallet.asktian.com/purchase";
      return null;
    }

    return res.json();
  };
}

# ── Option A: Check balance only (no deduction) ────────────────────────────────────
# Use this to show the user their balance on page load without charging them.
# You need the privyId (from a previous /auth/verify call or your own DB).
curl "https://wallet.asktian.com/api/v1/points/balance?privyId=did:privy:clxxxxxxxxxxxxxxxx" \
  -H "X-API-Key: tc_live_your_key_here"

# Response:
# { "privyId": "did:privy:clxxxxxxxxxxxxxxxx", "balance": 250 }

# ── Option B: Verify token + deduct (full flow) ───────────────────────────────────
# Use this when the user triggers a paid action.
# Step 1: Verify the Privy token → get privyId + balance + sessionToken
curl -X POST https://wallet.asktian.com/api/v1/auth/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tc_live_your_key_here" \
  -d '{"privyToken": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."}'

# Response:
# {
#   "privyId": "did:privy:clxxxxxxxxxxxxxxxx",
#   "balance": 250,
#   "sessionToken": "a3f8c2d1...",
#   "sessionExpiresAt": "2026-03-27T12:05:00.000Z"
# }

# Step 2: Deduct points using the sessionToken from Step 1
curl -X POST https://wallet.asktian.com/api/v1/points/deduct \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tc_live_your_key_here" \
  -d '{"privyId": "did:privy:clxxxxxxxxxxxxxxxx", "sessionToken": "a3f8c2d1...", "amount": 1, "description": "Chat message"}'

# Response:
# { "success": true, "creditsDeducted": 1, "newBalance": 249 }

# ── Option C: Get a pre-built top-up URL (server-side, no frontend needed) ───────────
# Use this to generate a top-up link for email, Telegram, or any server-side notification.
# You need the privyId (from a previous /auth/verify call or your own DB).
curl "https://wallet.asktian.com/api/v1/topup-url?privyId=did:privy:clxxxxxxxxxxxxxxxx&amount=100&returnUrl=https%3A%2F%2Fyourapp.com%2Fdashboard"   -H "X-API-Key: tc_live_your_key_here"

# Response:
# {
#   "topupUrl": "https://wallet.asktian.com/purchase?method=card&amount=100&minBalance=100&returnUrl=https%3A%2F%2Fyourapp.com%2Fdashboard"
# }
# Open or share this URL directly — no further construction needed.

// Node.js / TypeScript — reusable helper
const WALLET_BASE = "https://wallet.asktian.com";
const WALLET_API_KEY = process.env.WALLET_API_KEY!;

async function verifyAndDeduct(
  privyToken: string,
  amount: number,
  description: string,
  endpoint: string
) {
  // Step 1: Verify token → get privyId, balance, and a single-use sessionToken
  const authRes = await fetch(`${WALLET_BASE}/api/v1/auth/verify`, {
    method: "POST",
    headers: { "Content-Type": "application/json", "X-API-Key": WALLET_API_KEY },
    body: JSON.stringify({ privyToken }),
  });

  if (!authRes.ok) throw Object.assign(new Error("Auth failed"), { status: 401 });
  const { privyId, balance, sessionToken } = await authRes.json();

  // Step 2: Check balance
  if (balance < amount) {
    throw Object.assign(
      new Error("Insufficient TIAN Points"),
      { status: 402, balance, required: amount }
    );
  }

  // Step 3: Deduct — pass sessionToken to prevent replay attacks
  const deductRes = await fetch(`${WALLET_BASE}/api/v1/points/deduct`, {
    method: "POST",
    headers: { "Content-Type": "application/json", "X-API-Key": WALLET_API_KEY },
    body: JSON.stringify({ privyId, sessionToken, amount, description, endpoint }),
  });

  if (!deductRes.ok) throw Object.assign(new Error("Deduction failed"), { status: 402 });
  const { newBalance } = await deductRes.json();

  return { privyId, newBalance };
}

// Usage in an Express route:
app.post("/api/chat", async (req, res) => {
  try {
    const { privyToken, message } = req.body;
    await verifyAndDeduct(privyToken, 1, "Chat message", "/api/chat");
    const reply = await generateReply(message);
    res.json({ reply });
  } catch (err: any) {
    res.status(err.status ?? 500).json({
      error: err.message,
      ...(err.balance !== undefined && { balance: err.balance, required: err.required }),
    });
  }
});

// Option A: your backend fetches topupUrl from /api/v1/topup-url and forwards it
// (recommended — the wallet builds the correct URL for the user's account)
if (res.status === 402) {
  const { balance, required, topupUrl } = await res.json(); // topupUrl from your backend
  window.open(topupUrl, "_blank");
}

// Option B: build the URL manually on the frontend (no extra backend call)
if (res.status === 402) {
  const { balance, required } = await res.json();
  const returnUrl = encodeURIComponent(window.location.href);
  const topUpUrl =
    `https://wallet.asktian.com/purchase?method=card&amount=${required}&returnUrl=${returnUrl}`;
  window.open(topUpUrl, "_blank");
}

// Confirm-before-pay pattern
const authRes = await fetch(`${WALLET_BASE}/api/v1/auth/verify`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-API-Key": WALLET_API_KEY },
  body: JSON.stringify({ privyToken }),
});
const { privyId, balance, sessionToken } = await authRes.json();

// Show balance to user; hold sessionToken in memory
if (balance < cost) return res.status(402).json({ error: "Insufficient TIAN Points" });

// ... user confirms the action ...

// Deduct — sessionToken is burned here
const deductRes = await fetch(`${WALLET_BASE}/api/v1/points/deduct`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-API-Key": WALLET_API_KEY },
  body: JSON.stringify({ privyId, sessionToken, amount: cost, description }),
});
// If 401: sessionToken expired or reused — call /auth/verify again