Tokens

* is a required field

Make sure to use your X-Auth-Token when making a POST request. Your X-Auth-Token is the private key associated to your ERC-20 wallet.

It is strongly not recommended to use Mint/Clone/Burn in any game as it can cause uncontrolled access to your studio wallet and expose the private key. Mint/Clone/Burn should be done via the Vessel dashboard.

Create Tokens

Create new tokens

Create new tokens

POSThttps://game-api.openvessel.io/tokens/manage/create

Header parameters

Body

application/json

fqTn*string

Fully Qualified Token Name

displayName*string

NFT display name

description*string

NFT description

propertiesobject

Arbitrary immutable properties

mutablePropertiesobject

Arbitrary mutable properties

amount*integer (int64)

The amount of tokens to mint

tostring

To address

displayInDiscoveryboolean

The flag that controls display in the Discovery

imageUrlstring

NFT image

Response

202400401403404405409429500

Accepted

Body

*/*

response*ManageResponseObject (object)

Request

JavaScriptCurl

const response = await fetch('https://game-api.openvessel.io/tokens/manage/create', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "description": "Card #1 increases your luck",
      "displayName": "Card #1",
      "fqTn": "com.studio.game.cards.1"
    }),
});
const data = await response.json();

Response

{
  "response": {
    "txHash": "text",
    "description": "text"
  }
}

Create new tokens multipart

Сreate new tokens multipart

POSThttps://game-api.openvessel.io/tokens/manage/create-multipart

Header parameters

Body

multipart/form-dataapplication/json

data*CreateNftRequest (object)

image*string (binary)

Response

202400401403404405409429500

Accepted

Body

*/*

response*ManageResponseObject (object)

Request

JavaScriptCurl

const response = await fetch('https://game-api.openvessel.io/tokens/manage/create-multipart', {
    method: 'POST',
    headers: {
      "Content-Type": "multipart/form-data"
    },
    body: JSON.stringify({
      "data": {
        "description": "Card #1 increases your luck",
        "displayName": "Card #1",
        "fqTn": "com.studio.game.cards.1"
      },
      "image": "binary"
    }),
});
const data = await response.json();

Response

{
  "response": {
    "txHash": "text",
    "description": "text"
  }
}

create vs create-multipart

You need to upload the image somewhere and post the URL when you use /tokens/manage/create API. Once it is created, we store image data in our DB.

On the other hand, you can post the image binary directly to us if you use /tokens/manage/create-multipart API.

Mint/Clone/Burn Tokens

Mint tokens

You can create new tokens specified by fqTn and give it to the user wallet.

Mint tokens

POSThttps://game-api.openvessel.io/tokens/manage/{fqTn}/mint

Path parameters

fqTn*string

Fully Qualified Token Name

Header parameters

Body

application/json

tostring

Address of the token receiver

amount*integer (int64)

The amount of tokens to mint

Response

202400401403404405409429500

Accepted

Body

*/*

response*ManageResponseObject (object)

Request

JavaScriptCurl

const response = await fetch('https://game-api.openvessel.io/tokens/manage/{fqTn}/mint', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "response": {
    "txHash": "text",
    "description": "text"
  }
}

Clone tokens

You can clone and create new tokens from a parent token specified by fqTn. Cloned tokens have different fqTn from the parent token.

Create a clone token based on parent fqTn

POSThttps://game-api.openvessel.io/tokens/manage/{fqTn}/clone

Path parameters

fqTn*string

Fully qualified token name

Header parameters

Body

application/json

tostring

Address of the token receiver

mutablePropertiesobject

Arbitrary mutable properties

cloneMutablePropertiesboolean

Should mutable properties of parent token be clonned as well

displayInDiscoveryboolean

The flag that controls display in the Discovery

Response

202400401403404405409429500

Accepted

Body

*/*

response*ManageResponseCloneTokenResponse (object)

Request

JavaScriptCurl

const response = await fetch('https://game-api.openvessel.io/tokens/manage/{fqTn}/clone', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "response": {
    "txHash": "text",
    "description": "text",
    "details": {
      "fqTn": "text"
    }
  }
}

Burn tokens

You can consume tokens. Consumed tokens will be removed from the user wallet.

Burn player tokens

POSThttps://game-api.openvessel.io/tokens/manage/burn

Header parameters

Body

application/json

from*string

Owner address who approved the game for manage tokens

fqTn*string

Fully Qualified Token Name

quantity*integer (int64)

The quantity of tokens to burn

Response

202400401403404405409429500

Accepted

Body

*/*

response*ManageResponseObject (object)

Request

JavaScriptCurl

const response = await fetch('https://game-api.openvessel.io/tokens/manage/burn', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "fqTn": "com.studio.game.cards.1",
      "from": "0xcafe000102030405060708090a0b0c0d0e0fbeef"
    }),
});
const data = await response.json();

Response

{
  "response": {
    "txHash": "text",
    "description": "text"
  }
}

Burn to Mint tokens

You can consume tokens and create new tokens.

Burn to Mint player tokens

POSThttps://game-api.openvessel.io/tokens/manage/burn-to-mint

Header parameters

Body

application/json

address*string

Player address

fqCn*string

Fully Qualified Collection Name

burnTokens*object

Tokens set to burn

mintTokens*object

Tokens set to mint

Response

202400401403404405409429500

Accepted

Body

*/*

response*ManageResponseObject (object)

Request

JavaScriptCurl

const response = await fetch('https://game-api.openvessel.io/tokens/manage/burn-to-mint', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "address": "0xcafe000102030405060708090a0b0c0d0e0fbeef",
      "fqCn": "com.studio.game.cards"
    }),
});
const data = await response.json();

Response

{
  "response": {
    "txHash": "text",
    "description": "text"
  }
}

Mint vs Clone

There are two APIs for creating and giving a new token to a user, Mint and Clone.

If you use Mint API, the token created has the identical fqTn as the original one. If you Mint com.studio.sword.greatsword, the user will get com.studio.sword.greatsword in the wallet. On the other hand, If you Clone com.studio.sword.greatsword , a new token com.studio.sword.greatsword:1 is created and added to the user wallet. In short, Clone API will create a variation of the original token.

Here's the side-by-side comparison for both APIs.

	Mint	Clone
fqTn	identical	:N is appended
Display Name	identical	#N is appended
Description	identical	identical
Immutable Properties	identical	identical
Mutable Properties	identical	new values can be set

If you just need to give a specific item to a user and all those items share the same properties in your app, our Mint API is recommended. If each token has different mutable parameter that can be changed in the gameplay (e.g. level) , you need to use Clone API.

Token Details

List game tokens

List game tokens

GEThttps://game-api.openvessel.io/tokens/{fqGn}/

Path parameters

fqGn*string

Fully qualified game name

Response

200400401403404405409429500

OK

Body

*/*

response*array of TokenInfoResponse (object)

Request

JavaScriptCurl

const response = await fetch('https://game-api.openvessel.io/tokens/{fqGn}/', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "response": [
    {
      "fqTn": "text",
      "displayName": "text"
    }
  ]
}

List collection tokens

List collection tokens

GEThttps://game-api.openvessel.io/tokens/{fqGn}/{qcn}/

Path parameters

fqGn*string

Fully qualified game name

qcn*string

Collection qualified name

Response

200400401403404405409429500

OK

Body

*/*

response*array of TokenInfoResponse (object)

Request

JavaScriptCurl

const response = await fetch('https://game-api.openvessel.io/tokens/{fqGn}/{qcn}/', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "response": [
    {
      "fqTn": "text",
      "displayName": "text"
    }
  ]
}

Token Object

Name	Type	Description
displayName	string	Display name of the token
fqTn	string	Fully qualified token name
totalSupply	number	Total number of minted tokens

Get details of the specific token

GEThttps://game-api.openvessel.io/tokens/{fqGn}/{qcn}/{qtn}

Path parameters

fqGn*string

Fully Qualified Game Name

qcn*string

Qualified Collection Name

qtn*string

Qualified Token Name

Response

200400401403404405409429500

OK

Body

*/*

response*TokenDetailsResponse (object)

Request

JavaScriptCurl

const response = await fetch('https://game-api.openvessel.io/tokens/{fqGn}/{qcn}/{qtn}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "response": {
    "collectionAddress": "text",
    "fqTn": "text",
    "displayName": "text",
    "description": "text",
    "imageUrl": "text"
  }
}

Token Details Object

Name	Type	Description
displayName	string	Display name of the token
description	string	Token description
imageUrl	string	URL that points to the token image
fqTn	string	Fully qualified token name
collectionAddress	string	Blockchain address of the collection this token belongs to
totalSupply	number	Total number of minted tokens
properties	object	An object that contains the token’s immutable properties
mutableProperties	object	An object that contains the token’s mutable properties
createdAt	number	Unix timestamp of the token’s creation time

Token Metadata

Update metadata

Update metadata

POSThttps://game-api.openvessel.io/tokens/manage/{fqTn}/update-metadata

Path parameters

fqTn*string

Fully Qualified Collection Name

Header parameters

Body

application/json

displayNamestring

New display name

descriptionstring

New description

propertiesobject

Arbitrary immutable properties

imageUrlstring

New image URL

Response

200400401403404405409429500

OK

Request

JavaScriptCurl

const response = await fetch('https://game-api.openvessel.io/tokens/manage/{fqTn}/update-metadata', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Update metadata multipart

Update metadata with image upload

POSThttps://game-api.openvessel.io/tokens/manage/{fqTn}/update-metadata-multipart

Path parameters

fqTn*string

Fully Qualified Collection Name

Header parameters

Body

multipart/form-dataapplication/json

data*UpdateTokenMetadataRequest (object)

image*string (binary)

Response

200400401403404405409429500

OK

Request

JavaScriptCurl

const response = await fetch('https://game-api.openvessel.io/tokens/manage/{fqTn}/update-metadata-multipart', {
    method: 'POST',
    headers: {
      "Content-Type": "multipart/form-data"
    },
    body: JSON.stringify({
      "data": {},
      "image": "binary"
    }),
});
const data = await response.json();

Update a single mutable property

Update token single mutable property

POSThttps://game-api.openvessel.io/tokens/manage/{fqTn}/update-mutable-property

Path parameters

fqTn*string

Fully qualified token name

Header parameters

Body

application/json

key*string

Name/key of mutable property

property*NftMutablePropertyRequest (object)

Body of mutable property

Response

200400401403404405409429500

OK

Body

*/*

response*TokenDetailsResponse (object)

Request

JavaScriptCurl

const response = await fetch('https://game-api.openvessel.io/tokens/manage/{fqTn}/update-mutable-property', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "key": "additionalProperty",
      "property": {
        "displayName": "text",
        "value": "text"
      }
    }),
});
const data = await response.json();

Response

{
  "response": {
    "collectionAddress": "text",
    "fqTn": "text",
    "displayName": "text",
    "description": "text",
    "imageUrl": "text"
  }
}

Update multiple mutable properties

Update token mutable properties

POSThttps://game-api.openvessel.io/tokens/manage/{fqTn}/update-mutable-properties

Path parameters

fqTn*string

Fully qualified token name

Header parameters

Body

application/json

properties*array of UpdateMutablePropertyRequest (object)

Properties to update/add

Response

200400401403404405409429500

OK

Body

*/*

response*TokenDetailsResponse (object)

Request

JavaScriptCurl

const response = await fetch('https://game-api.openvessel.io/tokens/manage/{fqTn}/update-mutable-properties', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "properties": [
        {
          "key": "additionalProperty",
          "property": {
            "displayName": "text",
            "value": "text"
          }
        }
      ]
    }),
});
const data = await response.json();

Response

{
  "response": {
    "collectionAddress": "text",
    "fqTn": "text",
    "displayName": "text",
    "description": "text",
    "imageUrl": "text"
  }
}

Mutable Properties

Minted tokens can have multiple mutable properties. These properties persist outside of Vessel’s blockchain.

The properties object maps property keys to their values. For example:

{
    "favorite_weapon": {
        "displayName": "Favorite Weapon",
        "value": "Club"
    }
}

In this example, favorite_weapon is the property key which maps to its current value along with the display name.

Transfer Tokens

Transfer tokens between players and studio

Transfer tokens between players and studio

POSThttps://game-api.openvessel.io/tokens/manage/transfer

Header parameters

Body

application/json

to*string

To Player address

fqCn*string

Fully Qualified Collection Name

tokens*object

A map of tokenId to amount of tokens to send to the user

Response

202400401403404405409429500

Accepted

Body

*/*

response*ManageResponseObject (object)

Request

JavaScriptCurl

const response = await fetch('https://game-api.openvessel.io/tokens/manage/transfer', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "fqCn": "com.studio.game.cards",
      "to": "0xcafe000102030405060708090a0b0c0d0e0fbeef"
    }),
});
const data = await response.json();

Response

{
  "response": {
    "txHash": "text",
    "description": "text"
  }
}

There's rate limit for API calls and it's 5,000/hour. If you want to increase the threshold, please reach out to your Vessel account manager.

Once you hit the rate limit, API returns http response code 429. In that case, you can retry to call the API after several minutes.