Getting Started

Welcome to Vessel! Take the following steps to get started:

1. Request Vessel Account Setup

Ask your account manager to grant you access to Vessel in the AppLovin dashboard.

2. Create an Ethereum Studio Wallet

Use Metamask or another ERC-20 wallet company to create an Ethereum-based wallet. Once you have created your wallet, let your Vessel account manager know the wallet address. Your wallet will be connected to the account and used to make API calls and receive royalties from transactions.

You can grant access to additional wallets and modify permissions through the Account Management section of our Vessel Dashboard.

3. Create a New Game

Once you have access to Vessel, login into the Staging Dashboard and click ADD GAME to begin adding your game to Vessel.

Game Creation Screen

Here's a breakdown of the required information on the Create New Game form:

Name	Description
App ID	Enter a game name. Vessel uses this name to query the Game API for a list of tokens that belong to a game or a user.
Display Name	Enter a user-friendly game name to be displayed on the marketplace.
Description	Enter a short, user-friendly description of the game to be displayed on the marketplace.
Image	Upload a 200x200 pixel game icon to be displayed on the marketplace.
Background Image	Upload an 800x300 pixel image to be displayed as a background on the marketplace.
Owner	Enter the wallet address of the game owner.
App Info	Click ADD INFO and enter the package name of the game and the app's public key (Android only). You can do this multiple times to add additional package names. You can find your app's public key on the Google Play console.

Important: You need to add the correct package name of your app to connect the Vessel wallet.

Important: Using the same wallet address both for Royalty Wallet (Studio Wallet) and game owner wallet is not recommended for security reasons.

4. Create a New Token Collection Template

Click the name of your newly created game, then click + ADD COLLECTION TEMPLATE in the COLLECTION TEMPLATES tab to begin the process of creating a new token collection template:

Collection Template Creation Screen

The following table explains the fields you need to enter on the Create collection template form:

Name	Description
Collection ID	Enter a qualified collection name. Vessel uses this name to query the Game API for a list of tokens that belong to this collection.
Display Name	Enter a user-friendly name of the collection, to be displayed on the marketplace.
Description	Enter a short, user-friendly description of the collection, to be displayed on the marketplace.
Image	Upload a 500x500 pixel icon representing the collection, to be displayed on the marketplace.

5. Deploy a Token Collection

Deploy your newly created token collection template to the blockchain by clicking DEPLOY.

Deploy Collection Screen

You can see your newly deployed collection in the DEPLOYED COLLECTIONS tab. It may take a few seconds after you click DEPLOY before the collection appears in this tab.

Deployed Collection

You can also create and deploy a token collection by making an API POST request:

post

Path parameters

fqGnstringRequired

Fully Qualified Game Name

Example: com.studio.game

Header parameters

X-Auth-KeystringOptionalDefault: ""

Body

displayNamestring · max: 255Required

Collection display name

Example: New year cards

descriptionstring · max: 2000Required

Collection description

Example: Super game new year cards

imageUrlstring · max: 255Required

Main image

Example: Collection image

qCnstring · max: 64Required

Qualified Collection Name

Example: cardsPattern: (\b[a-z0-9-]{1,20}\b)(:[1-9][0-9]{0,10})?

Responses

201

Created

*/*

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 /collections/manage/{fqGn}/create HTTP/1.1
Host: game-api.openvessel.io
Content-Type: application/json
Accept: */*
Content-Length: 118

{
  "displayName": "New year cards",
  "description": "Super game new year cards",
  "imageUrl": "Collection image",
  "qCn": "cards"
}

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

6. Create a New Token Template

A token template governs how to mint tokens for the users of your game. To begin the process of creating a new token template, you need to do the following: 1. Click the FQCN (Fully Qualified Collection Name) of the newly created collection in the DEPLOYED COLLECTIONS list.

2. Once you're in the Deployed Collections section, click on CREATE TOKEN TEMPLATE.

Create Token Template Screen

Here's a breakdown of the required information on the Create Token Template form:

Name	Description
Token ID	Enter a qualified token name. This name must uniquely identify the token variety in the collection. Vessel uses this name to instruct the Game API to mint new tokens for your users.
Display Name	Enter a user-friendly name for the token, to be displayed on the marketplace
Description	Enter a short, user-friendly description of the game to be displayed on the marketplace
Image	Upload a 500x500 pixel icon representing this type of token, to be displayed on the marketplace.
Permanent properties	Fill in the fields here to describe any non-mutable token properties. Click × to remove a property entirely, or ADD PROPERTY to add additional property.
Mutable properties	Fill in the fields here to describe any mutable token properties. Click × to remove a property entirely, or ADD PROPERTY to add additional property.

7. Deploy Your Token Template

To deploy your newly created token template to the blockchain, first click DEPLOY under Actions. Then, in the Deploy tokens pop-up that appears, enter an amount, and then finalize your amount by clicking DEPLOY.

Deploy Token Screen

You can see your deployed token template in the DEPLOYED TOKENS tab. It may take a few seconds after you click DEPLOY before your template appears in this tab.

Deployed Token

You can also create and deploy a token template by making an API POST request:

Create new tokens

post

Header parameters

X-Auth-KeystringOptionalDefault: ""Example: abcdef0123456789ABCDEF

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, 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
Content-Type: application/json
Accept: */*
Content-Length: 412

{
  "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
    }
  },
  "amount": 1,
  "to": "0xcafe000102030405060708090a0b0c0d0e0fbeef",
  "displayInDiscovery": true,
  "imageUrl": "jpg, png"
}

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

8. Mint a Token for a User

Make a POST request to the Mint API to mint a new token into any wallet on the Vessel blockchain:

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-KeystringOptionalDefault: ""Example: abcdef0123456789ABCDEF

Body

tostringRequired

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
Content-Type: application/json
Accept: */*
Content-Length: 62

{
  "to": "0xcafe000102030405060708090a0b0c0d0e0fbeef",
  "amount": 1
}

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

Here’s a sample request:

curl -X "POST" "https://game-api.openvessel.io/tokens/manage/com.teststudio.gamename.ratefinds.raresword/mint" \
     -H 'Content-Type: application/json' \
     -H 'X-Auth-Key: <YOUR WALLET PRIVATE KEY>' \
     -d $'{
  "to": "<TARGET USER WALLET ADDRESS>",
  "amount": 1
}'

You can also clone a token (create a new token based on an existing one) by making a POST request to the Clone API:

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-KeystringOptionalDefault: ""Example: abcdef0123456789ABCDEF

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
Content-Type: application/json
Accept: */*
Content-Length: 211

{
  "to": "0xcafe000102030405060708090a0b0c0d0e0fbeef",
  "mutableProperties": {
    "ANY_ADDITIONAL_PROPERTY": {
      "displayName": "text",
      "value": "text",
      "propertyOrder": 1
    }
  },
  "cloneMutableProperties": true,
  "displayInDiscovery": true
}

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

9. Query a User’s Tokens

Make a GET request to the User Token List API to query all tokens that belong to a user:

List of all tokens for selected user

get

Path parameters

addressstringRequired

Filter by blockchain address of the given user

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

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 /user/{address}/tokens/{fqGn}/ HTTP/1.1
Host: game-api.openvessel.io
Accept: */*

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

List of all tokens for selected user

get

Path parameters

addressstringRequired

Filter by blockchain address of the given user

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

fqGnstringRequired

Fully Qualified Game Name

Example: com.studio.game

qCnstringRequired

Qualified Collection 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 /user/{address}/tokens/{fqGn}/{qCn}/ HTTP/1.1
Host: game-api.openvessel.io
Accept: */*

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

Here’s a sample request:

curl "https://game-api.openvessel.io/user/<TARGET USER WALLET ADDRESS>/tokens/com.teststudio.gamename/" \
     -H 'Content-Type: application/json'

10. Integrate the SDK to Connect Your Game

Follow the SDK Integration guide to connect your game to your Vessel Wallet and to retrieve wallet addresses for your users:

Standard

Vessel also has a demo Unity project which you can check out.