Documentation

Server-Side SDK

Suggest Edits

Our SDK is available on github.

To install the SDK (or clone from GitHub):

npm i chainengine-sdk

Configure your project to use the SDK:

import { ChainEngineSdk } from 'chainengine-sdk';

sdk = new ChainEngineSdk('https://api.chainengine.xyz', YOUR_API_KEY, YOUR_API_SECRET);

Please create the first game on the developer console, and copy and save your game ID. We will need that to make requests.

Below you'll find a few examples of how you can use the SDK.

Mint your first NFT

Let's start by minting your first NFT, please substitute YOUR_GAME_ID with your game id from the developer console.

const gameId = 'YOUR_GAME_ID';

sdk.nfts.mintToGame(
  {
    name: 'Hammer',
    description: 'Hammer v.1',
    imageURI: 'https://62acd7e8d87dbc18617c656a--moonlit-sundae-d1789e.netlify.app/NFTs/hammer_00.jpg',
    attributes: {
      weight: '10kg',
      color: 'red',
      material: 'steel',
      manufacturer: 'Hammer Manufacturer',
      model: 'Hammer Model',
    },
    supply: 10,
  },
  gameId
);
We just minted our first NFT! Click to see the response 
{
  "status": "OK",
  "data": {
    "id": "5b52a2e2-6ffa-4edf-9d99-23fe8fabf72d",
    "contractAddress": "0x02562366454b90b21E4D291fCE28b9a208D2D662",
    "onChainId": "5",
    "chain": "polygon",
    "transactionHash": "0x8547e466ac93e34df02643b28a11daabe4c46a5e9ceb095aa1e13a70534fbe35",
    "accountId": "test2",
    "gameId": "26716535-bb9a-4ad4-afb1-4effa5a7830b",
    "status": "ONCHAIN",
    "metadata": {
      "name": "Hammer",
      "description": "Hammer v.1",
      "image": "http://api.chainengine.xyz/nfts/5b52a2e2-6ffa-4edf-9d99-23fe8fabf72d/image",
      "attributes": {
        "weight": "10kg",
        "color": "red",
        "material": "steel",
        "manufacturer": "Hammer Manufacturer",
        "model": "Hammer Model"
      },
      "URI": "ipfs://QmUxJdroj17EXNceFGtzL4gxwM8uU18x6dQ3hyA58oBk2A"
    },
    "supply": 10,
    "supplyAvailable": 10
  }
}

Actual transaction is also available on the chain explorer.

Most of the SDK calls return type ResponseDto which has an error status and a data field with actual response data.

Fetch NFT by Id

To fetch an already minted NFT:

const nftId = '5b52a2e2-6ffa-4edf-9d99-23fe8fabf72d';
sdk.nfts.getNftById(nftId);

The response is the same as the mint function.

Create a player

To transfer an NFT to the player, we need to create our first player:

sdk.players.create({
  gameId: gameId,
  walletAddress: '0x32c45d580DE0F6126941bfb8ff2181e778545E85',
});
Click to see the response 
{
  "data": {
    "player": {
      "id": "f406fb49-832f-4fe1-8df6-2f93ba5544c1",
      "gameId": "26716535-bb9a-4ad4-afb1-4effa5a7830b",
      "walletAddress": "0x32c45d580DE0F6126941bfb8ff2181e778545E85"
    }
  },
  "status": "OK"
}

In this case, we have created a new player with a non-custodial wallet (to create a custodial wallet, please read our Custodial Wallets guide).

The non-custodial wallet can be connected through our Unity SDK. Learn more about our Unity SDK here.

Transfer NFT to the player

After the player is created, we can transfer NFT to a player ( substitute the already created playerId and nftId):

const nftId = '5b52a2e2-6ffa-4edf-9d99-23fe8fabf72d';
const playerId = 'f406fb49-832f-4fe1-8df6-2f93ba5544c1';
const response = await sdk.nfts.transfer({ playerId: playerId, amount: 3 }, nftId);
Click to see the response 
{
  "data": {
    "id": "5b52a2e2-6ffa-4edf-9d99-23fe8fabf72d",
    "contractAddress": "0x02562366454b90b21E4D291fCE28b9a208D2D662",
    "onChainId": "5",
    "chain": "polygon",
    "transactionHash": "0x8547e466ac93e34df02643b28a11daabe4c46a5e9ceb095aa1e13a70534fbe35",
    "accountId": "test2",
    "gameId": "26716535-bb9a-4ad4-afb1-4effa5a7830b",
    "status": "ONCHAIN",
    "metadata": {
      "name": "Hammer",
      "description": "Hammer v.1",
      "image": "https://62acd7e8d87dbc18617c656a--moonlit-sundae-d1789e.netlify.app/NFTs/hammer_00.jpg",
      "attributes": {
        "weight": "10kg",
        "color": "red",
        "material": "steel",
        "manufacturer": "Hammer Manufacturer",
        "model": "Hammer Model"
      },
      "URI": "ipfs://QmUxJdroj17EXNceFGtzL4gxwM8uU18x6dQ3hyA58oBk2A"
    },
    "holders": {
      "f406fb49-832f-4fe1-8df6-2f93ba5544c1": 3
    },
    "supply": 10,
    "supplyAvailable": 7
  },
  "status": "OK"
}

That's it, we just transferred NFT to a player, developer console now has transfer history (mint and transfer transactions):

1873

Get NFT owned by the player

To fetch the NFT ownership of the player who has just received NFT, we can do the following:

const playerId = 'f406fb49-832f-4fe1-8df6-2f93ba5544c1';
const response = await this.sdk.nfts.getNFTsByParams({
  queryBy: FetchType.Player,
  id: playerId,
  page: 1,
  limit: 10,
});

Note: To implement this, please ensure that you add the line below at the beginning of your code:

import {ChainEngineSdk} from 'chainengine-sdk/dist/nft/fetch.type.js';

The response includes all NFTs owned by a particular player. In this case, we have only 1 NFT.

Click to see the response 
{
  "data": {
    "page": 1,
    "offset": 0,
    "total": 1,
    "items": [
      {
        "nfts": [
          {
            "id": "5b52a2e2-6ffa-4edf-9d99-23fe8fabf72d",
            "contractAddress": "0x02562366454b90b21E4D291fCE28b9a208D2D662",
            "onChainId": "5",
            "chain": "polygon",
            "transactionHash": "0x8547e466ac93e34df02643b28a11daabe4c46a5e9ceb095aa1e13a70534fbe35",
            "accountId": "test2",
            "gameId": "26716535-bb9a-4ad4-afb1-4effa5a7830b",
            "status": "ONCHAIN",
            "metadata": {
              "name": "Hammer",
              "description": "Hammer v.1",
              "image": "http://api.chainengine.xyz/nfts/5b52a2e2-6ffa-4edf-9d99-23fe8fabf72d/image",
              "attributes": {
                "weight": "10kg",
                "color": "red",
                "material": "steel",
                "manufacturer": "Hammer Manufacturer",
                "model": "Hammer Model"
              },
              "URI": "ipfs://QmUxJdroj17EXNceFGtzL4gxwM8uU18x6dQ3hyA58oBk2A"
            },
            "holders": {
              "f406fb49-832f-4fe1-8df6-2f93ba5544c1": 3
            },
            "supply": 10,
            "supplyAvailable": 7
          }
        ]
      }
    ]
  },
  "status": "OK"
}

Get all game NFTs

To get all the NFTs in the game, simply query by game ID:

sdk.nfts.getNFTsByParams({
  queryBy: FetchType.Game,
  id: gameId,
  page: 1,
  limit: 10,
});
Click to see the response 
{
  "data": {
    "page": 1,
    "offset": 0,
    "total": 5,
    "items": [
      {
        "nfts": [
          {
            "id": "279fc7f7-4bf5-445b-9f5c-a1db7237ba12",
            "contractAddress": "0x8613C93189A281D7b6CEE65814B304dB127e0eeA",
            "onChainId": "63",
            "chain": "polygon",
            "transactionHash": "0x165c6e7c0e37b5e81f76b24695aa64355cd9a08898057a2eb7e80c0f48bfd4de",
            "accountId": "test2",
            "gameId": "26716535-bb9a-4ad4-afb1-4effa5a7830b",
            "status": "ONCHAIN",
            "metadata": {
              "name": "Hammer",
              "description": "Hammer v.1",
              "image": "http://api.chainengine.xyz/nfts/279fc7f7-4bf5-445b-9f5c-a1db7237ba12/image",
              "attributes": {
                "weight": "10kg",
                "color": "red",
                "material": "steel",
                "manufacturer": "Hammer Manufacturer",
                "model": "Hammer Model"
              },
              "URI": "ipfs://QmUxJdroj17EXNceFGtzL4gxwM8uU18x6dQ3hyA58oBk2A"
            },
            "supply": 1,
            "supplyAvailable": 0
          },
....
          {
            "id": "5b52a2e2-6ffa-4edf-9d99-23fe8fabf72d",
            "contractAddress": "0x02562366454b90b21E4D291fCE28b9a208D2D662",
            "onChainId": "5",
            "chain": "polygon",
            "transactionHash": "0x8547e466ac93e34df02643b28a11daabe4c46a5e9ceb095aa1e13a70534fbe35",
            "accountId": "test2",
            "gameId": "26716535-bb9a-4ad4-afb1-4effa5a7830b",
            "status": "ONCHAIN",
            "metadata": {
              "name": "Hammer",
              "description": "Hammer v.1",
              "image": "http://api.chainengine.xyz/nfts/5b52a2e2-6ffa-4edf-9d99-23fe8fabf72d/image",
              "attributes": {
                "weight": "10kg",
                "color": "red",
                "material": "steel",
                "manufacturer": "Hammer Manufacturer",
                "model": "Hammer Model"
              },
              "URI": "ipfs://QmUxJdroj17EXNceFGtzL4gxwM8uU18x6dQ3hyA58oBk2A"
            },
            "holders": {
              "f406fb49-832f-4fe1-8df6-2f93ba5544c1": 3
            },
            "supply": 10,
            "supplyAvailable": 7
          }
        ]
      }
    ]
  },
  "status": "OK"
}

Upload image to IPFS

To upload images to IPFS using our SDK you will need to provide a ReadStream of the image file.
You can use the following code to get a ReadStream from a file and upload the file.

const fileReadStream = await fs.createReadStream(`sample-image.jpg`);
const uploadResponse = await sdk.nfts.uploadFileToIPFS(file);

The response includes a URL that you can use to access the image from IPFS.

You can then use this URL in the NFT metadata.

Click to see the response 
{
  "data": {
    "url": "ipfs://QmUxJdroj17EXNceFGtzL4gxwM8uU18x6dQ3hyA58oBk2A",
  },
  "status": "OK"
}

Create NFT Listing

As game developer to create an NFT listing you will need to use the following code:

sdk.marketplace.listings.create({
    "nftId": '5b52a2e2-6ffa-4edf-9d99-23fe8fabf72d',
    "amount": 1,
    "price": 0.0001,
    "receiptWallet": '0x32c45d580DE0F6126941bfb8ff2181e778545E85',
});

Note: The receiptWallet is the wallet address that will receive the payment when the NFT is sold; ChainEngine do not hold any funds.

The response will include the listing ID that you can use to update or delete the listing.

Click to see the response 
{
  "data": {
    "id": "5b52a2e2-6ffa-4edf-9d99-23fe8fabf72d",
    "nftId": "5b52a2e2-6ffa-4edf-9d99-23fe8fabf72d",
    "amount": 1,
    "price": 0.0001,
    "receiptWallet": "0x32c45d580DE0F6126941bfb8ff2181e778545E85",
    "status": "active",
  },
  "status": "OK"
}

Fetch an existing listing

To fetch an existing listing you can use the following code:

sdk.marketplace.listings.getSingle('5b52a2e2-6ffa-4edf-9d99-23fe8fabf72d');

The response will include the listing details.

Click to see the response 
{
  "data": {
    "id": "5b52a2e2-6ffa-4edf-9d99-23fe8fabf72d",
    "nftId": "5b52a2e2-6ffa-4edf-9d99-23fe8fabf72d",
    "amount": 1,
    "price": 0.0001,
    "receiptWallet": "0x32c45d580DE0F6126941bfb8ff2181e778545E85",
    "status": "active",
  },
  "status": "OK"
}

Cancel an existing listing

To cancel an existing listing you can use the following code:

sdk.marketplace.listings.cancel('5b52a2e2-6ffa-4edf-9d99-23fe8fabf72d');

The response will include the listing details containing the updated status.

Click to see the response 
{
  "data": {
    "id": "5b52a2e2-6ffa-4edf-9d99-23fe8fabf72d",
    "nftId": "5b52a2e2-6ffa-4edf-9d99-23fe8fabf72d",
    "amount": 1,
    "price": 0.0001,
    "receiptWallet": "0x32c45d580DE0F6126941bfb8ff2181e778545E85",
    "status": "canceled",
  },
  "status": "OK"
}

Fetch listings using a query

When fetching for listings you can use some query parameters to execute filtering. The following parameters are available:

  • gameId - Filter by Game ID
  • search - Filter by searching in the NFT name
sdk.marketplace.listings.getByQuery({
    gameId: '26716535-bb9a-4ad4-afb1-4effa5a7830b',
    search: 'Hammer',
});

The response will include a list of listing tha match the filtering criteria.

Click to see the response 
{
  "data": [
    {
      "id": "5b52a2e2-6ffa-4edf-9d99-23fe8fabf72d",
      "nftId": "5b52a2e2-6ffa-4edf-9d99-23fe8fabf72d",
      "amount": 1,
      "price": 0.0001,
      "receiptWallet": "0x32c45d580DE0F6126941bfb8ff2181e778545E85",
      "status": "active",
    },
  ],
  "status": "OK"
}

Updated 6 months ago

What’s Next