Set up your environment
Estimated time to complete: 15 minutes
Before you begin your Immutable integration, you will need to set up your environment correctly.
Task 1: Join Immutable Hub
Immutable Hub is the admin panel and learning platform for Immutable developers. Sign up typically takes between 3 and 5 minutes and you’ll be asked 8 simple questions to help us understand what you’re building.
Immutable Hub
Task 2: Use Immutable Hub to create a zkEVM project
Once you’ve set up your Immutable Hub account, you can create a project. Create a project and fill in the following in the setup flow:
- Project Name: the name of your application (e.g. My Project)
- Project Rollup: Immutable zkEVM
- Environment Name: anything you want (e.g. Testing)
- Environment Type: Testnet
Games should initially build on our testing/testnet environment before switching to production/mainnet.
Once complete, you should see the Project screen inside Immutable Hub, where you'll configure your Immutable integration for this project. Consider keeping the browser tab open so you can easily return to it later.
Task 3: Create Publishable and Secret API Keys
Once you've set up your project and environment, the next step is to create a Publishable API key as well as view your Secret API key under the environment you just created. You'll use these in the next step when you install and configure the Immutable Typescript SDK.
To create your keys, navigate to the "Keys" menu item within your project and environment to manage your API keys.
Please note that your Secret API key is only revealed during creation. Ensure that you save this key securely as it will not be displayed again.
Task 4: Install the Immutable SDK
Prerequisites
Node Version 20 or later
To install nvm
follow these instructions. Once installed, run:
nvm install --lts
- (Optional) To enable Code Splitting (importing only the SDK modules you need) there are additional prerequisites.
Install the Immutable SDK
Run the following command in your project root directory.
- npm
- yarn
npm install -D @imtbl/sdk
# if necessary, install dependencies
npm install -D typescript ts-node
yarn add --dev @imtbl/sdk
# if necessary, install dependencies
yarn add --dev typescript ts-node
The Immutable SDK is still in early development. If experiencing complications, use the following commands to ensure the most recent release of the SDK is correctly installed:
- npm
- yarn
rm -Rf node_modules
npm cache clean --force
npm i
rm -Rf node_modules
yarn cache clean
yarn install
How to use API Keys
Using the Publishable Key
Publishable Keys are used to identify your integration for tracking and analytics purposes. It's not a secret key and is safe for client-side applications, like web browsers, mobile applications and game clients as it is designed to be publicly safe and anonymous.
const baseConfig = {
environment: config.Environment.PRODUCTION,
publishableKey: YOUR_PUBLISHABLE_KEY, // Replace with your Publishable Key from the Immutable Hub
};
curl --request GET \
--url https://api.sandbox.immutable.com/v1/chains/imtbl-zkevm-testnet/collections \
-H 'Content-Type: application/json' \
-H 'x-immutable-publishable-key: [YOUR_PUBLISHABLE_KEY]'
Using the Secret API Key
Secret API Keys are used to authenticate and authorise your backend integrations with Immutable (eg. deploying a contract). Don’t expose this key on a website or embed it in a game client or mobile application.
import { config, blockchainData } from '@imtbl/sdk';
const API_KEY = 'YOUR_API_KEY';
const PUBLISHABLE_KEY = 'YOUR_PUBLISHABLE_KEY';
const client = new blockchainData.BlockchainData({
baseConfig: {
environment: config.Environment.PRODUCTION,
apiKey: API_KEY,
publishableKey: PUBLISHABLE_KEY,
},
});
curl --request POST \
--url https://api.sandbox.immutable.com/v1/chains/imtbl-zkevm-testnet/collections/0x8a90cab2b38dba80c64b7734e58ee1db38b8992e/refresh-metadata \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-immutable-api-key: [YOUR_SECRET_API_KEY]' \
--data '{
"collection_metadata": {
"name": "Gigantic Lizards",
"symbol": "GLZ",
"description": "This is the Gigantic Lizards collection",
"image": "https://some-url",
"external_link": "https://some-url",
"contract_uri": "https://some-url",
"base_uri": "https://some-url"
}
}'
Read more about the Immutable the TypeScript SDK.