Referrals in your UI

Referrals have two halves. This page is the client half you build into your game UI: capturing an invite code when a referred player arrives, attaching it to their login, and showing a player their own code and share links so they can invite others. The payout logic — who earns what, and when — is the server half; it lives in Referrals (server) and you never touch it from the client.

Capturing the code

A referred player lands on a link like https://yourgame.com/?ref=ABC123 (or ?referral=, or a Telegram startapp parameter). The provider captures that automatically on mount — if you’ve mounted IAMGameWalletProvider, the code is already stored and will ride along on the next login. For the common case you write no capture code at all.

import { IAMGameWalletProvider } from "@iamgame/wallet-sdk";

// The provider captures ?ref= / ?referral= / Telegram startapp on mount.
// Nothing else to do — the captured code is attached to the next login.
export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <IAMGameWalletProvider publishableKey={process.env.NEXT_PUBLIC_WALLET_PK!}>
      {children}
    </IAMGameWalletProvider>
  );
}

When you route the code yourself

If your app owns its own routing and the code doesn’t sit in a plain ?ref= query — say it’s a path segment, or you fetched it from your own backend — hand it to the SDK with setReferralCode. You can also call captureReferralCodeFromUrl manually (e.g. after a client-side navigation the provider didn’t see), and read what’s pending with getPendingReferralCode:

import {
  setReferralCode,
  captureReferralCodeFromUrl,
  getPendingReferralCode,
} from "@iamgame/wallet-sdk";

// You pulled the code off your own routing (path segment, custom param, backend, …):
setReferralCode("ABC123");

// Or re-scan the current URL yourself after a client-side navigation:
const captured = captureReferralCodeFromUrl(); // returns the code, or the stored one

// Inspect what's waiting to be attached to the next login:
const pending = getPendingReferralCode(); // "ABC123" | null

Attaching the code to a login

There’s nothing extra to wire. Whatever login path the player takes, the SDK attaches the pending code to that login for you and clears it afterward. Your job is just to make sure the code was captured before the player logs in — which the auto-capture on provider mount already guarantees for URL-borne codes. If you’re routing a code manually, call setReferralCode before triggering login.

Showing the player their own code & share link

Once a player is signed in, give them a way to invite others. Two surfaces, depending on how much control you want.

Drop-in share link

WalletShareLink renders the signed-in player’s invite link for the platform the app is running on — it auto-detects web / Telegram / MeWe and picks the right link, with the player’s code already substituted, plus a copy button. It renders nothing while the player is anonymous or if the app has no link templates configured.

import { WalletShareLink } from "@iamgame/wallet-sdk";

export function InvitePanel() {
  return <WalletShareLink label="Invite friends & earn" />;
}

Headless: useShareLink

For custom UI, useShareLink() gives you the same data without markup — the best link for the current platform, which platform it targets, and all configured links if you want to render several (a “share to X” vs “share to Telegram” row):

import { useShareLink } from "@iamgame/wallet-sdk";

export function CustomInvite() {
  const { url, platform, all, loading } = useShareLink();

  if (loading) return <span>Loading your link…</span>;
  if (!url) return null; // anonymous, or no links configured

  return (
    <div>
      <p>Your invite link ({platform}):</p>
      <code>{url}</code>
      <button onClick={() => navigator.clipboard.writeText(url)}>Copy</button>

      {/* Optionally render every platform's link */}
      {all.map((l) => (
        <a key={l.platform} href={l.url}>{l.platform}</a>
      ))}
    </div>
  );
}

The raw code & referral summary

If you want the player’s bare code (to render your own share buttons), or a summary of how their referrals are doing, call getMyReferral() on the wallet client instance you constructed at setup (see Client SDK setup). It returns the player’s code, their referrerUserId (who invited them, if anyone), a directReferrals count, and their referral-earnings balances per currency:

import type { IAMGameWalletClient } from "@iamgame/wallet-sdk";

async function loadReferral(client: IAMGameWalletClient) {
  const me = await client.getMyReferral();
  // {
  //   code: "ABC123",
  //   referrerUserId: "u_… | null",
  //   directReferrals: 12,
  //   balances: [{ currency: 2, balance: "5000000" }],  // base units
  // }
  return me;
}

Client responsibilities, at a glance

Where to go next

• Referrals (server) — attribution, the earnings chain, and payouts.
• Client SDK setup — mounting the provider and getting the client.
• Authentication — the login the referral code attaches to.