Typed clients for all Immutable APIs and services.
Who is this for? Web developers and TypeScript developers looking to build web3 applications and integrate blockchain features seamlessly.
Packages
Install only what you need:
| Package | Purpose | Install |
|---|
@imtbl/auth | Authentication & sessions | npm i @imtbl/auth |
@imtbl/wallet | Embedded wallets & transactions | npm i @imtbl/wallet |
@imtbl/auth-nextjs | Next.js integration | npm i @imtbl/auth-nextjs |
@imtbl/orderbook | NFT trading | npm i @imtbl/orderbook |
@imtbl/blockchain-data | On-chain data queries (Indexer) | npm i @imtbl/blockchain-data |
@imtbl/minting-backend | Server-side minting | npm i @imtbl/minting-backend |
@imtbl/contracts | Smart contract ABIs & types | npm i @imtbl/contracts |
@imtbl/webhook | Webhook signature validation | npm i @imtbl/webhook |
@imtbl/config | Environment configuration | npm i @imtbl/config |
Install individual packages instead of @imtbl/sdk for smaller bundles and better tree-shaking.
Installation
Or install individual packages for smaller bundles:
npm install @imtbl/auth @imtbl/wallet @imtbl/config
Framework Setup
Next.js (App Router)
Vite
wagmi Integration
Use the @imtbl/auth-nextjs package for the simplest integration:npm install @imtbl/auth-nextjs
Layout Setup
// app/layout.tsx
import { ImmutableProvider } from '@imtbl/auth-nextjs';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<ImmutableProvider
clientId={process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID!}
redirectUri={`${process.env.NEXT_PUBLIC_URL}/callback`}
logoutRedirectUri={process.env.NEXT_PUBLIC_URL!}
>
{children}
</ImmutableProvider>
</body>
</html>
);
}
Using the Hooks
// app/page.tsx
'use client';
import { useAuth, useWallet } from '@imtbl/auth-nextjs';
export default function Home() {
const { user, login, logout, isLoading } = useAuth();
const { address, connect } = useWallet();
if (isLoading) return <div>Loading...</div>;
if (!user) {
return <button onClick={login}>Login with Passport</button>;
}
return (
<div>
<p>Welcome, {user.email}</p>
{address ? (
<p>Wallet: {address}</p>
) : (
<button onClick={connect}>Connect Wallet</button>
)}
<button onClick={logout}>Logout</button>
</div>
);
}
Callback Route
// app/callback/page.tsx
'use client';
import { AuthCallback } from '@imtbl/auth-nextjs';
export default function Callback() {
return <AuthCallback redirectTo="/" errorRedirectTo="/?error=auth" />;
}
Environment Variables
NEXT_PUBLIC_IMMUTABLE_CLIENT_ID=your_client_id
NEXT_PUBLIC_URL=http://localhost:3000
npm install @imtbl/auth @imtbl/wallet
Initialization
// src/lib/immutable.ts
import { Auth } from '@imtbl/auth';
import { connectWallet, ZkEvmProvider } from '@imtbl/wallet';
export const auth = new Auth({
clientId: import.meta.env.VITE_CLIENT_ID,
redirectUri: `${window.location.origin}/callback`,
logoutRedirectUri: window.location.origin,
audience: 'platform_api',
scope: 'openid offline_access email transact',
});
let providerPromise: Promise<ZkEvmProvider> | null = null;
export function getProvider() {
if (!providerPromise) {
providerPromise = connectWallet({ auth });
}
return providerPromise;
}
Environment Variables
VITE_CLIENT_ID=your_client_id
Vite Configuration (Required)
Vite requires Node.js polyfills for the SDK. Without this configuration, builds will fail.
npm install --save-dev vite-plugin-node-polyfills
// vite.config.ts
import { defineConfig } from 'vite';
import { nodePolyfills } from 'vite-plugin-node-polyfills';
export default defineConfig({
plugins: [
nodePolyfills()
]
});
Use Passport with wagmi for React hooks:npm install wagmi @imtbl/auth @imtbl/wallet
Configuration
import { createConfig, http } from 'wagmi';
import { immutableZkEvmTestnet } from 'wagmi/chains';
import { injected } from 'wagmi/connectors';
export const wagmiConfig = createConfig({
chains: [immutableZkEvmTestnet],
connectors: [injected()],
transports: {
[immutableZkEvmTestnet.id]: http(),
},
});
Component Example
import { useAccount, useConnect } from 'wagmi';
function WalletButton() {
const { address, isConnected } = useAccount();
const { connect, connectors } = useConnect();
if (isConnected) {
return <span>{address?.slice(0, 8)}...</span>;
}
return (
<button onClick={() => connect({ connector: connectors[0] })}>
Connect
</button>
);
}
Environment Configuration
| Environment | Chain | API Base |
|---|
SANDBOX | Immutable Testnet | api.sandbox.immutable.com |
PRODUCTION | Immutable Mainnet | api.immutable.com |
Next Steps
Getting Started
Additional Resources
