Link Search Menu Expand Document

Development Endpoint: https://api.xenum.io/development
Beta Endpoint: https://api.xenum.io/beta
Production Endpoint: https://api.xenum.io/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 contracts accepted by the bridge network, on every supported blockchain.

This repository ONLY cointains user-callable API functions. The relay script/server is not included, for example, because it is not callable. It is located here.

Overview

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

(Internal: Keep table sorted alphabetically by endpoint)

Endpoint Folder Name Description Permissions
/addDatabaseItem add-database-item Add a new item to the Xenum database. This is item will only be usable as a database item. Project owner
/addItem add-item Add an item that already exists on the blockchain to the Xenum database. This is only required if you did not use this API to create the item. No restrictions
/assignRole/${game} assign-role Assign a role to a given player. Project owner only
/assignRole/byEmail/${game} assign-role-by-email Offer a user, specified by email address, a given role. Project owner only
/assignRole/byEmail/${game} assign-role-by-email Accept a role offer. User offered role only
/auth/authenticate authorization/authenticate 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. No restrictions
/auth/getNonce authorization/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. No Rrestrictions
/changePassword change-password Change the logged in user’s password User whose password to change
/circulatingByNetwork/${internalId} circ-by-network Get amount of tokens on each network No restrictions
/circulatingByNetwork/${projecId}/${itemId} circ-by-network Get amount of tokens on each network No restrictions
/createItem/${projectId} create-item Can create a new token type or mint items depending on the calldata being sent and the contract function being called. Project owner, approved users
/generateFee verify-fee Calculates and verifies fee data for use with the cross-chain bridge No restrictions
/getBridge/${networkId} get-bridge Returns the address of the bridge contract on the given network. No restrictions
/getItems get-items Returns all items held in the database No restrictions
/getMetadata get-metadata Return a user’s metadata User whose metadata it is
/getProjects get-projects Returns an array containing all projects and info about them No restrictions
/inventory/${userId}/${projectId} inventory Gets all the items owned by ${wallet} that are managed by one of ${projectId}’s contracts. No restrictions
/inventory/${wallet}/${projectId} inventory Gets all the items owned by ${wallet} that are managed by one of ${projectId}’s contracts. No restrictions
/item/${internalId} item-info Gets metadata of the given item. No restrictions
/item/${projectId}/${itemId} item-info Gets metadata of the given item. No restrictions
/linkWallet/evm link-eth-wallet Links a EVM compatible wallet to a user’s account User whose account to link address to
/login login Login a user (generates a JWT to authenticate user) No restrictions
/mintPermit mint-permit Various functions for getting pending mint permits, requesting developer signatures and updating mint permit signatures No restrictions
/mintPermit/mint get-mint-permit 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. No restrictions
/mintPermit/pending get-pending-mint-permit Gets the information for requested mint permits that need to be signed by the developer. No restrictions
/pendingTransactions pending-transactions Returns an array of pending transactions that need to be signed before sending No restrictions
/register register Create a new user account No restrictions
/resetPassword password-reset Sends the user a password reset email No restrictions
/revokeAccess revoke-access Revokes a login session so a JWT can no longer be used No restrictions
/updateInventory update-inventory Updates the quantity of an item for a user in the database Project owner, approved users
/updateItemLevel update-item-level Updates the level of a given item Project owner
/updateMetadata/${game} update-metadata Update a particular user’s app_metadata for the given ${game} Project owner
/verifyEmail email-verification Verify a user’s email address User whose email it is

Add Database Item

Stage Most recent update
Development TR50
Beta TR50
Production TR50

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

Endpoint Type Authentication Supported Contract Standards
/addDatabaseItem POST JWT ERC-1155, ERC-721

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:

{
  "xenumId": 4
}

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

Add Item

Stage Most recent update
Development TR50
Beta TR50
Production TR50

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

Endpoint Type Authentication Supported Contract Standards
/addItem POST None ERC-1155, ERC-721

Request Body:

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

Example success response:

{
  "xenumId": 4
}

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

Assign Role

Stage Most recent update
Development TR50
Beta TR49
Production TR49

Assign a role to a given user

Endpoint Type Authentication Supported Contract Standards
/assignRole/${game} POST JWT N/A
/assignRole/${game} DELETE JWT N/A

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

Stage Most recent update
Development TR53
Beta N/A
Production N/A

Assign a role to a given user

Endpoint Type Authentication Supported Contract Standards
/assignRole/byEmail/${game} POST JWT N/A
/assignRole/byEmail/${game} PATCH JWT N/A

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

Stage Most recent update
Development TR52
Beta 445812f
Production 445812f

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.

Endpoint Type Authentication Supported Contract Standards
/auth/authenticate POST None N/A

Authenticate Request Body:

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

Returns JWT

Get Nonce

Stage Most recent update
Development TR49
Beta TR49
Production TR49

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.

Endpoint Type Authentication Supported Contract Standards
/auth/getNonce POST None N/A

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

Stage Most recent update
Development TR49
Beta TR49
Production TR49

Change a user’s password.

Endpoint Type Authentication Supported Contract Standards
/changePassword PATCH JWT N/A

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

Stage Most recent update
Development TR49
Beta TR49
Production TR49

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

Endpoint Type Authentication Supported Contract Standards
/login POST None N/A

Request Body:

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

Stage Most recent update
Development TR49
Beta TR49
Production TR49

Create a new user account.

Endpoint Type Authentication Supported Contract Standards
/register POST None N/A

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

Stage Most recent update
Development TR54
Beta TR49
Production TR49

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

Endpoint Type Authentication Supported Contract Standards
/resetPassword POST None N/A

Request Body:

{
  "email": <email address>,
}

Circulating By Network

Stage Most recent update
Development TR49
Beta N/A
Production N/A

Get amount of tokens on each network.

Endpoint Type Authentication Support Contract Standards
/circulatingByNetwork/${internalId} GET None ERC-1155*, ERC-721, ERC-20
/circulatingByNetwork/${projecId}/${itemId} GET None ERC-1155*, ERC-721, ERC-20
* ERC-1155 contracts must implement circulatingSupply(uint256) to be supported. Support for ERC-1155 contracts that do not implement circulatingSupply(uint256) is planned.

Response body format:

{
  <networkId1>: <amount1>,
  <networkId2>: <amount2>,
  ...
}

Create Item

Stage Most recent update
Development TR49
Beta N/A
Production N/A

Can create a new token type or mint items depending on the calldata being sent and the contract function being called. This endpoint will take the calldata for the transaction. If the transaction is already signed, it will be published and any missing items will be added to the database through the transaction checker. If unsigned, the user will have to get the pending transaction and sign it before the item is added. The transaction must be compatible with the primary network of the project. Not supported for ERC-20 tokens.

Endpoint Type Authentication Supported Contract Standards
/createItem/${projectId} POST JWT ERC-1155, ERC-721

Request body format:

{
  "calldata":<Transaction calldata>,
  "chainId":<Network chain ID for project>
}

Inventory

Stage Most recent update
Development TR49
Beta TR49
Production TR49

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

Endpoint Type Authentication Supported Contract Standards
/inventory/${wallet}/${projectId} GET None ERC-1155, ERC-721, ERC-20
/inventory/${userId}/${projectId} GET None ERC-1155, ERC-721, ERC-20
/inventory/${userId}/${projectId} PATCH None ERC-1155, ERC-721, ERC-20

userId is obtained when the user logs in to their Xenum 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:

Query Data Type Description
ignoreDb bool Used to filter out off chain (database) items. (ie. only get items that are on chain)
networkId int Used to filter inventory by network ID. Use 0 to get only database items
onlyReal bool Do not include rented items, and items staked in a rental contract

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.

Generate Fee

Stage Most recent update
Development TR49
Beta N/A
Production N/A

Calculates and verifies fee data for use with the cross-chain bridge

Endpoint Type Authentication Supported Contract Standards
/generateFee POST None ERC-1155, ERC-721, ERC-20

Request body format:

{
  "sender": <public address of sender>,
  "tokenAddress": <address of token to send, or message recipient>,
  "tokenAmount": <amount of tokens to send>,
  "tokenId": <ID of token to send>
  "senderNetwork": <network user is sending from>,
  "destinationNetwork": <network to send data/token to>,
  "feeToken": <address of fee token (zero address for native token of sending network)>,
  "messageData": <bytes encoded data for message>,
  "requestReceipt": <true/false>,
  "estimateOnly": <true/false>
}

These are not all required for all operations. The below table outlines the required parameters for each possible bridge transfer. Any parameters that are not required MUST either be omitted entirely, or set to 0 (number) or false (bool).

Bridged Data Required Parameters
ERC-20 sender, tokenAddress, tokenAmount, senderNetwork, destinationNetwork, feeToken
ERC-1155 sender, tokenAddress, tokenAmount, tokenId, senderNetwork, destinationNetwork, feeToken
ERC-721 sender, tokenAddress, tokenId, senderNetwork, destinationNetwork, feeToken
Message sender, tokenAddress, senderNetwork, destinationNetwork, messageData, feeToken

For Message operations, tokenAddress is the recipient of the message. If you would like to request a receipt also set requestReceipt to true (or any non-false, non-null, non-zero value). The default is false.

To get the fee for a given operation without getting a signed fee verification, set estimateOnly to true (or any non-false, non-null, non-zero value).

Get Bridge

Stage Most recent update
Development TR50
Beta TR50
Production TR50

Returns the address of the bridge contract on the given network.

Endpoint Type Authentication Supported Contract Standards
/getBridge/${networkId} GET None N/A

Returns status code 400 if network does not have a bridge contract.

Get Items

Stage Most recent update
Development TR49
Beta TR49
Production TR49

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

Endpoint Type Authentication Supported Contract Standards
/getItems GET None ERC-1155, ERC-721, ERC-20
/getItems/${projectId} GET None ERC-1155, ERC-721, ERC-20

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

Stage Most recent update
Development TR49
Beta TR49
Production TR49

Return a user’s metadata

Endpoint Type Authentication Supported Contract Standards
/getMetadata GET JWT N/A

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

Stage Most recent update
Development TR49
Beta TR49
Production TR49

Returns all projects on Xenum

Endpoint Type Authentication Supported Contract Standards
/getProjects GET None N/A

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

Stage Most recent update
Development TR49
Beta TR49
Production TR49

Gets metadata of the given item.

Endpoint Type Authentication Supported Contract Standards
/item/${internalId} GET None ERC-1155, ERC-721
/item/${projectId}/${itemId} GET None ERC-1155, ERC-721

This function does not require any additional data.

Will simply return what the metadata of the item is set to on the blockchain.

internalId refers to the ID assigned to each item by Xenum. It is unique to each item.

Stage Most recent update
Development TR51
Beta TR49
Production TR49

Link an EVM compatable wallet to the user’s account

Endpoint Type Authentication Supported Contract Standards
/linkWallet/evm POST JWT N/A

Request Body:

{
  "signature": <signature of message>
}

Mint Permit

Stage Most recent update
Development TR49
Beta N/A
Production N/A
Endpoint Type Authentication Supported Contract Standards
/mintPermit GET JWT N/A
/mintPermit POST JWT N/A
/mintPermit PATCH JWT N/A

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 daemon wallet) 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>
}

Mint Mint Permit

Stage Most recent update
Development TR49
Beta N/A
Production N/A

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

Endpoint Type Authentication Supported Contract Standards
/mintPermit/mint POST JWT N/A

Authenticate Request Body:

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

Get Pending Mint Permit

Stage Most recent update
Development TR49
Beta N/A
Production N/A

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

Endpoint Type Authentication Supported Contract Standards
/mintPermit/pending GET JWT N/A

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

Pending Transactions

Stage Most recent update
Development TR49
Beta N/A
Production N/A

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

Endpoint Type Authentication Supported Contract Standards
/pendingTransactions POST None N/A

Request Body:

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

Revoke Access

Stage Most recent update
Development TR50
Beta TR50
Production TR50

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

Endpoint Type Authentication Supported Contract Standards
/revokeAccess POST JWT N/A

Authenticate Request Body: None required

Update Inventory

Stage Most recent update
Development TR49
Beta N/A
Production N/A

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

Endpoint Type Authentication Supported Contract Standards
/updateInventory POST JWT N/A

Request Body:

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

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

Update Item Level

Stage Most recent update
Development TR49
Beta N/A
Production N/A

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

Endpoint Type Authentication Supported Contract Standards
/updateItemLevel POST JWT ERC-1155, ERC-721

Must include your JWT in the authorization header to add items to 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 xenumId as itemId

Example success response:

{
}

Update Metadata

Stage Most recent update
Development TR50
Beta TR49
Production TR49

Update a particular user’s app_metadata for the given ${game}

Endpoint Type Authentication Supported Contract Standards
/updateMetadata/${game} POST JWT N/A

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

Request Body:

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

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

Verify Email

Stage Most recent update
Development TR49
Beta TR49
Production TR49

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

Endpoint Type Authentication Supported Contract Standards
/verifyEmail POST JWT N/A

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

Request Body:

{
}

Returns an empty body on success.

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