RE:DREAMER Lab
Search
⌃K

Redeem Passport

Welcome to the Redeem Passport section of the API documentation. Assuming that users are on the go and are using Android or iOS devices, the following API documentation will guide you through the necessary steps to redeem an NFT via the RE:DREAMER API.

NFT Redemption

Redemption process:
  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 app generates a unique QR code for the selected NFT.
  8. 8.
    Show the QR code to the Event Organizer (EO).
  9. 9.
    The EO scans the QR code using a scanner app.
  10. 10.
    The scanner app will validate the QR code.

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*
Unique identifier of the network. Currently only eth is supported.
Query
startTime
DateTime
ISO 8601 datetime format, e.g. 2023-02-26T15:59:59Z.
endTime
DateTime
ISO 8601 datetime format, e.g. 2023-02-28T15:59:59Z.
status
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*
API key.
Responses
200: OK

STEP 2: List RNFTs for a campaign

To retrieve the list of RNFTs eligible for redemption in a specific campaign, send a GET request to the following endpoint:
get
/api/v1/passport/:network/campaigns/:uuid/nfts
List RNFTs for a campaign
Returns a list of eligible Redeemable-NFTs (RNFTs) owned by the connected wallet for a specific campaign.
Parameters
Path
network*
Unique identifier of the network. Currently only eth is supported.
uuid*
The unique identifier of the campaign for which the list of eligible RNFTs is being retrieved.
Header
Authorization*
Bearer ${token}. Replace ${token} with the actual JWT.
Responses
200: OK

STEP 3: Get the signature

After obtaining the selected campaign's unique identifier, and the selected NFT's token identifier and contract address, you need to sign the following message by using the private key of the wallet address which will be used to redeem the NFT.
campaign_id:${campaign_id},contract_address:${contract_address},token_id:${token_id}

Metamask Playground

You can sign the message without building the UI by using Metamask Playground. Please follow these steps:
  1. 2.
    Click INSPECTOR button in the bottom right corner.
  2. 3.
    Copy the JSON below and paste it to playground inspector.
    {
    "jsonrpc": "2.0",
    "method": "eth_requestAccounts"
    }
  3. 4.
    Click Play button to connect to the wallet. This step will trigger a popup if Metamask wallet extension is installed in the web browser.
  4. 5.
    Select the wallet that will be connected and click Next button.
  5. 6.
    Click Connect button to connect the wallet.
  6. 7.
    Copy the JSON below and paste it to playground inspector.
    {
    "jsonrpc": "2.0",
    "method": "personal_sign",
    "params": [
    "campaign_id:${campaign_id},contract_address:${contract_address},token_id:${token_id}",
    "${address}"
    ],
    "id": 0
    }
  7. 8.
    Replace ${campaign_id} with selected campaign's unique identifier from STEP 1 and replace with the selected NFT's contract address and token identifier from STEP 2. Replace ${address} with the wallet address which will be used for redemption.
  8. 9.
    Click Play button to sign the message. This step will trigger popup if Metamask wallet extension is installed in the web browser.
  9. 10.
    Click Sign button in the popup.
  10. 11.
    In Metamask Playground, see the response payload and get the signature from the result. Example response can be seen below.
    {
    "jsonrpc": "2.0",
    "result": "0xef128476f6e17bc32ead6bddf3daf329c018d03ffc7ebb449c4fc30e36bbb65b20fe38a4303cf718fd1ec1ac675fcea86056d541cd2f88d5bfd2e73e52c2ead21c",
    "id": 0
    }

Build your own web app

In order to sign the message with your own UI. You can follow up the steps mentioned in the following tutorials.
For managing multiple wallets, e.g. Metamask, Gnosis, Coinbase wallet, we recommend to use web3-react packages which is developed by Uniswap.

STEP 4: 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
Unique identifier of the network. Currently only eth is supported.
uuid
The unique identifier of the campaign for which the list of eligible RNFTs is being retrieved.
Header
Authorization*
Bearer ${token}. Replace ${token} with the actual JWT.
Body
contract_address*
The address of the smart contract for the selected NFT.
signature*
Signature gotten from STEP 3.
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":"eth",
"campaign_uuid":String,
"campaign_id":String,
"contract_address":String,
"token_id":0,
"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 5: Validate the QR code

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*
Unique identifier of the network. Currently only eth is supported.
uuid*
The unique identifier of the campaign for which the list of eligible RNFTs is being retrieved.
Header
x-api-key*
API key.
Body
requester_address*
Wallet address of the user who intends to perform a redemption.
contract_address*
The address of the smart contract for the selected NFT.
token_id*
Integer
Unique identifier for an NFT within a specific smart contract.
hash*
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.