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

post
Header parameters
X-Auth-KeystringRequiredExample: ababa71162175e6867058b271eea7b5b279326eaf646188ab5e37365f32bb353Pattern: [0-9a-fA-F]{64}
X-OpenVessel-Request-IdanyOptional

Unique Request Id that makes APIs idempotent. If two requests have the same ID, one of them will fail.

Example: ab62663d-1645-4026-ba2d-d888b9634de9
Body
fqTnstring · max: 255Required

Fully Qualified Token Name

Example: com.studio.game.cards.1Pattern: ^[a-z]{2,6}\.(\b[a-z0-9-]{1,59}\b)\.(\b[a-z0-9-]{1,59}\b)\.(\b[a-z0-9-]{1,59}\b)\.(\b[a-z0-9-]{1,20}\b)(:[1-9][0-9]{0,10})?
displayNamestring · max: 255Required

NFT display name

Example: Card #1
descriptionstring · max: 2000Required

NFT description

Example: Card #1 increases your luck
amountinteger · int64Required

The amount of tokens to mint

tostringOptional

To address

Example: 0xcafe000102030405060708090a0b0c0d0e0fbeefPattern: ^0x[a-fA-F0-9]{40}$
displayInDiscoverybooleanOptional

The flag that controls display in the Discovery

Default: trueExample: true
imageUrlstringOptional

NFT image

Example: jpg, pngPattern: ^(http|https)://[-a-zA-Z0-9+&@#/%?=~_|,!:.;]*[-a-zA-Z0-9+@#/%=&_|]\.(?:jpg|jpeg|png)$
Responses
202
Accepted
*/*
post
POST /tokens/manage/create HTTP/1.1
Host: game-api.openvessel.io
X-Auth-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 438

{
  "fqTn": "com.studio.game.cards.1",
  "displayName": "Card #1",
  "description": "Card #1 increases your luck",
  "properties": {
    "ANY_ADDITIONAL_PROPERTY": {
      "displayName": "text",
      "value": "text",
      "propertyOrder": 1
    }
  },
  "mutableProperties": {
    "ANY_ADDITIONAL_PROPERTY": {
      "displayName": "text",
      "value": "text",
      "propertyOrder": 1,
      "displayInDiscovery": true
    }
  },
  "amount": 1,
  "to": "0xcafe000102030405060708090a0b0c0d0e0fbeef",
  "displayInDiscovery": true,
  "imageUrl": "jpg, png"
}
{
  "response": {
    "txHash": "text",
    "description": "text",
    "details": {}
  }
}

Create new tokens multipart

Сreate new tokens multipart

post
Header parameters
X-Auth-KeystringRequiredExample: ababa71162175e6867058b271eea7b5b279326eaf646188ab5e37365f32bb353Pattern: [0-9a-fA-F]{64}
X-OpenVessel-Request-IdanyOptional

Unique Request Id that makes APIs idempotent. If two requests have the same ID, one of them will fail.

Example: ab62663d-1645-4026-ba2d-d888b9634de9
Body
imagestring · binaryRequired
Responses
202
Accepted
*/*
post
POST /tokens/manage/create-multipart HTTP/1.1
Host: game-api.openvessel.io
X-Auth-Key: text
Content-Type: multipart/form-data
Accept: */*
Content-Length: 442

{
  "data": {
    "fqTn": "com.studio.game.cards.1",
    "displayName": "Card #1",
    "description": "Card #1 increases your luck",
    "properties": {
      "ANY_ADDITIONAL_PROPERTY": {
        "displayName": "text",
        "value": "text",
        "propertyOrder": 1
      }
    },
    "mutableProperties": {
      "ANY_ADDITIONAL_PROPERTY": {
        "displayName": "text",
        "value": "text",
        "propertyOrder": 1,
        "displayInDiscovery": true
      }
    },
    "amount": 1,
    "to": "0xcafe000102030405060708090a0b0c0d0e0fbeef",
    "displayInDiscovery": true
  },
  "image": "binary"
}
{
  "response": {
    "txHash": "text",
    "description": "text",
    "details": {}
  }
}

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

post
Path parameters
fqTnstringRequired

Fully Qualified Token Name

Example: com.studio.game.cards.1Pattern: ^[a-z]{2,6}\.(\b[a-z0-9-]{1,59}\b)\.(\b[a-z0-9-]{1,59}\b)\.(\b[a-z0-9-]{1,59}\b)\.(\b[a-z0-9-]{1,20}\b)(:[1-9][0-9]{0,10})?
Header parameters
X-Auth-KeystringRequiredExample: ababa71162175e6867058b271eea7b5b279326eaf646188ab5e37365f32bb353Pattern: [0-9a-fA-F]{64}
X-OpenVessel-Request-IdanyOptional

Unique Request Id that makes APIs idempotent. If two requests have the same ID, one of them will fail.

Example: ab62663d-1645-4026-ba2d-d888b9634de9
Body
tostringOptional

Address of the token receiver

Example: 0xcafe000102030405060708090a0b0c0d0e0fbeefPattern: ^0x[a-fA-F0-9]{40}$
amountinteger · int64Required

The amount of tokens to mint

Responses
202
Accepted
*/*
post
POST /tokens/manage/{fqTn}/mint HTTP/1.1
Host: game-api.openvessel.io
X-Auth-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 62

{
  "to": "0xcafe000102030405060708090a0b0c0d0e0fbeef",
  "amount": 1
}
{
  "response": {
    "txHash": "text",
    "description": "text",
    "details": {}
  }
}

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

post
Path parameters
fqTnstringRequired

Fully qualified token name

Example: com.studio.app.collection.token
Header parameters
X-Auth-KeystringRequiredExample: ababa71162175e6867058b271eea7b5b279326eaf646188ab5e37365f32bb353Pattern: [0-9a-fA-F]{64}
X-OpenVessel-Request-IdanyOptional

Unique Request Id that makes APIs idempotent. If two requests have the same ID, one of them will fail.

Example: ab62663d-1645-4026-ba2d-d888b9634de9
Body
tostringOptional

Address of the token receiver

Example: 0xcafe000102030405060708090a0b0c0d0e0fbeefPattern: ^0x[a-fA-F0-9]{40}$
cloneMutablePropertiesbooleanOptional

Should mutable properties of parent token be clonned as well

displayInDiscoverybooleanOptional

The flag that controls display in the Discovery

Default: trueExample: true
Responses
202
Accepted
*/*
post
POST /tokens/manage/{fqTn}/clone HTTP/1.1
Host: game-api.openvessel.io
X-Auth-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 237

{
  "to": "0xcafe000102030405060708090a0b0c0d0e0fbeef",
  "mutableProperties": {
    "ANY_ADDITIONAL_PROPERTY": {
      "displayName": "text",
      "value": "text",
      "propertyOrder": 1,
      "displayInDiscovery": true
    }
  },
  "cloneMutableProperties": true,
  "displayInDiscovery": true
}
{
  "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

post
Header parameters
X-Auth-KeystringRequiredExample: ababa71162175e6867058b271eea7b5b279326eaf646188ab5e37365f32bb353Pattern: [0-9a-fA-F]{64}
X-OpenVessel-Request-IdanyOptional

Unique Request Id that makes APIs idempotent. If two requests have the same ID, one of them will fail.

Example: ab62663d-1645-4026-ba2d-d888b9634de9
Body
fromstringRequired

Owner address who approved the game for manage tokens

Example: 0xcafe000102030405060708090a0b0c0d0e0fbeefPattern: ^0x[a-fA-F0-9]{40}$
fqTnstringRequired

Fully Qualified Token Name

Example: com.studio.game.cards.1Pattern: ^[a-z]{2,6}\.(\b[a-z0-9-]{1,59}\b)\.(\b[a-z0-9-]{1,59}\b)\.(\b[a-z0-9-]{1,59}\b)\.(\b[a-z0-9-]{1,20}\b)(:[1-9][0-9]{0,10})?
quantityinteger · int64Required

The quantity of tokens to burn

Responses
202
Accepted
*/*
post
POST /tokens/manage/burn HTTP/1.1
Host: game-api.openvessel.io
X-Auth-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 99

{
  "from": "0xcafe000102030405060708090a0b0c0d0e0fbeef",
  "fqTn": "com.studio.game.cards.1",
  "quantity": 1
}
{
  "response": {
    "txHash": "text",
    "description": "text",
    "details": {}
  }
}

Burn to Mint tokens

You can consume tokens and create new tokens.

Burn to Mint player tokens

post
Header parameters
X-Auth-KeystringRequiredExample: ababa71162175e6867058b271eea7b5b279326eaf646188ab5e37365f32bb353Pattern: [0-9a-fA-F]{64}
X-OpenVessel-Request-IdanyOptional

Unique Request Id that makes APIs idempotent. If two requests have the same ID, one of them will fail.

Example: ab62663d-1645-4026-ba2d-d888b9634de9
Body
addressstringRequired

Player address

Example: 0xcafe000102030405060708090a0b0c0d0e0fbeefPattern: ^0x[a-fA-F0-9]{40}$
fqCnstringRequired

Fully Qualified Collection Name

Example: com.studio.game.cards
Responses
202
Accepted
*/*
post
POST /tokens/manage/burn-to-mint HTTP/1.1
Host: game-api.openvessel.io
X-Auth-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 173

{
  "address": "0xcafe000102030405060708090a0b0c0d0e0fbeef",
  "fqCn": "com.studio.game.cards",
  "burnTokens": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "mintTokens": {
    "ANY_ADDITIONAL_PROPERTY": 1
  }
}
{
  "response": {
    "txHash": "text",
    "description": "text",
    "details": {}
  }
}

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

get
Path parameters
fqGnstringRequired

Fully qualified game name

Example: com.studio.game
Responses
200
OK
*/*
get
GET /tokens/{fqGn}/ HTTP/1.1
Host: game-api.openvessel.io
Accept: */*

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

List collection tokens

List collection tokens

get
Path parameters
fqGnstringRequired

Fully qualified game name

Example: com.studio.game
qcnstringRequired

Collection qualified name

Example: armor01
Responses
200
OK
*/*
get
GET /tokens/{fqGn}/{qcn}/ HTTP/1.1
Host: game-api.openvessel.io
Accept: */*

{
  "response": [
    {
      "fqTn": "text",
      "totalSupply": 1,
      "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

get
Path parameters
fqGnstringRequired

Fully Qualified Game Name

Example: com.studio.game
qcnstringRequired

Qualified Collection Name

Example: armor01
qtnstringRequired

Qualified Token Name

Example: shield
Responses
200
OK
*/*
get
GET /tokens/{fqGn}/{qcn}/{qtn} HTTP/1.1
Host: game-api.openvessel.io
Accept: */*

{
  "response": {
    "collectionAddress": "text",
    "fqTn": "text",
    "createdAt": 1,
    "displayName": "text",
    "description": "text",
    "imageUrl": "text",
    "totalSupply": 1,
    "properties": {
      "ANY_ADDITIONAL_PROPERTY": {
        "displayName": "text",
        "value": "text",
        "propertyOrder": 1
      }
    },
    "mutableProperties": {
      "ANY_ADDITIONAL_PROPERTY": {
        "displayName": "text",
        "value": "text",
        "propertyOrder": 1,
        "displayInDiscovery": true
      }
    }
  }
}

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

post
Path parameters
fqTnstringRequired

Fully Qualified Collection Name

Example: com.studio.game.collection
Header parameters
X-Auth-KeystringRequiredExample: ababa71162175e6867058b271eea7b5b279326eaf646188ab5e37365f32bb353Pattern: [0-9a-fA-F]{64}
Body
displayNamestringOptional

New display name

descriptionstringOptional

New description

imageUrlstringOptional

New image URL

Responses
200
OK
post
POST /tokens/manage/{fqTn}/update-metadata HTTP/1.1
Host: game-api.openvessel.io
X-Auth-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 158

{
  "displayName": "text",
  "description": "text",
  "properties": {
    "ANY_ADDITIONAL_PROPERTY": {
      "displayName": "text",
      "value": "text",
      "propertyOrder": 1
    }
  },
  "imageUrl": "text"
}
No content

Update metadata multipart

Update metadata with image upload

post
Path parameters
fqTnstringRequired

Fully Qualified Collection Name

Example: com.studio.game.collection
Header parameters
X-Auth-KeystringRequiredExample: ababa71162175e6867058b271eea7b5b279326eaf646188ab5e37365f32bb353Pattern: [0-9a-fA-F]{64}
Body
imagestring · binaryRequired
Responses
200
OK
post
POST /tokens/manage/{fqTn}/update-metadata-multipart HTTP/1.1
Host: game-api.openvessel.io
X-Auth-Key: text
Content-Type: multipart/form-data
Accept: */*
Content-Length: 166

{
  "data": {
    "displayName": "text",
    "description": "text",
    "properties": {
      "ANY_ADDITIONAL_PROPERTY": {
        "displayName": "text",
        "value": "text",
        "propertyOrder": 1
      }
    }
  },
  "image": "binary"
}
No content

Update a single mutable property

Update token single mutable property

post
Path parameters
fqTnstringRequired

Fully qualified token name

Example: com.studio.app.collection.token
Header parameters
X-Auth-KeystringRequired

Auth token

Example: abcdefghijkPattern: [0-9a-fA-F]{64}
Body
keystringRequired

Name/key of mutable property

Example: additionalProperty
Responses
200
OK
*/*
post
POST /tokens/manage/{fqTn}/update-mutable-property HTTP/1.1
Host: game-api.openvessel.io
X-Auth-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 121

{
  "key": "additionalProperty",
  "property": {
    "displayName": "text",
    "value": "text",
    "propertyOrder": 1,
    "displayInDiscovery": true
  }
}
{
  "response": {
    "collectionAddress": "text",
    "fqTn": "text",
    "createdAt": 1,
    "displayName": "text",
    "description": "text",
    "imageUrl": "text",
    "totalSupply": 1,
    "properties": {
      "ANY_ADDITIONAL_PROPERTY": {
        "displayName": "text",
        "value": "text",
        "propertyOrder": 1
      }
    },
    "mutableProperties": {
      "ANY_ADDITIONAL_PROPERTY": {
        "displayName": "text",
        "value": "text",
        "propertyOrder": 1,
        "displayInDiscovery": true
      }
    }
  }
}

Update multiple mutable properties

Update token mutable properties

post
Path parameters
fqTnstringRequired

Fully qualified token name

Example: com.studio.app.collection.token
Header parameters
X-Auth-KeystringRequired

Auth token

Example: abcdefghijkPattern: [0-9a-fA-F]{64}
Body
Responses
200
OK
*/*
post
POST /tokens/manage/{fqTn}/update-mutable-properties HTTP/1.1
Host: game-api.openvessel.io
X-Auth-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 138

{
  "properties": [
    {
      "key": "additionalProperty",
      "property": {
        "displayName": "text",
        "value": "text",
        "propertyOrder": 1,
        "displayInDiscovery": true
      }
    }
  ]
}
{
  "response": {
    "collectionAddress": "text",
    "fqTn": "text",
    "createdAt": 1,
    "displayName": "text",
    "description": "text",
    "imageUrl": "text",
    "totalSupply": 1,
    "properties": {
      "ANY_ADDITIONAL_PROPERTY": {
        "displayName": "text",
        "value": "text",
        "propertyOrder": 1
      }
    },
    "mutableProperties": {
      "ANY_ADDITIONAL_PROPERTY": {
        "displayName": "text",
        "value": "text",
        "propertyOrder": 1,
        "displayInDiscovery": true
      }
    }
  }
}

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

post
Header parameters
X-Auth-KeystringRequiredExample: ababa71162175e6867058b271eea7b5b279326eaf646188ab5e37365f32bb353Pattern: [0-9a-fA-F]{64}
X-OpenVessel-Request-IdanyOptional

Unique Request Id that makes APIs idempotent. If two requests have the same ID, one of them will fail.

Example: ab62663d-1645-4026-ba2d-d888b9634de9
Body
tostringRequired

To Player address

Example: 0xcafe000102030405060708090a0b0c0d0e0fbeefPattern: ^0x[a-fA-F0-9]{40}$
fqCnstringRequired

Fully Qualified Collection Name

Example: com.studio.game.cards
Responses
202
Accepted
*/*
post
POST /tokens/manage/transfer HTTP/1.1
Host: game-api.openvessel.io
X-Auth-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 121

{
  "to": "0xcafe000102030405060708090a0b0c0d0e0fbeef",
  "fqCn": "com.studio.game.cards",
  "tokens": {
    "ANY_ADDITIONAL_PROPERTY": 1
  }
}
{
  "response": {
    "txHash": "text",
    "description": "text",
    "details": {}
  }
}

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.

PreviousCollectionsNextMarketplace

Last updated

Was this helpful?