PASSPORT
Welcome to the Passport v2 section of the API documentation. The following API documentation will guide you through the necessary steps to redeem an NFT via the RE:DREAMER API.
NFT Redemption
Assuming that users are on the go and are using Android or iOS devices, the redemption process is as follow:
Open the internal browser of the MetaMask or any other compatible wallet app.
Go to the redemption web app and connect your wallet.
The web app will display a list of campaigns.
Select a campaign from the list.
The web app will show a list of available NFTs for the selected campaign.
Choose an NFT to redeem.
The web application will display a unique QR code or promotional code for the selected NFT, based on the campaign configuration.
In the case of a QR code, the Event Organizer (EO) can utilize a scanning application (RE:VIEW) to validate the code.
If it is a promotional code, users can enter the code in a designated area to avail the associated benefits.
STEP 1: List campaigns for a network
To retrieve the list of campaigns available for a specific network, send a GET request to the following endpoint.
List campaigns for a network
GET
/api/v1/passport/:network/campaigns
Returns a list of valid campaigns for a given network.
Path Parameters
Name | Type | Description |
---|---|---|
network* | String | Unique identifier of the network. Please refer to the "Network" section located on the "General" page for more information. |
Query Parameters
Name | Type | Description |
---|---|---|
mine | Boolean | Set to |
status | String | Status of the campaign, i.e. |
end_time | DateTime | ISO 8601 datetime format, e.g. |
start_time | DateTime | ISO 8601 datetime format, e.g. |
Headers
Name | Type | Description |
---|---|---|
x-api-key* | String | API key. |
STEP 2: List NFTs for a campaign
To retrieve the list of NFTs eligible for redemption in a specific campaign, send a GET request to the following endpoint.
List NFTs for a campaign
GET
/api/v1/passport/:network/campaigns/:uuid/nfts
Returns a list of eligible NFTs owned by the connected wallet for a specific campaign.
Path Parameters
Name | Type | Description |
---|---|---|
uuid* | String | The unique identifier of the campaign for which the list of eligible NFTs is being retrieved. |
network* | String | Unique identifier of the network. Please refer to the "Network" section located on the "General" page for more information. |
Headers
Name | Type | Description |
---|---|---|
Authorization* | String |
|
STEP 3: Generate authorization message
After obtaining the unique identifier of the selected campaign, as well as the token identifier and contract address of the chosen NFT, the authorization message can be generated by sending a POST request to the following endpoint.
Generate authorization message
POST
/api/v1/passport/:network/campaigns/:uuid/authorization
Returns the authorization information that needs to be signed using the private key associated with the wallet address intended for NFT redemption.
Path Parameters
Name | Type | Description |
---|---|---|
network* | String | Unique identifier of the network. Please refer to the "Network" section located on the "General" page for more information. |
uuid* | String | The unique identifier of the campaign for which the list of eligible NFTs is being retrieved. |
Request Body
Name | Type | Description |
---|---|---|
contract_address* | String | The address of the smart contract for the selected NFT. |
token_id* | Integer | Unique identifier for an NFT within a specific smart contract. |
Response Parameters
Parameter | Value | Description |
---|---|---|
| String | Unique identifier of the authorization message. |
| Object | Fields of the signing domain. |
| Object | The data structure of the |
| String | The type to which the |
| Object | The message to be signed by the wallet address which will be used to redeem the NFT. |
STEP 4: Get the signature
After obtaining the authorization message, you can construct a JSON object by utilizing domain
, types
, primaryType
, and message
. The structure of the JSON object adheres to EIP-712 standard.
Ethereum provider API
In order to utilize the window.ethereum
provider object for suggesting users to sign the EIP-712 message, it is necessary to have the MetaMask browser extension installed.
For instructions on constructing the EIP-712 message and obtaining the signature, please consult the provided JavaScript code snippet below.
To observe the aforementioned code in action, you can visit our JSFiddle page and follow the steps outlined below::
To establish a connection with the wallet, click on the Connect Wallet button. This action will initiate a popup if the MetaMask wallet extension is installed in your web browser.
Select the desired wallet and click the Next button.
Click the Connect button to establish the wallet connection.
Copy the API response from STEP 3 and paste it into the "input authorization response" textbox.
Click the Sign button to sign the message. This action will trigger a popup if the MetaMask wallet extension is installed in your web browser.
In the popup, click the Sign button in the popup.
Retrieve the generated signature.
For managing multiple wallets, e.g. Metamask, Gnosis, Coinbase wallet, we recommend to use web3-react packages which is developed by Uniswap.
STEP 5: Redeem an NFT
To redeem an NFT, send a POST request to the following endpoint:
Redeem an NFT for specific campaign
POST
/api/v1/passport/:network/campaigns/:uuid/redeem
Returns a Base64-encoded hash
string, which can be used to generate a QR code or displayed directly to end users.
Path Parameters
Name | Type | Description |
---|---|---|
network* | String | Unique identifier of the network. Please refer to the "Network" section located on the "General" page for more information. |
uuid* | String | The unique identifier of the campaign for which the list of eligible NFTs is being retrieved. |
Headers
Name | Type | Description |
---|---|---|
Authorization* | String |
|
Request Body
Name | Type | Description |
---|---|---|
contract_address* | String | The address of the smart contract for the selected NFT. |
signature* | String | Signature gotten from STEP 4. |
token_id* | Integer | Unique identifier for an NFT within a specific smart contract. |
authorization_uuid | String | Unique identifier of the authorization message gotten from STEP 3. |
Response Parameters
Parameter | Value | Description |
---|---|---|
| 0 | 1 | 2 | Refers to the section "Redeem Methods". |
| DateTime | ISO 8601 datetime format, e.g. |
| String | The string is formatted as |
| String | The string to be displayed on the same page as the QR code. |
| String | The string to be displayed after the QR code is successfully validated. |
Upon decoding the ${redemption-info}
string, a JSON object will be returned with the following format:
Redeem Methods
The Campaign configuration in Redeem Console offers three redemption methods:
Code | Method Name | Description |
---|---|---|
| Validate QR Code | Use the |
| Only Show Description | Show |
| Show Plain Text | Show the |
STEP 6: Validate the QR code
Please be aware that this API endpoint will be deprecated in the future. We are introducing a new product called RE:VIEW, which will provide the validation utility instead.
To validate the QR code, send a POST request to the following endpoint:
Validate the code
POST
/api/v1/passport/:network/campaigns/:uuid/validate
Validate the hash
string extracted from the qr_code
for redemption.
Path Parameters
Name | Type | Description |
---|---|---|
network* | String | Unique identifier of the network. Please refer to the "Network" section located on the "General" page for more information. |
uuid* | String | The unique identifier of the campaign for which the list of eligible NFTs is being retrieved. |
Headers
Name | Type | Description |
---|---|---|
x-api-key* | String | API key. |
Request Body
Name | Type | Description |
---|---|---|
requester_address* | String | Wallet address of the user who intends to perform a redemption. |
contract_address* | String | The address of the smart contract for the selected NFT. |
token_id* | Integer | Unique identifier for an NFT within a specific smart contract. |
hash* | String | The |
Error Codes
Code | Description |
---|---|
| Campaign not found. |
| Network mismatch. |
| Exceeded the maximum number of allowed redemptions. |
| The user is not the token owner. |
| Invalid campaign. |
| The QR code is expired. |
| The QR code is invalid. |
Testing
For testing purpose, the QR code below can be used. The QR code was generated in the testnet and can be verified an unlimited number of times.
Please use this API key to validate this QR code.
8AetTdcKwtrOvZJcPLI5VP2qxL70_kQ9Pkn6SNECrwo=
Last updated