XERIAL - API Documentation

Documentation

"Web3" is a term that refers to the third generation of the internet, which includes new technologies like blockchain. Although Xerial is a blockchain platform, it is not necessary to use this technology to take advantage of the marketplace. In this documentation, you will find web3 terminology that we recommend you become familiar with. However, we will explain these terms in the context of Xerial when they are used. Knowing concepts like "NFT" or "address" will make this documentation easier to read, but it is not a requirement

All communications between Xerial and integrations are done through HTTP POST (at least for now). Therefore, it's important that before integrating, you make sure that you can send HTTP requests from your client to our server and that your server is capable of receiving HTTP requests sent from our platform

Basic Terminology

In the following step-by-step guide, you will find the following web3 terms, each with a particular meaning within the platform's domain.

Project

We refer to clients of our platform as Projects. In order to integrate with Xerial, it's necessary to have a project, and all transactions within the platform are made from the project's point of view. All entities, connections, purchases, and sales within Xerial are internally related to a Project

NFTs

NFT stands for "non-fungible token" and in blockchain terminology is used to represent a unique entity that is independent of all other entities. In Xerial, an NFT is the base entity and represents anything collectible or acquirable in the marketplace. In the context of a project, an NFT can represent whatever the developer wants, for example:

1) An NFT can be an object that a game developer allows their players to buy. When players buy the object on Xerial, it's added to their inventory in the game.

2) An NFT can be a character that a player puts up for sale from within the game. When other players buy the character on Xerial, the game transfers the character between players.

3) An NFT can be a collectible achievement in the game. Players wouldn't be able to buy it from the marketplace, but rather the game would award it to them as a reward for a particular action, and players can show it on their Xerial profile.

Whenever a developer is creating entities within Xerial, both to sell and to give away for free to their users, they will do so through the API called "Create NFT."

Token

The term token, or "fungible token" in web3 terminology, is used to refer to any entity that is NOT unique but is of equal value and interchangeable with other entities in its category.

In Xerial, a project's token is the currency used to acquire NFTs in the marketplace. Each project can choose the name and logo of its token, and users can see a listing of all the available tokens in the marketplace. Users can also see a list of all the tokens they've acquired and their respective balances.

Token Wallet and Address

A wallet is what a user uses to identify themselves on web3 platforms. Just as traditional platforms identify their users with an email and password, web3 platforms use an address (or public key) and private key, respectively.

The process of creating or managing a wallet within Xerial is transparent to the user, thanks to the Web3Auth technology (https://web3auth.io/). It is not necessary to know what a wallet is or how to use it, but it should be noted that internally the platform uses addresses as the primary identifier for users, not emails or user IDs as in traditional platforms.

Update webhook URL

This URL is the one that Xerial's server will use to notify the project of user interactions with their NFTs and tokens.

To enter the URL where you want to receive notifications, go to the configuration screen and use the form.

Creating NFTs

Can be done in two ways: through the dashboard (https://staging.developer.xerial.io/dashboard/items) and by using APIs.

To create an NFT through the dashboard, simply navigate to the NFT screen (labeled as "Items") and fill out the creation form.

Using the API is the most flexible way to create NFTs, as it allows for dynamic creation from within a game or when the user executes a particular action.

The NFT creation API is very simple and works as shown in this example (https://github.com/xerial-games/sample-game/blob/master/pages/api/sell_rogue.js).

Receive Notifications

The Xerial server sends out different notifications throughout the lifecycle of a user and an NFT.

To receive notifications, you first need to update the Webhook URL field in the configuration panel with the URL where the Xerial server should send the notifications.

The HTTP requests sent to the Webhook URL are always of the POST type.

The body of the HTTP request is in JSON format and has the following fields:

1) "eventName": A string that indicates the action being notified
2) "payload": A dynamic object that contains relevant information about the action

IMPORTANT: Verify HTTP requests

It is important to verify that the HTTP requests received by your server are sent by the Xerial server.

Xerial's HTTP requests contain a header with the key X-Xerial-API-Key and its value will be your API key. This way you can verify that it is actually the Xerial server that is sending you the HTTP requests.