Javascript RTSDK - Topia Client Library

The Topia Client Library leverages the Topia Public API and allows users to interact with the topia systems and modify their world programmatically. With the SDK you can now build new features to be used in Topia! Check out a list of examples here. Questions, comments, or have something exciting to share with the Topia team? Reach out to developers@topia.io!


A Topia provided API Key can be included with every object initialization as a parameter named apiKey. This API Key is used to in authorization headers in all calls to the Public API.

Want to build interactive assets? This is how you can get started:

Getting a Key Pair:

  • Navigate directly to your integrations page or follow the steps below from within a world.
    • Click on your image (or circle) at the top left of the left hand navbar.
    • Click Edit Profile. This will bring you to a separate dashboard.
    • Click Integrations on the left nav
  • Click the “Add Key Pair” button. This is going to be your public / private key pair for your app.

Adding a Key Pair to an asset:

Make an asset “interactive” by adding your PUBLIC key to the integrations page of the asset editor.

  • Go back to your world. Make sure you are in “Edit Mode” by toggling on Edit on the left nav bar
  • Hover over any asset. Click the pencil icon that should show up on hover and select “Edit”
  • Go to the Integrations tab
  • At the bottom, you'll see a section that says “Add player session credentials to asset interactions”. Toggle that on. Now webhooks that fire from this asset and iframes that open from this asset will include the following values:
    • assetId
    • interactivePublicKey
    • interactiveNonce
    • visitorId
    • urlSlug
  • The above values are included in the query params of the iframe URL as well as payload of the webhook.
  • Once you have the above values you can pass them as credentials into the factory classes when creating class instances.
await DroppedAsset.get(assetId, urlSlug, {
credentials: {

Need an API Key to test locally? This is how you can create one:

  • Navigate directly to your integrations page or follow the steps below from within a world.
    • Click on your image (or circle) at the top left of the left hand navbar.
    • Click Edit Profile. This will bring you to a separate dashboard.
    • Click Integrations on the left nav
  • Click Generate New API Key and copy the API Key to be used in your .env and while using https://sdk-examples.metaversecloud.com

Alternatively, visitors of a topia.io world interact with each other and the interactively configured assets in your world without the need for an API Key. This is all made possible through Interactive Session credentials passed to the SDK with every request, when applicable. What does this mean for you? Not much, actually! All of the magic happens behind the scenes and all you have to do is make sure that new class constructors include an options object like this: options: WorldOptionalInterface = { attributes: {}, credentials: {} } and all calls to this.topia.axios include the inherited this.requestOptions parameter.

Interactive Application Development Diagram


Need inspiration?! Check out our example application which utilizes the SDK to create new and enhanced features inside topia.io.

Get Started

Run yarn add @rtsdk/topia or npm install @rtsdk/topia

Create your instance of Topia and instantiate the factories you need:

import dotenv from "dotenv";

import { AssetFactory, Topia, DroppedAssetFactory, UserFactory, WorldFactory } from "@rtsdk/topia";

const config = {
apiDomain: process.env.INSTANCE_DOMAIN || "https://api.topia.io/",
apiKey: process.env.API_KEY,
interactiveKey: process.env.INTERACTIVE_KEY,
interactiveSecret: process.env.INTERACTIVE_SECRET,

const myTopiaInstance = new Topia(config);

const Asset = new AssetFactory(myTopiaInstance);
const DroppedAsset = new DroppedAssetFactory(myTopiaInstance);
const User = new UserFactory(myTopiaInstance);
const World = new WorldFactory(myTopiaInstance);

export { Asset, DroppedAsset, myTopiaInstance, User, World };

Put it to use:

import { DroppedAsset } from "./pathToAboveCode";

export const getAssetAndDataObject = async (req) => {
const { assetId, urlSlug } = req.body;

const droppedAsset = await DroppedAsset.get(assetId, urlSlug, {
credentials: req.body,

await droppedAsset.fetchDroppedAssetDataObject();
return droppedAsset;


Get Started

Run gh repo clone metaversecloud-com/mc-sdk-js


We've added an Issue template to help standardize Issues and ensure they have enough detail for a developer to start work and help prevent contributors from forgetting to add an important piece of information.

Pull Requests

We've added a Pull Request template to help make it easier for developers to clarify what the proposed changes will do. This helps facilitate clear communication between all contributors of the SDK and ensures that we are all on the same page!


We use TypeDoc to convert comments in TypeScript source code into rendered HTML documentation. Comments should be simple and concise and include examples where applicable. Please be sure to add or update comments accordingly!

To update docs run yarn docs.

To view docs locally open mc-sdk-js/clients/client-topia/docs/modules.html in your browser.

Example of Class comments:

* @summary
* Create an instance of Dropped Asset class with a given dropped asset id, url slug, and optional attributes and session credentials.
* @usage
* ```ts
* await new DroppedAsset(topia, "1giFZb0sQ3X27L7uGyQX", "example", { attributes: { text: "" }, credentials: { assetId: "1giFZb0sQ3X27L7uGyQX" } } });
* ```

Example of method comments

* @summary
* Sets the data object for a dropped asset.
* Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
* @usage
* ```ts
* await droppedAsset.setDroppedAssetDataObject({
* "exampleKey": "exampleValue",
* });
* const { dataObject } = droppedAsset;
* ```


We use Jest for testing and take advantage of dependency injection to pass mock data into our services.

To run the test suite, please run yarn test.