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.

Sections

• Task 1: Join Immutable Hub
• Task 2: Use Immutable Hub to create a zkEVM project
• Task 3: Create Publishable and Secret API Keys
• Task 4: Install the Immutable SDK
• How to use API Keys

---

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

💡NOTE

This tutorial uses the Immutable Typescript SDK. We will soon add our Unity and Unreal Engine SDKs to this tutorial.

Prerequisites

Node Version 20 or later

Immutable's Typescript SDK requires **Node v20** (Active LTS version) or **higher**. Node v20 can be installed via `nvm`.

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

npm install -D @imtbl/sdk
# if necessary, install dependencies
npm install -D typescript ts-node

yarn

yarn add --dev @imtbl/sdk
# if necessary, install dependencies
yarn add --dev typescript ts-node

Troubleshooting

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

rm -Rf node_modules
npm cache clean --force
npm i

yarn

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.

View on GitHub

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.