RE:DREAMER Lab
Search
⌃K

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:
  1. 1.
    Open the internal browser of the MetaMask or any other compatible wallet app.
  2. 2.
    Go to the redemption web app and connect your wallet.
  3. 3.
    The web app will display a list of campaigns.
  4. 4.
    Select a campaign from the list.
  5. 5.
    The web app will show a list of available NFTs for the selected campaign.
  6. 6.
    Choose an NFT to redeem.
  7. 7.
    The web application will display a unique QR code or promotional code for the selected NFT, based on the campaign configuration.
  8. 8.
    In the case of a QR code, the Event Organizer (EO) can utilize a scanning application (RE:VIEW) to validate the code.
  9. 9.
    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.
get
/api/v1/passport/:network/campaigns
List campaigns for a network
Returns a list of valid campaigns for a given network.
Parameters
Path
network*
String
Unique identifier of the network. Please refer to the "Network" section located on the "General" page for more information.
Query
start_time
DateTime
ISO 8601 datetime format, e.g. 2023-02-26T15:59:59Z.
end_time
DateTime
ISO 8601 datetime format, e.g. 2023-02-28T15:59:59Z.
status
String
Status of the campaign, i.e. ongoing | scheduled | expired . Default value is ongoing.
mine
Boolean
Set to true to return only projects owned by the campaign creator. Default value is false.
Header
x-api-key*
String
API key.
Responses
200: OK

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.
get
/api/v1/passport/:network/campaigns/:uuid/nfts
List NFTs for a campaign
Returns a list of eligible NFTs owned by the connected wallet for a specific campaign.
Parameters
Path
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.
Header
Authorization*
String
Bearer ${token}. Replace ${token} with the actual JWT.
Responses
200: OK

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.
post
/api/v1/passport/:network/campaigns/:uuid/authorization
Generate authorization message
Returns the authorization information that needs to be signed using the private key associated with the wallet address intended for NFT redemption.
Parameters
Path
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.
Body
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.
Responses
200: OK

Response Parameters

Parameter
Value
Description
uuid
String
Unique identifier of the authorization message.
domain
Object
Fields of the signing domain.
types
Object
The data structure of the domain and message.
primaryType
String
The type to which the message belongs.
message
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.
const messageParam = {
domain,
message,
types,
primaryType
}
​
ethereum.request({
"jsonrpc": "2.0",
"method": "eth_signTypedData_v4",
"params": [
connectedWallet,
JSON.stringify(messageParam)
]
}).then((signature) => console.log(`Signed: ${signature}`))
.catch((error) => console.error);
​
To observe the aforementioned code in action, you can visit our JSFiddle page and follow the steps outlined below::
  1. 1.
    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.
  2. 2.
    Select the desired wallet and click the Next button.
  3. 3.
    Click the Connect button to establish the wallet connection.
  4. 4.
    Copy the API response from STEP 3 and paste it into the "input authorization response" textbox.
  5. 5.
    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.
  6. 6.
    In the popup, click the Sign button in the popup.
  7. 7.
    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:
post
/api/v1/passport/:network/campaigns/:uuid/redeem
Redeem an NFT for specific campaign
Returns a Base64-encoded hash string, which can be used to generate a QR code or displayed directly to end users.
Parameters
Path
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.
Header
Authorization*
String
Bearer ${token}. Replace ${token} with the actual JWT.
Body
authorization_uuid
String
Unique identifier of the authorization message gotten from STEP 3.
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.
Responses
200: OK

Response Parameters

Parameter
Value
Description
after_redeemed
0 | 1 | 2
Refers to the section "Redeem Methods".
created_at
DateTime
ISO 8601 datetime format, e.g. 2023-02-26T15:59:59Z.
qr_code
String
The string is formatted as REDREAMER:${redemption-info}. The ${redemption-info} string is encoded in Base64 format.
redeemed_description
String
The string to be displayed on the same page as the QR code.
validated_description
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:
{
"network":String,
"campaign_uuid":String,
"campaign_id":String,
"contract_address":String,
"token_id":Integer,
"requester_address":String,
"hash":String
}

Redeem Methods

The Campaign configuration in Redeem Console offers three redemption methods:
Code
Method Name
Description
0
Validate QR Code
Use the hash string to generate QR code for end users.
1
Only Show Description
Show redeemed_description string only.
2
Show Plain Text
Show the hash string to the end user.

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:
post
/api/v1/passport/:network/campaigns/:uuid/validate
Validate the code
Validate the hash string extracted from the qr_code for redemption.
Parameters
Path
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.
Header
x-api-key*
String
API key.
Body
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 hash string extracted from the qr_code that needs to be validated for redemption.
Responses
200: OK

Error Codes

Code
Description
PASSPORT_CAMPAIGN_NOT_FOUND
Campaign not found.
PASSPORT_NETWORK_MISMATCH
Network mismatch.
EXCEED_MAXIMUM_PASSPORT_REDEMPTION
Exceeded the maximum number of allowed redemptions.
NOT_TOKEN_OWNER
The user is not the token owner.
INVALID_PASSPORT_CAMPAIGN
Invalid campaign.
QR_CODE_EXPIRED
The QR code is expired.
INVALID_QR_CODE
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=
​
​
Previous
Authorization
Next
RE:VIVE
Last modified 2mo ago