Quickstart

IAMGame Wallet gives every player an embedded Solana wallet they sign in to with their existing wallet, Telegram, or email — no seed phrases, no extensions. This guide takes you from zero to a working login your backend trusts in about ten minutes. Skim Core concepts first if you want the mental model (apps, keys, environments, custody).

1. Get your keys

Sign in to the developer portal and create an app. Every app has two keys, split by where they run:

Publishable key (pk_test_… / pk_live_…) — safe to ship in your game client. Starts logins and reads the signed-in player’s own wallet.
Secret key (sk_test_… / sk_live_…) — backend only, never in the browser. Verifies sessions and moves money.

2. Install the SDK

npm install @iamgame/wallet-sdk

3. Wrap your app in the provider

Point the SDK at the API and pass your publishable key. Do this once, high in the tree.

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

export default function App({ children }: { children: React.ReactNode }) {
  return (
    <IAMGameWalletProvider
      publishableKey={process.env.NEXT_PUBLIC_IAMGAME_WALLET_PK!}
      baseUrl="https://api-wallet.iamgame.com/v1"
    >
      {children}
    </IAMGameWalletProvider>
  );
}

Inside a Telegram Mini App the provider auto-logs the player in from the launch data (zero taps) — that’s the autoTelegram default. See Client SDK setup for every provider option, including onError for your tracker.

4. Add a login + wallet UI

Drop in the prebuilt components. They render every sign-in method your app enables.

import { WalletLogin, WalletAddress, WalletBalance } from "@iamgame/wallet-sdk";

function Account() {
  return (
    <div>
      <WalletLogin />       {/* SIWS · Telegram · email OTP — whatever the app allows */}
      <WalletAddress />     {/* the player's Solana address, truncated */}
      <WalletBalance />     {/* live balances, formatted from smallest units */}
    </div>
  );
}

Prefer to build your own UI? Every component is backed by a hook — useWalletAuth(), useWallet(), useWalletBalance(). See Login & session.

On a successful login the SDK holds a short-lived access token (the session token). The next step is proving that session to your own backend.

5. Trust the player on your backend

Never trust a wallet address the browser claims. Forward the access token to your backend and verify it server-to-server with your secret key, then mint your own app session.

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

const wallet = new IAMGameWalletServer({
  secretKey: process.env.IAMGAME_WALLET_SECRET_KEY!,   // sk_… — server only
  baseUrl: "https://api-wallet.iamgame.com/v1",
});

// Your login endpoint receives { sessionToken } from the frontend.
const verified = await wallet.verifySession(sessionToken);
// → { userId, appId, environment, authMethod, walletAddress, wallets, identities }

const myJwt = signMyAppJwt({ userId: verified.userId, wallet: verified.walletAddress });

That’s the whole loop: wallet login → access token → your backend verifies → your JWT. verifySession is scoped to your key’s app + environment and fails closed. Full setup in Server SDK setup.

Where next

• Core concepts — apps & keys, environments, custody, identities, and the money models.
• Client SDK setup — every provider option and how to build custom wallet UI from the hooks.
• Authentication — the three sign-in methods in depth, plus keys and the session lifecycle.
• Server SDK setup — verifying sessions and calling the wallet from your backend.
• Choose a money model — ledger, custodial treasury, or pool escrow: the decision that shapes your backend.