# Tide APIs

### Get project space leaderboard <a href="#space-api" id="space-api"></a>

This API lets users view a leaderboard that tracks participants' progress in a certain project space. The leaderboard provides information on the number of tasks completed, rewards claimed, and experience points earned by each participant.

Please note that no authentication is required since leaderboard data is public.

## Get leaderboard

<mark style="color:blue;">`GET`</mark> `https://api-prod.tideprotocol.xyz/public/project/${projectId}/leaderboard`

Get leadboard data of a given Tide project.

#### Query Parameters

| Name                | Type    | Description                                                                                                                            |
| ------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| nextPage            | Integer | Number of the requested page. Default = `1`                                                                                            |
| by                  | ADDRESS | Required field to filter by address                                                                                                    |
| search              | address | Searched value (`by` field required)                                                                                                   |
| pageSize            | Integer | Number of entries for each page. Default = `10`                                                                                        |
| onlyListedCampaigns | Boolean | Filter by campaigns only listed on Tide frontend                                                                                       |
| lastDays            | Integer | Get participants' progress only up to `${lastDays}` days ago. Must be greater than zero. Cannot be used together with `currentPeriod`. |
| currentPeriod       | String  | Get participants' progress of the current period. Accepted values: `WEEK`, `MONTH`. Cannot be used together with `lastDays`.           |
| cids                | String  | Filter by campaigns ID (cids). cids are separated by comma (e.g. cids=`cid,cid,cid)`                                                   |

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

<pre class="language-json"><code class="lang-json"><strong>{
</strong>"filteredLeaderboard": 
[
	{
	"address": "0x0000000000000000000000000000000000000000",
	"taskDone": 100,
	"rewardClaimed": 5,
	"position": 1,
	"xpGained": 50, // XP gained in the last 30 days
	"totalXp": 120 // total amount of XPs
	}
],
"nextPage": 1, // current page
"leaderboardUserCount": 2290, // count of all users in the leaderboard 
"userPosition": {...}
}
</code></pre>

{% endtab %}
{% endtabs %}

### Get Tide NFT user data for a specific campaign <a href="#space-api" id="space-api"></a>

This API lets users get information related to one NFT minted in one specific Tide campaign.

Using this endpoint Tide gives you access to information related to the specific campaign and metadata related to the NFT minted by one specific user.

Please note that no authentication is required since the data shown is public.

## Get tide NFT user data

<mark style="color:blue;">`GET`</mark> `https://api-prod.tideprotocol.xyz/public/nft/${userAddress}/${contractAddress}/${chainId}`

Display user NFT metadata as well as other info such as leaderboard position, XPs, etc.

#### Path Parameters

| Name            | Type   | Description                                                  |
| --------------- | ------ | ------------------------------------------------------------ |
| userAddress     | String | Wallet address of the user for which data will be retrieved. |
| contractAddress | String | Contract address for the campaigns that is tracked.          |
| chainId         | String | ChainId in which the campaign contract has been deployed.    |

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

<pre class="language-json"><code class="lang-json">{
"name": "MafiaBird #1",
"attributes": [
    {
        "trait_type": "Body",
        "value": "Rocco"
    },
    {
        "trait_type": "Clothes",
        "value": "Harlem"
    },
    {
        "trait_type": "Background",
<strong>        "value": "Empire State Building"
</strong>    },
    {
        "trait_type": "Role",
        "value": "Ally"
    },
    {
        "trait_type": "Weapon",
        "value": "Bird's Knuckles"
<strong>    },
</strong>    {
        "trait_type": "XP",
        "value": "65"
<strong>    }
</strong>],
"userPosition": {
    "address": "0x30b0EAe5e9Df8a1C95dFdB7AF86aa4e7F3B51f13",
    "rewardClaimed": 1,
    "taskDone": 2,
    "referralXp": 10, // xp gained from referral
    "taskXp": 20, // xp gained from tasks
    "xpGained": 10, // xp gained in the last 30 days
    "totalXp": 65, // total xp gaiend
    "xpEarned": 65, // total xp gained
    "position": 1137
},
"description": "Are you ready to become a made bird and dive into The Magpie Mafia? 🐦🗡️ Enter the gang, climb your way up thru the ranks of a fun-oriented mafia-style organization, and be rewarded for your activity. 🔥🫡  By joining, you will earn your own nontransferable Magpie Mafia NFT that will level up based on your activity while acting as your way to access future Magpie Mafia functions, track your reputation, and more! 💣From here onwards, each time you’d like to engage in a campaign, join an event, or track your reputation, just show that you’re a member of The Magpie Mafia and join in on all the fun. 💰The beak speaks, the words of The Magpie Mafia carries with it authority and respect. 🪖",
"external_url": "https://www.magpiefi.xyz/",
"image": "https://tideprotocol.infura-ipfs.io/ipfs/QmZHMqGJ69SCofyoXtKaXxrLnoKBbGL92aC5NC79sk9Aks",
"tokenId": "1"
}
</code></pre>

{% endtab %}
{% endtabs %}

### Get Specific Tide campaign

This API lets users get information about a specific campaign

## Get specific tide campaign

<mark style="color:blue;">`GET`</mark> `https://api-prod.tideprotocol.xyz/public/campaign/${campaignId}`

#### Path Parameters

| Name       | Type   | Description              |
| ---------- | ------ | ------------------------ |
| campaignId | String | Campaign identifier (ID) |

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

```
{
        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "title": "CampaignTitle",
        "description": "CampaignDescrition",
        "imageUrl": "https://tideprotocol.infura-ipfs.io/ipfs/XXX",
        "imagePreviewUrl": "",
        "isBanned": false,
        "startTime": "2024-01-19T15:10:57.550Z",
        "endTime": "2024-03-17T15:15:20.550Z",
        "address": "0x7d06....",
        "url": "https://www.tideprotocol.xyz/",
        "chain": 137,
        "projectId": 1,
        "projectLinks": [
            "https://twitter.com/tide_web3",
            "https://discord.gg/x19n2mbs",
         ],
         "successMessage": "Your participation was successful! Thank you for joining.",
         "isGasless": false,
         "isSoulbound": true,
         "listingStatus": "LISTED",
         "template": {
             "type": "RAFFLE",
             "name": "ERC20 Raffle"
         },
        "isCreationCompleted": true,
        "externalReward": 0,
        "createdAt": "2024-01-19T15:10:57.550Z",
        "updatedAt": "2024-01-19T16:44:04.855Z",
        "ipfsHash": "Qmcu5......",
        "participants": 1520,
        "step": 4,
        "ERC20Reward": {
            "amountPerWinner": 100,
            "winners": 100,
            "symbol": "USDC"
        },
        "pickedByTide": true
}
```

{% endtab %}
{% endtabs %}

### Get Tide campaigns for a specific chain

This API lets users get all the campaigns information for a specific chain.

## Get tide campaign for a specific chain

<mark style="color:blue;">`GET`</mark> `https://api-prod.tideprotocol.xyz/public/campaign/chain/${chainId}`

Display all campaigns for a chain with all the campaign info

#### Path Parameters

| Name    | Type   | Description                                               |
| ------- | ------ | --------------------------------------------------------- |
| chainId | String | ChainId in which the campaign contract has been deployed. |

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

<pre><code>{
    "campaigns": 
    [{
        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
<strong>        "title": "CampaignTitle",
</strong><strong>        "description": "CampaignDescrition",
</strong>        "imageUrl": "https://tideprotocol.infura-ipfs.io/ipfs/XXX",
        "imagePreviewUrl": "",
        "isBanned": false,
        "startTime": "2024-01-19T15:10:57.550Z",
        "endTime": "2024-03-17T15:15:20.550Z",
        "address": "0x7d06....",
<strong>        "url": "https://www.tideprotocol.xyz/",
</strong>        "chain": 137,
        "projectId": 1,
<strong>        "projectLinks": [
</strong>            "https://twitter.com/tide_web3",
            "https://discord.gg/x19n2mbs",
         ],
         "successMessage": "Your participation was successful! Thank you for joining.",
         "isGasless": false,
<strong>         "isSoulbound": true,
</strong>         "listingStatus": "LISTED",
         "template": {
             "type": "RAFFLE",
             "name": "ERC20 Raffle"
         },
        "isCreationCompleted": true,
        "externalReward": 0,
        "createdAt": "2024-01-19T15:10:57.550Z",
        "updatedAt": "2024-01-19T16:44:04.855Z",
        "ipfsHash": "Qmcu5......",
        "participants": 1520,
        "step": 4,
        "ERC20Reward": {
            "amountPerWinner": 100,
            "winners": 100,
            "symbol": "USDC"
        },
        "pickedByTide": true
    }],
    "totalCampaigns": 15
}
</code></pre>

{% endtab %}
{% endtabs %}

### Get Campaign info

This API let users get some basic information about a single campaign like participants and campaign's timings.

## Get campaign info

<mark style="color:blue;">`GET`</mark> `https://api-prod.tideprotocol.xyz/public/campaign/info/${campaignId}`

Get campaign basic info, to fetch fast data about users campaign

#### Path Parameters

| Name       | Type   | Description              |
| ---------- | ------ | ------------------------ |
| campaignId | String | Campaign identifier (ID) |

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

```
{
    "participants": 1250,
    "status": "Active" // Active - Idle - Unlisted - Ended
    "startTime": "2024-01-19T15:10:57.550Z",
    "endTime": "2024-03-17T15:15:20.550Z"
}
```

{% endtab %}
{% endtabs %}

### Get User claimable Campaigns

This API let users get information about a specific wallet address claimable campaigns.

## Get user claimable campaigns

<mark style="color:blue;">`GET`</mark> `https://api-prod.tideprotocol.xyz/public/claimable-campaigns/${userAddress}`

Get user claimable Campaigns with number of missing Tasks

#### Path Parameters

| Name        | Type    | Description  |
| ----------- | ------- | ------------ |
| userAddress | Address | User Address |

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

```
[
  {
    "campaignTitle": "NFT Badge Campaign",
    "campaignId": "8d2a1cd0-eda6-4d7e-9ce2-e2354dc4f7ad",
    "campaignChainId": 137,
    "spaceId": 230,
    "missingTasks": 2
  },
  {
    "campaignTitle": "ERC20 raffle Campaign",
    "campaignId": "960ed7b2-b84f-441b-aba9-b832dfc5ba84",
    "campaignChainId": 137,
    "spaceId": 230,
    "missingTasks": 0
  }
]
```

{% endtab %}
{% endtabs %}

### Get User XP for a specific Campaign

This API let users get information about a user's address XPs for a specific campaign.

## Get user XP for a specific campaign

<mark style="color:blue;">`GET`</mark> `https://api-prod.tideprotocol.xyz/public/campaign/user-xp/${userAddress}/${campaignId}`

Get user XPs for a specific campaign

#### Path Parameters

| Name        | Type    | Description              |
| ----------- | ------- | ------------------------ |
| userAddress | Address | User Address             |
| campaignId  | String  | Campaign identifier (ID) |

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

```
{
  "campaignId": "03e130ce-b0ad-4f45-8308-03488dca4f6e",
  "campaignTitle": "NFT Badge Campaign",
  "campaignChainId": 137,
  "spaceName": "Tide Protocol",
  "userAddress": "0x26B6282a68a5616E63B76401414A7939C0F6cc37",
  "userXp": 50
}
```

{% endtab %}
{% endtabs %}

### Get User XP for a specific project Space

This API let users get information about a user's address XPs for a specific project space.

## Get user XP for a specific project space

<mark style="color:blue;">`GET`</mark> `https://api-prod.tideprotocol.xyz/public/project/user-xp/${userAddress}/${projectId}`

Get total user XPs for a specific project space

#### Path Parameters

| Name        | Type    | Description             |
| ----------- | ------- | ----------------------- |
| userAddress | Address | User Address            |
| projectId   | String  | Project identifier (ID) |

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

```
{
  "spaceId": 230,
  "spaceName": "Tide Protocol",
  "userAddress": "0x26B6282a68a5616E63B76401414A7939C0F6cc37",
  "userXp": 120
}
```

{% endtab %}
{% endtabs %}

## Get if user has claimed a campaign

<mark style="color:blue;">`GET`</mark> `https://api-prod.tideprotocol.xyz/public/campaign/participation/${campaignId}?address={userAddress}`

Get if a user has claimed a campaign in TideProtocol

#### Path Parameters

| Name        | Type    | Description  |
| ----------- | ------- | ------------ |
| campaignId  | String  | Campaign Id  |
| userAddress | Address | User Address |

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

```
{
  "data": {
    "result": true
  }
}
```

{% endtab %}

{% tab title="500" %}

```
{
  "data": {
    "result": false
  },
  "error": {
    "code": "0",
    "message": "User has not claimed the campaign"
  }
}
```

{% endtab %}
{% endtabs %}