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

*/*

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

405

Method Not Allowed

*/*

409

Conflict

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post

HTTPcURLJavaScriptPython

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

multipart/form-dataapplication/json

imagestring · binaryRequired

Responses

202

Accepted

*/*

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

405

Method Not Allowed

*/*

409

Conflict

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post

HTTPcURLJavaScriptPython

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"
}

multipart/form-dataapplication/json

{
  "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

*/*

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

405

Method Not Allowed

*/*

409

Conflict

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post

HTTPcURLJavaScriptPython

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

*/*

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

405

Method Not Allowed

*/*

409

Conflict

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post

HTTPcURLJavaScriptPython

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

*/*

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

405

Method Not Allowed

*/*

409

Conflict

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post

HTTPcURLJavaScriptPython

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

*/*

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

405

Method Not Allowed

*/*

409

Conflict

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post

HTTPcURLJavaScriptPython

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

*/*

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

405

Method Not Allowed

*/*

409

Conflict

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get

HTTPcURLJavaScriptPython

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

*/*

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

405

Method Not Allowed

*/*

409

Conflict

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get

HTTPcURLJavaScriptPython

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

*/*

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

405

Method Not Allowed

*/*

409

Conflict

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get

HTTPcURLJavaScriptPython

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

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

405

Method Not Allowed

*/*

409

Conflict

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post

HTTPcURLJavaScriptPython

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

multipart/form-dataapplication/json

imagestring · binaryRequired

Responses

200

OK

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

405

Method Not Allowed

*/*

409

Conflict

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post

HTTPcURLJavaScriptPython

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"
}

multipart/form-dataapplication/json

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

*/*

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

405

Method Not Allowed

*/*

409

Conflict

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post

HTTPcURLJavaScriptPython

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

*/*

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

405

Method Not Allowed

*/*

409

Conflict

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post

HTTPcURLJavaScriptPython

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

*/*

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

405

Method Not Allowed

*/*

409

Conflict

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post

HTTPcURLJavaScriptPython

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.