Typed clients for all Immutable APIs and services.
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.
Quick Start
import { Auth } from '@imtbl/auth';
import { connectWallet } from '@imtbl/wallet';
import { Orderbook } from '@imtbl/orderbook';
import { BlockchainData } from '@imtbl/blockchain-data';
import { Environment } from '@imtbl/config';
const baseConfig = {
environment: Environment.SANDBOX,
publishableKey: 'YOUR_PUBLISHABLE_KEY',
};
// Authentication
const auth = new Auth({
clientId: 'YOUR_CLIENT_ID',
redirectUri: 'http://localhost:3000/callback',
logoutRedirectUri: 'http://localhost:3000',
audience: 'platform_api',
scope: 'openid offline_access email transact',
});
// Wallet (returns EIP-1193 provider)
const provider = await connectWallet({ auth });
// Trading
const orderbook = new Orderbook({ baseConfig });
// On-chain data
const indexer = new BlockchainData({ baseConfig });
Environment Configuration
import { Environment } from '@imtbl/config';
// Development
const sandboxConfig = { environment: Environment.SANDBOX };
// Production
const productionConfig = { environment: Environment.PRODUCTION };
| Environment | Chain | API Base |
|---|
SANDBOX | Immutable Testnet | api.sandbox.immutable.com |
PRODUCTION | Immutable Mainnet | api.immutable.com |
Using with viem
viem has built-in Immutable Chain support:
import { createWalletClient, createPublicClient, custom, http } from 'viem';
import { immutableZkEvm, immutableZkEvmTestnet } from 'viem/chains';
// Get wallet provider
const provider = await connectWallet({ auth });
// Create viem clients
const walletClient = createWalletClient({
chain: immutableZkEvmTestnet,
transport: custom(provider),
});
const publicClient = createPublicClient({
chain: immutableZkEvmTestnet,
transport: http(),
});
// Get address
const [address] = await walletClient.getAddresses();
// Send transaction
const hash = await walletClient.sendTransaction({
to: '0x...',
value: parseEther('0.1'),
});
Backend Integration
For server-side operations like minting:
import { MintingBackend } from '@imtbl/minting-backend';
import { Environment } from '@imtbl/config';
const minting = new MintingBackend({
baseConfig: { environment: Environment.SANDBOX },
apiKey: process.env.IMMUTABLE_SECRET_KEY!,
});
// Mint NFTs
await minting.mintByID({
collectionAddress: '0xYourContract',
assets: [
{
ownerAddress: '0xRecipient',
tokenId: '1',
metadata: {
name: 'Epic Sword',
image: 'https://...',
attributes: [{ trait_type: 'Rarity', value: 'Legendary' }],
},
},
],
});
Webhook Validation
Verify incoming webhooks from Immutable:
import { validateWebhook } from '@imtbl/webhook';
app.post('/webhook', (req, res) => {
const signature = req.headers['x-immutable-signature'] as string;
const rawBody = req.body; // Must be raw body, not parsed JSON
const isValid = validateWebhook(
rawBody,
signature,
process.env.WEBHOOK_SECRET!
);
if (!isValid) {
return res.status(403).send('Invalid signature');
}
// Process event...
res.status(200).send('OK');
});
TypeScript Configuration
Ensure your tsconfig.json includes:
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"moduleResolution": "bundler",
"esModuleInterop": true,
"strict": true
}
}
Resources
