@iamgame/wallet-sdk 0.1.0

package/README.md

@@ -0,0 +1,98 @@
+# @iamgame/wallet-sdk
+
+Embedded wallet SDK for games on Solana. Telegram & browser-wallet auth, live balances, server-side signing, and key export — in one React provider.
+
+- **Telegram Mini App login** — players inside Telegram are signed in with zero taps.
+- **Browser wallet auth (SIWS)** — Phantom, Solflare, Backpack, auto-detected.
+- **Server-side signing** — sub-200ms, no device-signing on the hot path.
+- **Full wallet lifecycle** — provisioning, balances, withdrawals, key export.
+
+## Install
+
+```bash
+npm install @iamgame/wallet-sdk
+```
+
+`react` and `react-dom` (>=18) are peer dependencies.
+
+## Quick start
+
+Wrap your app in the provider with your publishable key:
+
+```tsx
+import { IAMGameWalletProvider } from "@iamgame/wallet-sdk";
+
+export function App() {
+  return (
+    <IAMGameWalletProvider publishableKey="pk_live_...">
+      <Game />
+    </IAMGameWalletProvider>
+  );
+}
+```
+
+Drop in the login component:
+
+```tsx
+import { WalletLogin } from "@iamgame/wallet-sdk";
+
+<WalletLogin autoTelegram onSignIn={(user) => console.log("signed in", user.id)} />;
+```
+
+Use the hooks anywhere inside the provider:
+
+```tsx
+import { useWalletAuth, useWallet, useWalletBalance, useWalletSign } from "@iamgame/wallet-sdk";
+
+function Wallet() {
+  const { status, user, logout } = useWalletAuth();
+  const wallet = useWallet();
+  const balance = useWalletBalance(wallet?.id);
+
+  if (status !== "authenticated") return <WalletLogin />;
+
+  return (
+    <div>
+      <div>{wallet?.address}</div>
+      <div>{balance?.tokens.map((t) => `${t.amount} ${t.symbol ?? t.mint}`).join(", ")}</div>
+      <button onClick={logout}>Log out</button>
+    </div>
+  );
+}
+```
+
+Sign a transaction server-side (the wallet's key never touches the device):
+
+```tsx
+const { signAction } = useWalletSign();
+
+const { signedTxBase64, signature } = await signAction({
+  walletId: wallet.id,
+  txBase64,            // base64 of a serialized (v0 or legacy) Solana transaction
+  label: "buy-ticket", // optional, recorded in the audit log
+});
+```
+
+## Exports
+
+| Kind | Names |
+|------|-------|
+| Client | `IAMGameWalletClient`, `IAMGameWalletProvider`, `WalletSdkError` |
+| Hooks | `useWalletAuth`, `useWallet`, `useWalletBalance`, `useWalletSign`, `useWalletExport`, `useWalletTransferIn` |
+| Components | `WalletLogin`, `WalletLoginModal`, `WalletAddress`, `WalletBalance`, `WalletWithdraw`, `WalletExport` |
+| Adapters | `phantomAdapter`, `solflareAdapter`, `backpackAdapter`, `listSupportedWallets` |
+| Session | `localStorageSession`, `inMemorySession` |
+
+All components accept a `theme` prop so the UI matches your game.
+
+## Get API keys
+
+Sign up at [wallet.iamgame.com](https://wallet.iamgame.com) to create an app and get your publishable (`pk_`) and secret (`sk_`) keys. Sandbox (devnet) keys are issued instantly; live keys are enabled on approval.
+
+## Documentation
+
+Full guides and API reference: [wallet.iamgame.com/docs](https://wallet.iamgame.com/docs)
+
+## License
+
+MIT