# 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

<mark style="color:blue;">`GET`</mark> `/api/v1/passport/:network/campaigns`

Returns a list of valid campaigns for a given network.

#### Path Parameters

| Name                                      | Type   | Description                                                                                                                 |
| ----------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------- |
| network<mark style="color:red;">\*</mark> | 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<mark style="color:red;">\*</mark> | String | API key.    |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "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"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

### 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

<mark style="color:blue;">`GET`</mark> `/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<mark style="color:red;">\*</mark>    | String | The unique identifier of the campaign for which the list of eligible NFTs is being retrieved.                               |
| network<mark style="color:red;">\*</mark> | 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<mark style="color:red;">\*</mark> | String | `Bearer ${token}`. Replace `${token}` with the actual JWT. |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "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": []
        }
    ]
}
```

{% endtab %}
{% endtabs %}

### 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

<mark style="color:green;">`POST`</mark> `/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<mark style="color:red;">\*</mark> | String | Unique identifier of the network. Please refer to the "Network" section located on the "General" page for more information. |
| uuid<mark style="color:red;">\*</mark>    | String | The unique identifier of the campaign for which the list of eligible NFTs is being retrieved.                               |

#### Request Body

| Name                                                | Type    | Description                                                    |
| --------------------------------------------------- | ------- | -------------------------------------------------------------- |
| contract\_address<mark style="color:red;">\*</mark> | String  | The address of the smart contract for the selected NFT.        |
| token\_id<mark style="color:red;">\*</mark>         | Integer | Unique identifier for an NFT within a specific smart contract. |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "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
    }
}
```

{% endtab %}
{% endtabs %}

#### 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](https://eips.ethereum.org/EIPS/eip-712) standard.

#### Ethereum provider API

{% hint style="danger" %}
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.
{% endhint %}

For instructions on constructing the EIP-712 message and obtaining the signature, please consult the provided JavaScript code snippet below.

```javascript
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](https://jsfiddle.net/randyanto/q9u0npor/52/) 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.

{% hint style="info" %}
For managing multiple wallets, e.g. Metamask, Gnosis, Coinbase wallet, we recommend to use [web3-react](https://github.com/Uniswap/web3-react) packages which is developed by Uniswap.
{% endhint %}

### STEP 5: Redeem an NFT

To redeem an NFT, send a POST request to the following endpoint:

## Redeem an NFT for specific campaign

<mark style="color:green;">`POST`</mark> `/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<mark style="color:red;">\*</mark> | String | Unique identifier of the network. Please refer to the "Network" section located on the "General" page for more information. |
| uuid<mark style="color:red;">\*</mark>    | String | The unique identifier of the campaign for which the list of eligible NFTs is being retrieved.                               |

#### Headers

| Name                                            | Type   | Description                                                |
| ----------------------------------------------- | ------ | ---------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | `Bearer ${token}`. Replace `${token}` with the actual JWT. |

#### Request Body

| Name                                                | Type    | Description                                                        |
| --------------------------------------------------- | ------- | ------------------------------------------------------------------ |
| contract\_address<mark style="color:red;">\*</mark> | String  | The address of the smart contract for the selected NFT.            |
| signature<mark style="color:red;">\*</mark>         | String  | Signature gotten from STEP 4.                                      |
| token\_id<mark style="color:red;">\*</mark>         | Integer | Unique identifier for an NFT within a specific smart contract.     |
| authorization\_uuid                                 | String  | Unique identifier of the authorization message gotten from STEP 3. |

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}
{% endtabs %}

#### Response Parameters

<table><thead><tr><th width="268">Parameter</th><th width="109">Value</th><th>Description</th></tr></thead><tbody><tr><td><code>after_redeemed</code></td><td>0 | 1 | 2</td><td>Refers to the section "Redeem Methods".</td></tr><tr><td><code>created_at</code></td><td>DateTime</td><td>ISO 8601 datetime format, e.g.  <code>2023-02-26T15:59:59Z</code>.</td></tr><tr><td><code>qr_code</code></td><td>String</td><td>The string is formatted as <code>REDREAMER:${redemption-info}</code>. The <code>${redemption-info}</code> string is encoded in Base64 format.</td></tr><tr><td><code>redeemed_description</code></td><td>String</td><td>The string to be displayed on the same page as the QR code.</td></tr><tr><td><code>validated_description</code></td><td>String</td><td>The string to be displayed after the QR code is successfully validated.</td></tr></tbody></table>

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:

<table><thead><tr><th width="88.33333333333331">Code</th><th width="235">Method Name</th><th>Description</th></tr></thead><tbody><tr><td><code>0</code></td><td>Validate QR Code</td><td>Use the <code>hash</code> string to generate QR code for end users.</td></tr><tr><td><code>1</code></td><td>Only Show Description</td><td>Show <code>redeemed_description</code> string only.</td></tr><tr><td><code>2</code></td><td>Show Plain Text</td><td>Show the <code>hash</code> string to the end user.</td></tr></tbody></table>

### STEP 6: Validate the QR code

{% hint style="danger" %}
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.
{% endhint %}

To validate the QR code, send a POST request to the following endpoint:

## Validate the code

<mark style="color:green;">`POST`</mark> `/api/v1/passport/:network/campaigns/:uuid/validate`

Validate the `hash` string extracted from the `qr_code` for redemption.

#### Path Parameters

| Name                                      | Type   | Description                                                                                                                 |
| ----------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------- |
| network<mark style="color:red;">\*</mark> | String | Unique identifier of the network. Please refer to the "Network" section located on the "General" page for more information. |
| uuid<mark style="color:red;">\*</mark>    | String | The unique identifier of the campaign for which the list of eligible NFTs is being retrieved.                               |

#### Headers

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| x-api-key<mark style="color:red;">\*</mark> | String | API key.    |

#### Request Body

| Name                                                 | Type    | Description                                                                               |
| ---------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------- |
| requester\_address<mark style="color:red;">\*</mark> | String  | Wallet address of the user who intends to perform a redemption.                           |
| contract\_address<mark style="color:red;">\*</mark>  | String  | The address of the smart contract for the selected NFT.                                   |
| token\_id<mark style="color:red;">\*</mark>          | Integer | Unique identifier for an NFT within a specific smart contract.                            |
| hash<mark style="color:red;">\*</mark>               | String  | The `hash` string extracted from the `qr_code` that needs to be validated for redemption. |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "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"
}
```

{% endtab %}
{% endtabs %}

#### Error Codes

<table><thead><tr><th width="396">Code</th><th>Description</th><th data-hidden></th></tr></thead><tbody><tr><td><code>PASSPORT_CAMPAIGN_NOT_FOUND</code></td><td>Campaign not found.</td><td></td></tr><tr><td><code>PASSPORT_NETWORK_MISMATCH</code></td><td>Network mismatch.</td><td></td></tr><tr><td><code>EXCEED_MAXIMUM_PASSPORT_REDEMPTION</code></td><td>Exceeded the maximum number of allowed redemptions.</td><td></td></tr><tr><td><code>NOT_TOKEN_OWNER</code></td><td>The user is not the token owner.</td><td></td></tr><tr><td><code>INVALID_PASSPORT_CAMPAIGN</code></td><td>Invalid campaign.</td><td></td></tr><tr><td><code>QR_CODE_EXPIRED</code></td><td>The QR code is expired.</td><td></td></tr><tr><td><code>INVALID_QR_CODE</code></td><td>The QR code is invalid.</td><td></td></tr></tbody></table>

## 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=`

![](https://445953330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvV9CdXd21P6X0bD9MrDW%2Fuploads%2FAxemXpdAiXFTmNzQJT85%2Ftesting.png?alt=media\&token=ab41f56a-800a-4816-a078-3b8f5152220b)