> For the complete documentation index, see [llms.txt](https://docs.openvessel.io/integration/EZzgG67O9oXGl9CReheF/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openvessel.io/integration/EZzgG67O9oXGl9CReheF/game-api/tokens.md).

# Tokens

{% hint style="info" %} <mark style="color:red;">\*</mark> is a required field
{% endhint %}

{% hint style="warning" %}
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.
{% endhint %}

{% hint style="warning" %}
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.
{% endhint %}

## Create Tokens

### Create new tokens

{% openapi src="/files/HajKA5xZvO5SYYbfx35H" path="/tokens/manage/create" method="post" %}
[1009\_Vessel\_prod.json](https://1785276440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlS5g6RKJvRGb_KKP5m%2Fuploads%2FtIKhwzoW0fObLFwqU4WK%2F1009_Vessel_prod.json?alt=media\&token=a1353f5d-201e-4e43-8448-2468aa861158)
{% endopenapi %}

### Create new tokens multipart

{% openapi src="/files/HajKA5xZvO5SYYbfx35H" path="/tokens/manage/create-multipart" method="post" %}
[1009\_Vessel\_prod.json](https://1785276440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlS5g6RKJvRGb_KKP5m%2Fuploads%2FtIKhwzoW0fObLFwqU4WK%2F1009_Vessel_prod.json?alt=media\&token=a1353f5d-201e-4e43-8448-2468aa861158)
{% endopenapi %}

### 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.

{% openapi src="/files/HajKA5xZvO5SYYbfx35H" path="/tokens/manage/{fqTn}/mint" method="post" %}
[1009\_Vessel\_prod.json](https://1785276440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlS5g6RKJvRGb_KKP5m%2Fuploads%2FtIKhwzoW0fObLFwqU4WK%2F1009_Vessel_prod.json?alt=media\&token=a1353f5d-201e-4e43-8448-2468aa861158)
{% endopenapi %}

### 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.

{% openapi src="/files/HajKA5xZvO5SYYbfx35H" path="/tokens/manage/{fqTn}/clone" method="post" %}
[1009\_Vessel\_prod.json](https://1785276440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlS5g6RKJvRGb_KKP5m%2Fuploads%2FtIKhwzoW0fObLFwqU4WK%2F1009_Vessel_prod.json?alt=media\&token=a1353f5d-201e-4e43-8448-2468aa861158)
{% endopenapi %}

### Burn tokens

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

{% openapi src="/files/HajKA5xZvO5SYYbfx35H" path="/tokens/manage/burn" method="post" %}
[1009\_Vessel\_prod.json](https://1785276440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlS5g6RKJvRGb_KKP5m%2Fuploads%2FtIKhwzoW0fObLFwqU4WK%2F1009_Vessel_prod.json?alt=media\&token=a1353f5d-201e-4e43-8448-2468aa861158)
{% endopenapi %}

### Burn to Mint tokens

You can consume tokens and create new tokens.

{% openapi src="/files/HajKA5xZvO5SYYbfx35H" path="/tokens/manage/burn-to-mint" method="post" %}
[1009\_Vessel\_prod.json](https://1785276440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlS5g6RKJvRGb_KKP5m%2Fuploads%2FtIKhwzoW0fObLFwqU4WK%2F1009_Vessel_prod.json?alt=media\&token=a1353f5d-201e-4e43-8448-2468aa861158)
{% endopenapi %}

### Mint vs Clone

There are two APIs for creating and giving a new token to a user, [Mint](#tokens-manage-fqtn-mint) and [Clone](#tokens-manage-fqtn-clone).&#x20;

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

{% openapi src="/files/HajKA5xZvO5SYYbfx35H" path="/tokens/{fqGn}/" method="get" %}
[1009\_Vessel\_prod.json](https://1785276440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlS5g6RKJvRGb_KKP5m%2Fuploads%2FtIKhwzoW0fObLFwqU4WK%2F1009_Vessel_prod.json?alt=media\&token=a1353f5d-201e-4e43-8448-2468aa861158)
{% endopenapi %}

### List collection tokens

{% openapi src="/files/HajKA5xZvO5SYYbfx35H" path="/tokens/{fqGn}/{qcn}/" method="get" %}
[1009\_Vessel\_prod.json](https://1785276440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlS5g6RKJvRGb_KKP5m%2Fuploads%2FtIKhwzoW0fObLFwqU4WK%2F1009_Vessel_prod.json?alt=media\&token=a1353f5d-201e-4e43-8448-2468aa861158)
{% endopenapi %}

### Token Object

<table><thead><tr><th width="169">Name</th><th width="117">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>displayName</code></td><td><code>string</code></td><td>Display name of the token</td></tr><tr><td><code>fqTn</code></td><td><code>string</code></td><td><a href="/pages/14mcBCWRrAg06tiT6561#qualified-names">Fully qualified</a> token name</td></tr><tr><td><code>totalSupply</code></td><td><code>number</code></td><td>Total number of minted tokens</td></tr></tbody></table>

{% openapi src="/files/HajKA5xZvO5SYYbfx35H" path="/tokens/{fqGn}/{qcn}/{qtn}" method="get" %}
[1009\_Vessel\_prod.json](https://1785276440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlS5g6RKJvRGb_KKP5m%2Fuploads%2FtIKhwzoW0fObLFwqU4WK%2F1009_Vessel_prod.json?alt=media\&token=a1353f5d-201e-4e43-8448-2468aa861158)
{% endopenapi %}

### Token Details Object

<table><thead><tr><th width="224">Name</th><th width="106">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>displayName</code></td><td><code>string</code></td><td>Display name of the token</td></tr><tr><td><code>description</code></td><td><code>string</code></td><td>Token description</td></tr><tr><td><code>imageUrl</code></td><td><code>string</code></td><td>URL that points to the token image</td></tr><tr><td><code>fqTn</code></td><td><code>string</code></td><td><a href="/pages/14mcBCWRrAg06tiT6561#qualified-names">Fully qualified</a> token name</td></tr><tr><td><code>collectionAddress</code></td><td><code>string</code></td><td>Blockchain address of the collection this token belongs to</td></tr><tr><td><code>totalSupply</code></td><td><code>number</code></td><td>Total number of minted tokens</td></tr><tr><td><code>properties</code></td><td><code>object</code></td><td>An object that contains the token’s immutable properties</td></tr><tr><td><code>mutableProperties</code></td><td><code>object</code></td><td>An object that contains the token’s mutable properties</td></tr><tr><td><code>createdAt</code></td><td><code>number</code></td><td>Unix timestamp of the token’s creation time</td></tr></tbody></table>

## Token Metadata

### Update metadata

{% openapi src="/files/HajKA5xZvO5SYYbfx35H" path="/tokens/manage/{fqTn}/update-metadata" method="post" %}
[1009\_Vessel\_prod.json](https://1785276440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlS5g6RKJvRGb_KKP5m%2Fuploads%2FtIKhwzoW0fObLFwqU4WK%2F1009_Vessel_prod.json?alt=media\&token=a1353f5d-201e-4e43-8448-2468aa861158)
{% endopenapi %}

### Update metadata multipart

{% openapi src="/files/HajKA5xZvO5SYYbfx35H" path="/tokens/manage/{fqTn}/update-metadata-multipart" method="post" %}
[1009\_Vessel\_prod.json](https://1785276440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlS5g6RKJvRGb_KKP5m%2Fuploads%2FtIKhwzoW0fObLFwqU4WK%2F1009_Vessel_prod.json?alt=media\&token=a1353f5d-201e-4e43-8448-2468aa861158)
{% endopenapi %}

### Update a single mutable property

{% openapi src="/files/HajKA5xZvO5SYYbfx35H" path="/tokens/manage/{fqTn}/update-mutable-property" method="post" %}
[1009\_Vessel\_prod.json](https://1785276440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlS5g6RKJvRGb_KKP5m%2Fuploads%2FtIKhwzoW0fObLFwqU4WK%2F1009_Vessel_prod.json?alt=media\&token=a1353f5d-201e-4e43-8448-2468aa861158)
{% endopenapi %}

### Update multiple mutable properties

{% openapi src="/files/HajKA5xZvO5SYYbfx35H" path="/tokens/manage/{fqTn}/update-mutable-properties" method="post" %}
[1009\_Vessel\_prod.json](https://1785276440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlS5g6RKJvRGb_KKP5m%2Fuploads%2FtIKhwzoW0fObLFwqU4WK%2F1009_Vessel_prod.json?alt=media\&token=a1353f5d-201e-4e43-8448-2468aa861158)
{% endopenapi %}

### 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

{% openapi src="/files/HajKA5xZvO5SYYbfx35H" path="/tokens/manage/transfer" method="post" %}
[1009\_Vessel\_prod.json](https://1785276440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlS5g6RKJvRGb_KKP5m%2Fuploads%2FtIKhwzoW0fObLFwqU4WK%2F1009_Vessel_prod.json?alt=media\&token=a1353f5d-201e-4e43-8448-2468aa861158)
{% endopenapi %}

{% hint style="warning" %}
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.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.openvessel.io/integration/EZzgG67O9oXGl9CReheF/game-api/tokens.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.