Skip to main content

{/ If you rename/move this file, please update https://github.com/immutable/ts-immutable-sdk/blob/main/.github/scripts/update-docs-link.sh /}

Typescript SDK

This SDK provides access to a wide range of features allowing you to integrate your game with key blockchain functionality.

💡Rollups this SDK supports

Sections
📚SDK links

Installation​

Prerequisites​

Node Version >18
Immutable's Typescript SDK requires **Node v18** (Active LTS version) or **higher**. Node v18 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. See the Code Splitting section below.

Install the Immutable SDK​

Run the following command in your project root directory.

npm install -D @imtbl/sdk
# if necessary, install dependencies
npm install -D 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:

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

Initialization​

Each module of the Immutable SDK must be initialised with an instance of an ImmutableConfiguration. The ImmutableConfiguration defines configuration that is shared across modules, such as the current environment.
An instance of an ImmutableConfiguration can be initialised as follows:

Using the Publishable Key​

What is the Publishable Key for?
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]'
More information on Publishable Key can be found here
💡Environments

The environment argument can be one of the following:

Environment ConfigurationDescription
Environment.SANDBOXThe default test network (currently, it is Sepolia)
Environment.PRODUCTIONThe Ethereum mainnet network

SDK modules can then be initialised as follows:

import { passport, x } from '@imtbl/sdk';

const passport = new passport.Passport({
  baseConfig,
  // Passport specific configuration
});

const provider = new x.GenericIMXProvider({
  baseConfig,
  // Provider specific configuration
});

Using the Secret API Key​

What is the Secret API Key for?
Secret API Keys are used to authenticate and authorise your backend integrations with Immutable. 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 client = new blockchainData.BlockchainData({
  baseConfig: {
    environment: config.Environment.PRODUCTION,
    apiKey: YOUR_SECRET_API_KEY,
    publishableKey: YOUR_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"
  }
}'

List of endpoints that require Secret API Key authorization​

NameEndpointMethodType
Refresh Stacked metadata/v1/chains/{chain_name}/collections/{contract_address}/metadata/refresh-metadataPOSTMetadata Refresh
Refresh NFT metadata/v1/chains/{chain_name}/collections/{contract_address}/nfts/refresh-metadataPOSTMetadata Refresh

Learn more about secret API keys here.​

Browser Bundle​

Our SDK is available publicly, and therefore there are a few services that you can use to serve the browser bundle to your webpage:

Both services allow specifying versions of the SDK to use, so if you want a specific version, with levels of specificity. For example:

  • If you want a specific version (e.g. 1.23.3), specify it fully.
    • https://cdn.jsdelivr.net/npm/@imtbl/sdk@1.23.3
  • If you want a minor version:
    • https://cdn.jsdelivr.net/npm/@imtbl/sdk@1.23
  • If you want to support a major version:
    • https://cdn.jsdelivr.net/npm/@imtbl/sdk@1

You can load the script directly in your webpage, like any other script tag, for example:

<script src="https://cdn.jsdelivr.net/npm/@imtbl/sdk@1.20.0"></script>

Once loaded, you can access the immutable SDK via the window.immutable object.

If you plan to specify a version, you can check the latest release version on our NPM page.

Browser bundle in console

From there, please look at each product's documentation on how to use each of the available modules.

Code Splitting​

The Immutable SDK is designed to be used in a code-splitting environment, such as a web browser.

Your project will need some specific configuration to enable code splitting:

  • Typescript version 5 or higher
  • TS Config needs to have compilerOptions.moduleResolution set to bundler
  • Your code editor and project should have the same version of Typescript
// old import method
import { config, blockchainData } from '@imtbl/sdk';
const env = config.Environment.SANDBOX;
const client = new blockchainData.BlockchainData();

// new import method with code-splitting
import { Environment } from '@imtbl/sdk/config';
//                              module name is now snake_case
import { BlockchainData } from '@imtbl/sdk/blockchain_data';

Importing modules this way has the added benefit of allowing you to see all the available types within the module root so they can be imported individually.

Further documentation​

Troubleshooting​