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. Open the internal browser of the MetaMask or any other compatible wallet app.

2. Go to the redemption web app and connect your wallet.

3. The web app will display a list of campaigns.

4. Select a campaign from the list.

5. The web app will show a list of available NFTs for the selected campaign.

6. Choose an NFT to redeem.

7. The web application will display a unique QR code or promotional code for the selected NFT, based on the campaign configuration.

8. In the case of a QR code, the Event Organizer (EO) can utilize a scanning application (RE:VIEW) to validate the code.

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.

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 true to return only projects owned by the campaign creator. Default value is false.
status	String	Status of the campaign, i.e. ongoing | scheduled | expired . Default value is ongoing.
end_time	DateTime	ISO 8601 datetime format, e.g. 2023-02-28T15:59:59Z.
start_time	DateTime	ISO 8601 datetime format, e.g. 2023-02-26T15:59:59Z.

Headers

Name	Type	Description
x-api-key*	String	API key.

200: OK

{
    "data": [
        {
            "id": String,
            "uuid": String,
            "network": "eth",
            "name": String,
            "description": String,
            "validated_description": String,
            "redeemed_description": String,
            "image_url": String,
            "contract_addresses": [
                String
            ],
            "start_time": "2023-02-24T16:00:00Z",
            "end_time": "2023-02-28T15:59:59Z",
            "created_at": "2023-02-23T08:07:24.890266Z",
            "updated_at": "2023-02-23T08:08:38.173575Z",
            "deleted_at": "0001-01-01T00:00:00Z"
        }
    ]
}

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	Bearer ${token}. Replace ${token} with the actual JWT.

200: OK

{
    "data": [
        {
            "id": String,
            "uuid": String,
            "network": "eth",
            "contract_address": String,
            "token_id": Integer,
            "is_valid": Boolean,
            "is_redeemable": Boolean,
            "created_at": "0001-01-01T00:00:00Z",
            "updated_at": "0001-01-01T00:00:00Z",
            "deleted_at": "0001-01-01T00:00:00Z",
            "name": String,
            "description": String,
            "image": String,
            "external_url": String,
            "animation_url": String,
            "attributes": []
        }
    ]
}

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.

200: OK

{
    "uuid": String,
    "domain": {
        "name": String,
        "version": String,
        "chainId": Integer,
        "verifyingContract": String
    },
    "types": {
        "EIP712Domain": [
            {
                "name": "name",
                "type": "string"
            },
            {
                "name": "version",
                "type": "string"
            },
            {
                "name": "chainId",
                "type": "uint256"
            },
            {
                "name": "verifyingContract",
                "type": "address"
            }
        ],
        "ForwardRequest": [
            {
                "name": "from",
                "type": "address"
            },
            {
                "name": "to",
                "type": "address"
            },
            {
                "name": "value",
                "type": "uint256"
            },
            {
                "name": "gas",
                "type": "uint256"
            },
            {
                "name": "nonce",
                "type": "uint256"
            },
            {
                "name": "data",
                "type": "bytes"
            },
            {
                "name": "validUntilTime",
                "type": "uint256"
            }
        ]
    },
    "primaryType": String,
    "message": {
        "data": String,
        "from": String,
        "gas": Integer,
        "nonce": Integer,
        "to": String,
        "validUntilTime": Integer,
        "value": Integer
    }
}

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. 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. Select the desired wallet and click the Next button.

3. Click the Connect button to establish the wallet connection.

4. Copy the API response from STEP 3 and paste it into the "input authorization response" textbox.

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. In the popup, click the Sign button in the popup.

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:

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	Bearer ${token}. Replace ${token} with the actual JWT.

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.

200: OK

{
    "after_redeemed": 0 | 1 | 2,
    "validated_description": String,
    "redeemed_description": String,
    "qr_code": String,
    "created_at": "2023-02-24T08:23:18.841173051Z"
}

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:

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 hash string extracted from the qr_code that needs to be validated for redemption.

200: OK

{
    "id": String,
    "uuid": String,
    "network": "eth",
    "name": String,
    "description": String,
    "validated_description": String,
    "redeemed_description": String,
    "image_url": String,
    "contract_addresses": [
        String
    ],
    "start_time": "2023-02-17T16:00:00Z",
    "end_time": "2023-02-28T15:59:59Z",
    "created_at": "2023-02-18T08:27:51.46832Z",
    "updated_at": "2023-02-24T06:20:11.968802Z",
    "deleted_at": "0001-01-01T00:00:00Z"
}

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=