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, and also to interact with the Xenum 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.
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 |
/dbMarket | db-marketplace/in-game-payment | Called by a user to pay for a game item with an in-game currency | User who is buying the item(s) |
/dbMarket | db-marketplace/get-db-sales | Get all currently available DB sales | No restrictions |
/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 | item-info | Gets metadata of the given item. | 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 | Jan 20 2023 |
Beta | Nov 28 2022 |
Production | Nov 28 2022 |
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 | Jan 20 2023 |
Beta | Dec 13 2022 |
Production | Dec 13 2022 |
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 | Feb 6 2023 (POST ), Feb 6 2023 (DELETE ) |
Beta | Nov 28 2022 (POST ), Dec 12 2022 (DELETE ) |
Production | Nov 28 2022 (POST ), Dec 12 2022 (DELETE ) |
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 | Feb 6 2023 |
Beta | Dec 6 2022 (POST ), Dec 28 2022 (PATCH ) |
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 | Feb 6 2023 |
Beta | Dec 5 2022 |
Production | Dec 5 2022 |
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 | Feb 6 2023 |
Beta | Nov 22 2022 |
Production | Nov 22 2022 |
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 | Apr 17 2023 |
Beta | Nov 22 2022 |
Production | Nov 22 2022 |
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 | Apr 17 2023 |
Beta | Nov 22 2022 |
Production | Nov 22 2022 |
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 | Apr 17 2023 |
Beta | Nov 22 2022 |
Production | Nov 22 2022 |
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 | Dec 8 2022 |
Beta | Nov 22 2022 |
Production | Nov 22 2022 |
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 | Jan 20 2023 |
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 |
Note * ERC-1155 contracts must implement
circulatingSupply(uint256)
ortotalSupply(uint256)
to be supported. Support for ERC-1155 contracts that do not implementcirculatingSupply(uint256)
ortotalSupply(uint256)
is planned.
Response body format:
{
<networkId1>: <amount1>,
<networkId2>: <amount2>,
...
}
Create Item
Stage | Most recent update |
---|---|
Development | Nov 22 2022 |
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>
}
DB Market Functions
DB Currency Payments
Stage | Most recent update |
---|---|
Development | May 25 2023 |
Beta | N/A |
Production | N/A |
Called by a user to pay for a game item with an in-game currency.
Endpoint | Type | Authentication | Supported Contract Standards |
---|---|---|---|
/dbMarket | POST | JWT | N/A |
Must include your JWT in the authorization
header to add items to a project you own.
Request Body:
{
"saleId": <saleId>,
"currency": <Xenum item ID for currency the user wishes to use>,
}
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
Stage | Most recent update |
---|---|
Development | Apr 11 2023 |
Beta | N/A |
Production | N/A |
Get all currently available DB sales.
Endpoint | Type | Authentication | Supported Contract Standards |
---|---|---|---|
/dbMarket | GET | None | N/A |
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
Stage | Most recent update |
---|---|
Development | Apr 24 2023 |
Beta | Nov 22 2022 |
Production | Nov 22 2022 |
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 | Nov 22 2022 |
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 | Nov 28 2022 |
Beta | Nov 28 2022 |
Production | Nov 28 2022 |
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 | Nov 22 2022 |
Beta | Nov 22 2022 |
Production | Nov 22 2022 |
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 | Mar 7 2023 |
Beta | Dec 12 2022 |
Production | Dec 12 2022 |
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 | Nov 22 2022 |
Beta | Nov 22 2022 |
Production | Nov 22 2022 |
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 | Feb 1 2023 |
Beta | Feb 1 2023 |
Production | Nov 22 2022 |
Gets metadata of the given item.
Endpoint | Type | Authentication | Supported Contract Standards |
---|---|---|---|
/item/${internalId} – REMOVED as of Jan 31 2023 (Jan 31 2023) | GET | None | ERC-1155, ERC-721 |
/item/${projectId}/${itemId} – REMOVED as of Jan 31 2023 (Jan 31 2023) | GET | None | ERC-1155, ERC-721 |
/item | GET | None | ERC-1155, ERC-721 |
Pre Jan 31 2023
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.
Jan 31 2023 and later
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 Xenum internal item IDs.
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.
Link Wallet EVM
Stage | Most recent update |
---|---|
Development | Feb 6 2023 |
Beta | Dec 2 2022 |
Production | Dec 2 2022 |
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 | Feb 6 2023 (GET ), Feb 6 2023 (POST ), Feb 7 2023 (PATCH ) |
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 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
Stage | Most recent update |
---|---|
Development | Feb 6 2023 |
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 | Feb 6 2023 |
Beta | N/A |
Production | N/A |
Gets the information for requested mint permits that need to be signed by the developer. (Made with wallet daemon)
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 | Nov 22 2022 |
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 | Nov 28 2022 |
Beta | Nov 28 2022 |
Production | Nov 28 2022 |
Revokes a login session so a JWT can no longer be used
Endpoint | Type | Authentication | Supported Contract Standards |
---|---|---|---|
/revokeAccess | POST | JWT | N/A |
No requset body is required, and any provided body will be ignored.
Update Inventory
Stage | Most recent update |
---|---|
Development | Nov 22 2022 |
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 | Nov 22 2022 |
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 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 xenumId
as itemId
Example success response:
{
}
Update Metadata
Stage | Most recent update |
---|---|
Development | Jan 9 2023 |
Beta | Jan 9 2023 (Security patch 1 of Nov 28 2022) |
Production | Jan 9 2023 (Security patch 1 of Nov 28 2022) |
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.
Endpoint | Type | Authentication | Supported Contract Standards |
---|---|---|---|
/updateMetadata/${game} – DEPRECATED as of Jan 6 2023 (Jan 6 2023) | POST | JWT | N/A |
/updateMetadata/${game} | PATCH | JWT | N/A |
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 Jan 6 2023
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"
.
Verify Email
Stage | Most recent update |
---|---|
Development | Nov 22 2022 |
Beta | Nov 22 2022 |
Production | Nov 22 2022 |
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:
{
}
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"
}