Web3GameAPI

By Jacob MacMillan Software

Development Endpoint: https://api.web3gameapi.dev/development
Production Endpoint: https://api.web3gameapi.dev/production

The development endpoint uses test data and is not suitable for anything other than internal testing of products, and the API itself. Beta uses production data and has been tested, but may still contain minor bugs. Production is suitable for fully released products and should be relatively free of bugs.

This is an API to interact with all smart contracts monitored by thi system, on every supported blockchain, and also to interact with the database and login system, to retrieve/set/give things like items, and user metadata.

Overview

Note that for all endpoints that interact with blockchains, the operation must be supported by the smart contracts in order to succeed.

For all endpoints that require signing a message, the message to sign is returned by making a GET request to the endpoint /getSigningMessage. It will contain up to two instances of %s. The first instance must be replaced by either the user’s EVM-compatible wallet address (forced to all lower case) or the user’s userId (depending on endpoint). The second %s must be replcaed by the user’s current nonce (returned by /getNonce). Note that calling any endpoint that uses the user’s nonce will also invalidate the user’s last nonce, so a new nonce must be generated for every call to an endpoint that requires it.

(Internal: Keep table sorted alphabetically by endpoint)

Add Database Item

Add a new item to the database. This is item will only be usable as a database item.

Must include your JWT in the authorization header to add items to a project you own.

Request Body:

{
  "projectId": <projectId>,
  "itemId": <new itemId>,
  "mintable": <boolean (optional - default: false)>
}

You may select any itemId you wish, so long as it is not already in use by your project. DO NOT select an itemId that is likely to be used by your on-chain items in the future, unless you set mintable to true.

Example success response:

{
  "internalId": 4
}

internalId is the ID assigned to your item by the database. This ID can be used instead of ${projectId}/${itemId} for most functions.

Add Item

Add an item that already exists on the blockchain to the database. This is only required if you did not use this API to create the item.

Request Body:

{
  "projectId": <projectId>,
  "itemId": <on-chain itemId>
}

Example success response:

{
  "internalId": 4
}

internalId is the ID assigned to your item by the database. This ID can be used instead of ${projectId}/${itemId} for most functions.

Analytics

Get your user’s analytics. This includes what endpoints are called by your users, and when.

The response will be in the form a CSV table by default, but json, xml, and html are also supported.

Note that you can also view analytics through this webpage.

Pages

The default, and maximum, amount of entries returned is 500. If you would like less, set the query paramter limit to your desired amount of results. To chose which page of results you get, simple set the query paramter page.

Filters

You can filter results to get more control over the response. You may filter from any column by adding the query parameter <column> with the value of your condition. For example, to get only successful requests, you could add responseStatusCode=200. You may use conditions other than = by simply prepending it to the value. For example, to get all errors: responseStatusCode=!=200. Note that the first = is still required. All comparison operator supported by SQL are supported: <, >, <=, >=, and !=.

You may also wrap the value in LIKE() to recieve partial matches as well. For example, if you are looking for every leaderboard request, you could use the filter path=LIKE(leaderboard). If you want to filter to everything that doesn’t match a value, use !LIKE() instead.

Response type

To set the response type, simply set the query paramter response to the desired type. Supported types are json, xml, html, and csv, which is the default. For CSV and HTML only, if you want labels at the top of the spreadsheet/table, you can include the query parameter headers.

Assign Role

Assign a role to a given user

Request Body:

{
  "role": <name of role to assign>,
  "userToken": <jwt of user to assign role to>
}

Note that the role name will always be prepended by ${game}: to make sure that each role name is unique per game.

If the role doesn’t exist, it will be created.

If you would like to remove the role from the user, simply use a DELETE request to this endpoint.

Example success response:

{
}

Assign Role By Email

Assign a role to a given user

Game developers may request that a user join a given role without having a valid JWT for the user, by issuing a POST request to this endpoint instead and specifying the user’s email. The user must then accept the request by making a PATCH request to the same endpoint. Both calls must be authenticated by providing a JWT in the header. For the POST the game owner’s JWT must be use, and for the PATCH the JWT of the user who is joining the role must be used.

POST Request Body:

{
  "role": <name of role to assign>,
  "userEmail": <email of user>
  <xor>
  "userEmails": [<array containing multiple user emails>]
}

PATCH Request Body:

{
  "role": <name of role to assign>,
}

Note that the role name will always be prepended by ${game}: to make sure that each role name is unique per game.

If the role doesn’t exist, it will be created.

Example success response:

{
}

Authorization

Authenticate

DEPRECATED: Use /login instead

Verifies that the signature and nonce generates the user’s public address. If successful, a JWT is created and sent back to the client side.

Authenticate Request Body:

{
   "publicAddress":<User's Metamask wallet address>
   "signature":<Signature provided by web3.eth.sign>
}

Returns JWT

Get Nonce

Creates a random cryptographic string which is added to the user’s metadata and is used in the Metamask message signature. Note: if the user is not registered, an error is sent for the user to register.

getNonce Request Body:

{
  "publicAddress":<User's Metamask wallet address>
}

Alternativley, if an address is not linked or not known you can use the user’s userId instead of publicAddress:

{
  "userId":<User's userId>
}

Returns nonce

Change Password

Change a user’s password.

Request Body:

{
  "password": <new password>,
}

User must provide a valid JWT in the Authoriztion header to verify they have authority to change the password.

Login

Login a user (generates a JWT to authenticate user).

You may use either username/email and password to login, or login using a signed message (wallet login/metamask login/etc.). The appropriate method will be automatically chosen based on the provided request body.

Request Body for username/email and password login:

{
  "username": <username or email>,
  "password": <password>
}

Request body for EVM Wallet login:

{
   "publicAddress":<User's Metamask wallet address>
   "signature":<Signature provided by web3.eth.sign>
}

Example response body:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InBtR05td3RJTkRKb3F2TmUxalZOViJ9.eyJodHRwczovL3hlbnVtLmlvL3VzZXJfYXV0aG9yaXphdGlvbiI6eyJncm91cHMiOltdLCJyb2xlcyI6W119LCJpc3MiOiJodHRwczovL3hlbnVtLmV1LmF1dGgwLmNvbS8iLCJzdWIiOiJhdXRoMHw2MWRmNTllNzgwMDZlYTAwNmEwOGU4YTEiLCJhdWQiOiJodHRwczovL3hlbnVtLmV1LmF1dGgwLmNvbS9hcGkvdjIvIiwiaWF0IjoxNjQyMjA1MzA2LCJleHAiOjE2NDIyOTE3MDYsImF6cCI6ImVWZTR5NVVHSHRoSlA0YUVEdTVJdjdiaTdUNEt4azFlIiwic2NvcGUiOiJyZWFkOmN1cnJlbnRfdXNlciB1cGRhdGU6Y3VycmVudF91c2VyX21ldGFkYXRhIGRlbGV0ZTpjdXJyZW50X3VzZXJfbWV0YWRhdGEgY3JlYXRlOmN1cnJlbnRfdXNlcl9tZXRhZGF0YSBjcmVhdGU6Y3VycmVudF91c2VyX2RldmljZV9jcmVkZW50aWFscyBkZWxldGU6Y3VycmVudF91c2VyX2RldmljZV9jcmVkZW50aWFscyB1cGRhdGU6Y3VycmVudF91c2VyX2lkZW50aXRpZXMiLCJndHkiOiJwYXNzd29yZCJ9.gXS7hHJKxlIhp1qIxCnvzVVZxgzuUg9Vx1CBSNp8IV0_lt3pEmgcOj4L8e3yTXqDIwVYxgYYfop9E1iSufQgchVnBp-3-clRtqIZ5xPcOHi24l_1y8ZuMhp-A2RfCeixJUZvdmjIStrI-vuGDR0vVeeG_NT0qs-qZPK0CWGWKP_Dz9ArjyP7-qH3z0vrj0DtUkNwYYGtA6nh475ejIJau17tJHipLAyGA3vUO99V7gia3nswPETH1C9u_WXa7kyqDF26FkJ6eP0YrF_ecFedsITIKe-ZBHUaN016NCEjWs32dOwHfMGdqsaObnHerN0RFU-vK08kkLkBFCqVmFEVZQ",
  "scope": "read:current_user update:current_user_metadata delete:current_user_metadata create:current_user_metadata create:current_user_device_credentials delete:current_user_device_credentials update:current_user_identities",
  "expires_in": 86400,
  "token_type": "Bearer",
  "userId":"auth0|61df59e78006ea006a08e8a1"
  "username": "testuser",
  "roles": [
    "admin"
  ]
}

That particular JWT decodes to the following:

{
  "https://xenum.io/user_authorization": {
    "groups": [],
    "roles": []
  },
  "iss": "https://xenum.eu.auth0.com/",
  "sub": "auth0|61df59e78006ea006a08e8a1",
  "aud": "https://xenum.eu.auth0.com/api/v2/",
  "iat": 1642205306,
  "exp": 1642291706,
  "azp": "eVe4y5UGHthJP4aEDu5Iv7bi7T4Kxk1e",
  "scope": "read:current_user update:current_user_metadata delete:current_user_metadata create:current_user_metadata create:current_user_device_credentials delete:current_user_device_credentials update:current_user_identities",
  "gty": "password"
}

More information will be included in JWTs in the future (such as arbitrary metadata that game developers can add).

Register

Create a new user account.

Request Body:

{
  "email": <email address>,
  "username": <username>,
  "password": <password>
}

Example response body:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InBtR05td3RJTkRKb3F2TmUxalZOViJ9.eyJodHRwczovL3hlbnVtLmlvL3VzZXJfYXV0aG9yaXphdGlvbiI6eyJncm91cHMiOltdLCJyb2xlcyI6W119LCJpc3MiOiJodHRwczovL3hlbnVtLmV1LmF1dGgwLmNvbS8iLCJzdWIiOiJhdXRoMHw2MWRmNTllNzgwMDZlYTAwNmEwOGU4YTEiLCJhdWQiOiJodHRwczovL3hlbnVtLmV1LmF1dGgwLmNvbS9hcGkvdjIvIiwiaWF0IjoxNjQyMjA1MzA2LCJleHAiOjE2NDIyOTE3MDYsImF6cCI6ImVWZTR5NVVHSHRoSlA0YUVEdTVJdjdiaTdUNEt4azFlIiwic2NvcGUiOiJyZWFkOmN1cnJlbnRfdXNlciB1cGRhdGU6Y3VycmVudF91c2VyX21ldGFkYXRhIGRlbGV0ZTpjdXJyZW50X3VzZXJfbWV0YWRhdGEgY3JlYXRlOmN1cnJlbnRfdXNlcl9tZXRhZGF0YSBjcmVhdGU6Y3VycmVudF91c2VyX2RldmljZV9jcmVkZW50aWFscyBkZWxldGU6Y3VycmVudF91c2VyX2RldmljZV9jcmVkZW50aWFscyB1cGRhdGU6Y3VycmVudF91c2VyX2lkZW50aXRpZXMiLCJndHkiOiJwYXNzd29yZCJ9.gXS7hHJKxlIhp1qIxCnvzVVZxgzuUg9Vx1CBSNp8IV0_lt3pEmgcOj4L8e3yTXqDIwVYxgYYfop9E1iSufQgchVnBp-3-clRtqIZ5xPcOHi24l_1y8ZuMhp-A2RfCeixJUZvdmjIStrI-vuGDR0vVeeG_NT0qs-qZPK0CWGWKP_Dz9ArjyP7-qH3z0vrj0DtUkNwYYGtA6nh475ejIJau17tJHipLAyGA3vUO99V7gia3nswPETH1C9u_WXa7kyqDF26FkJ6eP0YrF_ecFedsITIKe-ZBHUaN016NCEjWs32dOwHfMGdqsaObnHerN0RFU-vK08kkLkBFCqVmFEVZQ",
  "scope": "read:current_user update:current_user_metadata delete:current_user_metadata create:current_user_metadata create:current_user_device_credentials delete:current_user_device_credentials update:current_user_identities",
  "expires_in": 86400,
  "token_type": "Bearer",
  "userId":"auth0|61df59e78006ea006a08e8a1"
  "username": "testuser",
  "roles": []
}

Reset Password

Send a password reset link to a given email address, provided they already have an account.

Request Body:

{
  "email": <email address>,
}

DB Market Functions

DB Currency Payments

Called by a user to pay for a game item with an in-game currency.

Must include your JWT in the authorization header to add items to a project you own.

Request Body:

{
  "saleId": <saleId>,
  "currency": <Internal item ID for currency the user wishes to use>,
	"quantity": <number>,
}

The user will buy saleId using currency. The user must have a sufficient amount of currency, and the sale must support the chosen currency. In the event either one of these is not true, a 400 error is returned with an explination of what the problem is.

Returns an empty body on success.

Get DB Sales

Get all currently available DB sales.

This function requires no input, and returns an array of all available sales, or an empty array if there are no current sales.

Example Response (no sales):

{
  "sales": []
}

Example Response (one sale):

{
  "sales": [
    {
      "saleId": 1,
      "itemId": 420,
      "itemAmount": 1,
      "currency": {
        "69": 200
      },
			"availableAmount": -1
    }
  ]
}

Inventory

Gets all the items owned by ${wallet} that are managed by one of ${projectId}’s contracts.

userId is obtained when the user logs in to their account. Using either of userId or wallet will attempt to get both the user’s database and blockchain inventories. Note that in order to get a blockchain inventory from a userId, the user must have a wallet linked to their account, and the same is true when getting the user’s database inventory with a wallet. In most cases, it is recomended to use userId over wallet in order to avoid forcing users to have a blockchain wallet.

Note that you must only include the part of userId following the final |. Although it should technically work, the function will not be called correctly if a | is included in the URI.

This function does not require any additional data, however you may pass optional query string, as outlined in the below table:

Example response body assuming the following:

• ${projectId} is an ERC-1155 contract
• ${wallet} owns 4 items with item ID of 1
• There exists items on ${projectId} with the following IDs: 1, 2, 3, 4

{
  "1": 4,
  "2": 0,
  "3": 0,
  "4": 0
}

This would be the same if the ${projectId} is an ERC-721 contract, but ${wallet} will not be able to own more than one of each item.

Example response body assuming the following:

• ${projectId} is an ERC-20 contract
• ${wallet} owns 400 ${projectId} tokens

{
  "1": 400
}

This endpoint will only returned the most recent cached data. To update the cache, simply make a PATCH request instead of GET.

Get Items

Returns all items in database. You also have the ability to get items based on the projectId.

Example Response Body:

{
  "items": [
    {
      "internalId": 1,
      "projectId": 1,
      "itemId": "1",
    },
    {
      "internalId": 2,
      "projectId": 1,
      "itemId": "2",
    },
    {
      "internalId": 3,
      "projectId": 1,
      "itemId": "3",
    },
     {
      "internalId": 4,
      "projectId": 2,
      "itemId": "4",
    },
  ]
}

Get Metadata

Return a user’s metadata

This functions require’s authentication using the user’s JWT. This is the user whose metadata will be returned.

Authentication:
Pass the header Authorization, with a value of Bearer followed by your JWT.

Get Projects

Returns all projects.

Example Response Body:

{
  "projects": [
    {
      "name": "Xenum Test",
      "projectId": 1,
      "internalId": 1,
      "currencies": {
        "*": [
          "0x0000000000000000000000000000000000000000"
        ]
      },
      "standard": "erc-721",
      "contracts": {
        "3": "0x48f2286703D112FEbA57eF2598C06cC09e394E14",
        "4": "0x48f2286703D112FEbA57eF2598C06cC09e394E14",
        "rinkeby": "0x48f2286703D112FEbA57eF2598C06cC09e394E14",
        "ropsten": "0x48f2286703D112FEbA57eF2598C06cC09e394E14"
      },
      "testnet": 1
    },
    {
      "name": "The Fabled (Mint Pass)",
      "projectId": 2,
      "internalId": 2,
      "currencies": {
        "*": [
          "0x0000000000000000000000000000000000000000"
        ]
      },
      "standard": "erc-1155",
      "contracts": {
        "1": "0xFf1546d3D5Cc63410A36C183260AF7Cd3B93cA7b",
        "ethereum": "0xFf1546d3D5Cc63410A36C183260AF7Cd3B93cA7b"
      },
      "testnet": 0
    },
   {
      "name": "Test ERC-20",
      "projectId": 3,
      "internalId": 3,
      "currencies": {
        "*": [
          "0x0000000000000000000000000000000000000000"
        ]
      },
      "standard": "erc-20",
      "contracts": {
        "3": "0x0009348015062f9292a53a3b6e3e3ba48e2093f3",
        "4": "0x01be23585060835e02b77ef475b0cc51aa1e0709",
        "rinkeby": "0x01be23585060835e02b77ef475b0cc51aa1e0709",
        "ropsten": "0x0009348015062f9292a53a3b6e3e3ba48e2093f3"
      },
      "testnet": 1
    },
    {
      "name": "Mock ERC-20",
      "projectId": 4,
      "internalId": 11,
      "currencies": {
        "*": [
          "0x0000000000000000000000000000000000000000"
        ]
      },
      "standard": "erc-20",
      "contracts": {
        "4": "0xA19DC9F3296bf8A21d18185007FbF67fE2bA6879",
        "rinkeby": "0xA19DC9F3296bf8A21d18185007FbF67fE2bA6879"
      },
      "testnet": 1
    },
    {
      "name": "Mock ERC-721",
      "projectId": 4,
      "internalId": 12,
      "currencies": {
        "*": [
          "0x0000000000000000000000000000000000000000"
        ]
      },
      "standard": "erc-721",
      "contracts": {
        "4": "0x7E71e4372287934b1BA6cEF7318FC3823Dd3F379",
        "rinkeby": "0x7E71e4372287934b1BA6cEF7318FC3823Dd3F379"
      },
      "testnet": 1
    },
    {
      "name": "Mock ERC-1155",
      "projectId": 4,
      "internalId": 13,
      "currencies": {
        "*": [
          "0x0000000000000000000000000000000000000000"
        ]
      },
      "standard": "erc-1155",
      "contracts": {
        "4": "0xF0FC47C0C8c2DD2CF106D97c0E8Dd6B375c5Aa82",
        "rinkeby": "0xF0FC47C0C8c2DD2CF106D97c0E8Dd6B375c5Aa82"
      },
      "testnet": 1
    }
  ]
}

Item Info

Gets metadata of the given item.

Item IDs and project ID pairs are passed by query string. Project IDs can be omited. In that case they must be omited for every item, and it will be assumed that the item IDs are internal item IDs (the itemIds assigned by the database).

Example query:

/item?id=9792&id=4128&project=20&project=20

Note that you can order the item and project IDs however you want, as long as the first itemId matches the first projectId, etc.

You may also add the optional boolean parameter forceNew to indicate if you would like to forefully update the cached metadata for each queried item. Default value is false, in which case cached metadata is used if available, otherwise the metadata is fetched and cached.

Leaderboard

Allows the ability to add and fetch leaderboard data for events.

Get

Example response body:

{
    "leaderboard": [{
        "username": "testuser",
        "value": 123,
        "time": "2023-08-07T22:17:36.000Z",
        "extraData": "123"
    }]
}

Post

Authentication: Pass the header Authorization, with a value of Bearer followed by your JWT

Request body format:

{
  "userToken":<Optional. The player's JWT that will mark the leaderboard entry as 'trusted' if authorized>,
  "extraData":<Optional. Any extra information to be added to the leaderboard entry>,
  "score":<Score for leaderboard order>
}

Link Wallet EVM

Link an EVM compatable wallet to the user’s account

Request Body:

{
  "signature": <signature of message>
}

Mint Permit

Various functions for interacting with mint permits.

GET - Gets all pending mint permits, their current status and whether it’s available to be used. Excludes mint permits that have already been used on the blockchain. Authentication:
Pass the header Authorization, with a value of Bearer followed by your JWT.

POST - A user requests for a mint permit top be created and signed by the developer. Authenticate Request Body:

{
   "itemId":<Item ID>,
   "recipient":<Public address of user receiving the mint permit>,
   "networkId":<Network ID>,
   "amount":<Amount of items that need to be minted>
}

PATCH - Sends hash and signature for mint permits signed by the developer (Made with wallet daemon) Authenticate Request Body:

{
  "signature":<Mint permit verification signature>,
  "mintPermitId":<Mint Permit ID>,
  "userId":<User ID of mint request>,
  "itemId":<Item ID>,
  "amount":<Amount of items that need to be minted>,
  "key": <HMAC key generated by the wallet daemon>
}

Mint Mint Permit

Updates the mint permit status and send the signature and mint permit data to the user.

Authenticate Request Body:

{
  "mintPermitId":<Mint Permit ID>,
}

Get Pending Mint Permit

Gets the information for requested mint permits that need to be signed by the developer. (Made with wallet daemon)

Authentication:
Pass the header Authorization, with a value of Bearer followed by your JWT

Pending Transactions

Returns an array of pending transactions that need to be signed before sending

Request Body:

{
  "address": <public wallet address>,
}

Revoke Access

Revokes a login session so a JWT can no longer be used

No requset body is required, and any provided body will be ignored.

Update Inventory

Updates the quantity of an item for a user in the database.

Request Body:

{
  "userId": <userId>,
  "itemId": <Item ID>,
  "quantity": <quantity>
}

Returns the user ID and update quantity count for the item.

Update Item Level

Update the level of a given item. Currently this will only effect the metadata generated by the metadata generator.

Must include your JWT in the authorization header to modify items belongining a project you own.

Request Body:

{
  "projectId": <projectId>,
  "itemId": <itemId>,
  "level": <new level>
}

You may also opt to not include a projectId and instead use the item’s internalId as itemId

Example success response:

{
}

Update Metadata

Update a particular user’s app_metadata for the given ${game}, or update the user_metadata of the user whose token was passed in the header.

Authentication:
Pass the header Authorization, with a value of Bearer followed by your JWT.

Request Body for updating app_metadata:

{
  "userToken": <user's JWT>,
  "metadataDiff": <metadata changes>
}

Request Body for updating user_metadata:

{
  "metadataDiff": <metadata changes>
}

Note that when updating user_metadata the ${game} parameter is still used. If you would like to update the top level object of user_metadata, simply set ${game} to self. Also note that versions TestRelease59 and lower will NOT merge metadatDiff recursively. If an object is included in metadataDiff it will overwrite any object of the same name that already existed.

Returns user’s updated metadata on success.

metadataDiff

metadataDiff is simply a JSON object containing the changes you wish to make to the user’s game metadata. This object is merged into the previous metadata.

metadataDiff also supports adding and subtracting from numbers by using +<number> and -<number>. With the exception of the adding/subtracting syntax, the type of a given token in metadataDiff must match the type of the same token in the user’s current metadata. If the token does not exist in the current metadata, the token will be created and have the type of the first assigned value.

For example, if the user’s metadata is currently:

{
  "kills": 100,
  "assists": 0
}

and you want to add 1 death, add one assist, and change kills to 104, you can use the following metadataDiff:

{
  "kills": 104,
  "deaths": 1,
  "assists": "+1"
}

Because deaths does not already exist, using "+1" instead of 1 would set deaths to the literal "+1".

User Managment

User Block

Block or unblock any user account from logging in.

To use this endpoint, you must be a verified project owner (ie. have a developer account).

This endpoint is used to block a malicious user account, or unblock a user that has been blocked mistakenly.

Example body:

  "userId": <userId>
  "block": <bool (default: true)>

To unblock a user, simply set block to false

User Search

Search for any user account.

To use this endpoint, you must be a verified project owner (ie. have a developer account).

This endpoint takes a single query parameter: search. This is used to specify the search terms. To search for a user with a given email address or username, simply use search=<username/email>. For more advanced queries, like searching for every user who’s account has been blocked, you can use search=blocked:true.

Verify Email

Send the logged in user a email verification link via email.

Authentication:
Pass the header Authorization, with a value of Bearer followed by your JWT.

Request Body:

{
}

Errors

All API errors will return an appropriate error code, and error message. The format of the error body will always be the following:

{
  "failure": true,
  "msg": "error message here"
}