# Drops API Documentation

## Drops API Documentation

Welcome to the official API documentation for Drops shared services.

### What is Drops?

[Drops](https://www.drops.bot) is a comprehensive platform for tracking and checking airdrop eligibility across multiple blockchain networks. Our shared APIs provide developers with easy access to airdrop data for any wallet address.

<figure><img src="https://2599773019-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsutJUuhqcx1Zf5sLIm2A%2Fuploads%2F3uwfFetyi1fNGZja8dci%2Fevm%20eligible.png?alt=media&amp;token=d241d2bb-8901-43a7-bab6-3465b5aa57f5" alt=""><figcaption></figcaption></figure>

### Getting Started

To start using our APIs, you'll need:

1. **API Key** - Contact us [on Twitter](https://x.com/DropsBot) to get your API key&#x20;
2. **Base URL** - All API endpoints are available at `https://api.drops.bot/shared`
3. **Authentication** - Include your API key in the `x-api-key` header


# Introduction

## API Reference

Complete reference for all Drops shared API endpoints.

### Base URL

All API requests should be made to:

```
https://api.drops.bot/shared/
```

### Authentication

All endpoints require authentication via API key. Include your API key in the `x-api-key` header:

```
x-api-key: YOUR_API_KEY
```

### Response Format

All API responses are returned in JSON format with the following structure:

#### Success Response

```
{
  "success": true,
  "data": {
    // Response data here
  }
}
```

#### Error Response

```
{
  "success": false,
  "error": "Human readable error message"
}
```

### Available Endpoints

#### Airdrops API

Check airdrop eligibility and get detailed airdrop information for addresses across multiple blockchain networks.

* `GET /shared/v1/airdrops/:network/:address` - Check airdrop eligibility


# Authentication

All API requests require authentication using API keys.

### API Key Authentication

Drops.bot uses API key authentication to secure access to shared endpoints. Include your API key in the `x-api-key` header with every request.

#### Header Format

```bash
x-api-key: YOUR_API_KEY_HERE
```

#### Example Request

```bash
curl -X GET \
  "https://api.drops.bot/v1/shared/v1/airdrops/evm/0x123...abcd" \
  -H "x-api-key: your-secret-api-key" \
  -H "Content-Type: application/json"
```

### Obtaining an API Key

To get your API key:

1. **Contact our team** - [Reach out on X](https://x.com/DropsBot) to request access
2. **Specify your use case** - Tell us how you plan to use the API
3. **Receive your key** - We'll provide you with a unique API key
4. **Start building** - Begin making authenticated requests

### API Key Security

{% hint style="warning" %}
**Keep your API key secure:**

* Never expose API keys in client-side code
* Store keys securely in environment variables
  {% endhint %}

#### Environment Variables

Store your API key securely:

```bash
# .env
DROPS_BOT_API_KEY=your-secret-api-key
```

```javascript
// Using the API key in your application
const response = await fetch('https://api.drops.bot/shared/v1/airdrops/evm/0x123...', {
  headers: {
    'x-api-key': process.env.DROPS_BOT_API_KEY,
    'Content-Type': 'application/json'
  }
})
```


# Endpoints

* [Address airdrops (simple)](/api-reference/endpoints/address-airdrops-simple)
* [Address airdrops (full)](/api-reference/endpoints/address-airdrops-full)
* [Address Airdrops Value](/api-reference/endpoints/address-airdrops-value)


# Address Airdrops (simple)

This is a free endpoint, but the airdrop details will remain hidden. To reveal the full details, you should redirect users to the corresponding address page on Drops.&#x20;

### Endpoints

#### Get Address Airdrops

<mark style="color:$primary;">GET</mark>  `/shared/v1/airdrops/:network/:address`

Get the eligible airdrops for a specific address.

**Headers**

| Header      | Type   | Required | Description                     |
| ----------- | ------ | -------- | ------------------------------- |
| `x-api-key` | string | ✅        | Your API key for authentication |

**Path Parameters**

| Parameter | Type   | Required | Description                                                                  |
| --------- | ------ | -------- | ---------------------------------------------------------------------------- |
| `network` | string | ✅        | Network to query                                                             |
| `address` | string | ✅        | The wallet address to check (must be a valid address with the network param) |

**Example Requests**

**cURL - Ethereum Address**

```bash
curl -X GET "https://api.drops.bot/shared/v1/airdrops/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" \
  -H "x-api-key: YOUR_API_KEY"
```

The following networks are supported for address airdrop queries:

| Network ID | Name                                                         |
| ---------- | ------------------------------------------------------------ |
| `evm`      | All EVM and L2 chains                                        |
| `solana`   | Solana                                                       |
| `move`     | Sui, Aptos, and all other Move Networks                      |
| `cosmos`   | Cosmos and all subnets (address must start with \`cosmos1\`) |
| `bitcoin`  | Bitcoin                                                      |
| `starknet` | Starknet                                                     |

### Response

#### 200 - Successful Response

```typescript
{
  "success": true,
  "data": AddressAirdropData[]
}
```

#### AddressAirdropData

| Field                | Type    | Description                                                                                                                  |
| -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `airdropId`          | string  | Unique identifier of the airdrop                                                                                             |
| `airdropName`        | string  | Name of the airdrop                                                                                                          |
| `imgUrl`             | string  | URL of the airdrop image/logo                                                                                                |
| `usdValue`           | number  | Fiat equivalent value of the claim                                                                                           |
| `isUnknownUsdValue`  | boolean | Whether the fiat value of the airdrop is known. (Final allocation can be unknown, or there's no premarket price before TGE). |
| `isExpiringSoon`     | boolean | Whether the airdrop is expiring soon (in the next 30 days)                                                                   |
| `isExpiringVerySoon` | boolean | Whether the airdrop is expiring very soon (in the next 7 days)                                                               |
| `addressUrl`         | string  | URL to the airdrop details page for the given address on Drops                                                               |


# Address Airdrops (full)

**This endpoint returns all revealed airdrop details.**\
If you want to use this data within your own app, note that since airdrop information is the core value of Drops, **this is a paid endpoint.**

Pricing ranges from **$0.025–$0.10 per credit**, depending on the package size. **Minimum starter package is $500**, which includes **5,000 address check credits**.

**Credit System:**

* **First check of any address costs 1 credit.** That credit covers unlimited re-checks of the same address for the rest of the month
* **Repeated checks** of the same address within the same month **are** **free**
* Usage resets at the start of each calendar month (midnight UTC)
* **Unused credits roll over** automatically to the next month

Contact [Drops on X](https://x.com/DropsBotHQ) for details. Include your expected monthly request amount in the message.

{% hint style="info" %}
There are also **free API endpoints:** [**Address Airdrops (simple)**](/api-reference/endpoints/address-airdrops-simple) and [**Address Airdrops Value**](/api-reference/endpoints/address-airdrops-value)**,** which return the total airdrop value **without the** **claiming details.**\
For full claiming details, users should be redirected to Drops to view the information.
{% endhint %}

### Endpoints

#### Get Address Airdrops with full details

<mark style="color:$primary;">GET</mark>  `/shared/v1/full/airdrops/:network/:address`

Get the eligible airdrops for a specific address.

**Headers**

| Header      | Type   | Required | Description                     |
| ----------- | ------ | -------- | ------------------------------- |
| `x-api-key` | string | ✅        | Your API key for authentication |

**Path Parameters**

| Parameter | Type   | Required | Description                                                                  |
| --------- | ------ | -------- | ---------------------------------------------------------------------------- |
| `network` | string | ✅        | Network to query                                                             |
| `address` | string | ✅        | The wallet address to check (must be a valid address with the network param) |

**Example Requests**

**cURL - Ethereum Address**

```bash
curl -X GET "https://api.drops.bot/shared/v1/full/airdrops/evm/0xBADA550000000000000000000000000000000001" \
  -H "x-api-key: YOUR_API_KEY"
```

The following networks are supported for address airdrop queries:

| Network ID | Name                                                         |
| ---------- | ------------------------------------------------------------ |
| `evm`      | All EVM and L2 chains                                        |
| `solana`   | Solana                                                       |
| `move`     | Sui, Aptos, and all other Move Networks                      |
| `cosmos`   | Cosmos and all subnets (address must start with \`cosmos1\`) |
| `bitcoin`  | Bitcoin                                                      |
| `starknet` | Starknet                                                     |

### Response

#### 200 - Successful Response

```typescript
{
  "success": true,
  "data": {
    "eligibleAirdrops": FullAddressAirdropData[],
    "claimedAirdrops": FullAddressAirdropData[],
    "errors": EligibilityCheckErrors[]
  }
}
```

#### FullAddressAirdropData

| Field                  | Type             | Description                                                                                                                                                                         |
| ---------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `airdropId`            | `string`         | Unique identifier of the airdrop                                                                                                                                                    |
| `airdropName`          | `string`         | Name of the airdrop                                                                                                                                                                 |
| `usdValue`             | `number`         | Fiat equivalent value of the claim                                                                                                                                                  |
| `imgUrl`               | `string`         | URL of the airdrop image/logo                                                                                                                                                       |
| `note`                 | `string \| null` | Extra notes if available (otherwise `null`)                                                                                                                                         |
| `tokenSymbol`          | `string`         | Symbol of the airdropped token                                                                                                                                                      |
| `claimFrom`            | `string \| null` | Date/time when claiming opens (UTC). ISO 8601 string                                                                                                                                |
| `claimUntil`           | `string \| null` | Date/time when claiming closes (UTC).  ISO 8601 string                                                                                                                              |
| `directlySent`         | `boolean`        | Whether the tokens are sent automatically without user claim                                                                                                                        |
| `claimUrl`             | `string`         | Official URL where eligible users can claim the airdrop                                                                                                                             |
| `eligibleAmount`       | `number`         | Amount of tokens the address is eligible to claim                                                                                                                                   |
| `isUnknownUsdValue`    | `boolean`        | Whether the fiat value of the airdrop is known (false = value is known)                                                                                                             |
| `addressUrl`           | `string`         | URL to the airdrop details page for the given address on Drops                                                                                                                      |
| `isClaimStatusChecked` | `boolean`        | Indicates whether the claim status of the airdrop was successfully verified. If `false`, the claim status couldn’t be checked (for example, due to an unavailable contract or API). |

#### EligibilityCheckErrors

When one or more airdrops eligibility check fails, they appear in the `errors` array.\
These are usually **temporary issues** and can be retried later.

| Field         | Type   | Description                                          |
| ------------- | ------ | ---------------------------------------------------- |
| `airdropId`   | string | Unique identifier of the airdrop that failed to load |
| `address`     | string | Address for which the airdrop check failed           |
| `reason`      | string | Short message describing the error or failed check   |
| `airdropName` | string | Human-readable name of the airdrop                   |
| `airdropUrl`  | string | Link to the airdrop details page on Drops            |

### Testing Addresses

The Full Airdrops API provides special testing addresses that return predictable mock data without consuming credits. These addresses are useful for integration testing, debugging, and development.

#### Available Testing Addresses

All testing addresses use the EVM network and start with the prefix `0xBADA55`.

**1. Two Eligible Airdrops (With Fiat Value)**

Address: `0xBADA550000000000000000000000000000000001` Network: evm

**Returns:**

* 2 eligible airdrops, 1 claimed airdrop
* Airdrop 1: 1,000 TEST1 tokens ($100 USD)
* Airdrop 2: 2,500 TEST2 tokens ($250 USD)
* Airdrop 3: 2,500 TEST3 tokens ($250 USD) ***claimed***

**2. Two Eligible Airdrops (No Fiat Value)**

Address: `0xBADA550000000000000000000000000000000002` Network: evm

**Returns:**

* 2 eligible airdrops
* Airdrop 3: 5,000 TEST3 tokens ($0 USD)
* Airdrop 4: 10,000 TEST4 tokens ($0 USD)

**3. Failed Eligibility Check (One Error)**

Address: `0xBADA550000000000000000000000000000000003` Network: evm

**Returns:**

* 0 eligible airdrops
* 1 error in the `errors` array
* Error reason: "Test error: Unable to verify eligibility"

**Use case:** Testing error handling and display.

**4. No Airdrops Found**

Address: `0xBADA550000000000000000000000000000000004` Network: evm

**Returns:**

* 0 eligible airdrops
* 0 errors
* Empty response

**Use case:** Testing addresses with no airdrop eligibility.

#### Example Request

```bash
curl -X GET \
  'https://www.drops.bot/api/shared/v1/full/ai
rdrops/evm/0xBADA55000000000000000000000000000
0000001' \
  -H 'x-api-key: YOUR_API_KEY'
```

#### Example Response

```json
{
  "success": true,
  "data": {
    "eligibleAirdrops": [
      {
        "airdropId": "test-airdrop-1",
        "airdropName": "Test Airdrop 1",
        "usdValue": 100,
        "eligibleAmount": 1000,
        "tokenSymbol": "TEST1",
        "isUnknownUsdValue": false,
        "imgUrl": "https://www.drops.bot/images/airdrops/mystery-drop-600px.png",
        "claimFrom": "2025-01-01T00:00:00.000Z",
        "claimUntil": "2045-12-31T23:59:59.999Z",
        "claimUrl": "https://test1.example.com/claim",
        "directlySent": false,
        "note": "Test airdrop with fiat value",
        "isClaimStatusChecked": true,
        "addressUrl": "https://www.drops.bot/address/0xBADA550000000000000000000000000000000001/EVM"
      },
      {
        "airdropId": "test-airdrop-2",
        "airdropName": "Test Airdrop 2",
        "usdValue": 250,
        "eligibleAmount": 2500,
        "tokenSymbol": "TEST2",
        "isUnknownUsdValue": false,
        "imgUrl": "https://www.drops.bot/images/airdrops/mystery-drop-600px.png",
        "claimFrom": "2025-01-01T00:00:00.000Z",
        "claimUntil": "2045-12-31T23:59:59.999Z",
        "claimUrl": "https://test2.example.com/claim",
        "directlySent": false,
        "note": "Another test airdrop with fiat value",
        "isClaimStatusChecked": true,
        "addressUrl": "https://www.drops.bot/address/0xBADA550000000000000000000000000000000001/EVM"
      }
    ],
    "errors": []
  }
}

```


# Address Airdrops Value

Returns the **total fiat value of unclaimed airdrops** for a given address on a supported network. To reveal the full details, you should redirect users to the corresponding address page on Drops.&#x20;

### Endpoints

#### Get Address Airdrops

<mark style="color:$primary;">GET</mark>  `/shared/v1/value/airdrops/:network/:address`

**Headers**

| Header      | Type   | Required | Description                     |
| ----------- | ------ | -------- | ------------------------------- |
| `x-api-key` | string | ✅        | Your API key for authentication |

**Path Parameters**

| Parameter | Type   | Required | Description                                                                  |
| --------- | ------ | -------- | ---------------------------------------------------------------------------- |
| `network` | string | ✅        | Network to query                                                             |
| `address` | string | ✅        | The wallet address to check (must be a valid address with the network param) |

**Example Requests**

**cURL - Ethereum Address**

```bash
curl -X GET "https://api.drops.bot/shared/v1/value/airdrops/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" \
  -H "x-api-key: YOUR_API_KEY"
```

The following networks are supported for address airdrop queries:

| Network ID | Name                                                         |
| ---------- | ------------------------------------------------------------ |
| `evm`      | All EVM and L2 chains                                        |
| `solana`   | Solana                                                       |
| `move`     | Sui, Aptos, and all other Move Networks                      |
| `cosmos`   | Cosmos and all subnets (address must start with \`cosmos1\`) |
| `bitcoin`  | Bitcoin                                                      |
| `starknet` | Starknet                                                     |

### Response

#### 200 - Successful Response

```typescript
{
  "success": true,
  "data": AddressAirdropValueData
}
```

#### AddressAirdropValueData

| Field                    | Type    | Description                                                              |
| ------------------------ | ------- | ------------------------------------------------------------------------ |
| `airdropsCount`          | number  | Number of eligible airdrops for the given address                        |
| `totalValueUsd`          | number  | Total fiat value of unclaimed airdrops (in USD)                          |
| `totalValueUsdFormatted` | string  | Human-readable formatted string of the total value (e.g. "$123.45")      |
| `isUnknownUsdValue`      | boolean | True if the total value cannot be calculated (e.g. missing token prices) |
| `addressUrl`             | string  | URL to the Drops address page with details for the given address         |

#### Example Success Response

```json
{
  "success": true,
  "data": {
    "airdropsCount": 3,
    "totalValueUsd": 452.78,
    "totalValueUsdFormatted": "$452.78",
    "isUnknownUsdValue": false,
    "addressUrl": "https://www.drops.bot/address/0x1234abcd..."
  }
}
```

#### Example Response (unknown USD value of the airdrops)

Sometimes the value of the airdrops can’t be determined. For example, before TGE or if the total allocation is unknown.

```json
{
  "success": true,
  "data": {
    "airdropsCount": 2,
    "totalValueUsd": 0,
    "totalValueUsdFormatted": "$0",
    "isUnknownUsdValue": true,
    "addressUrl": "https://www.drops.bot/address/0x1234abcd..."
  }
}

```


# Error Responses

#### 400 Bad Request - Invalid Address

```json
{
  "success": false,
  "error": "Invalid address format"
}
```

#### 401 Unauthorized - Missing/Invalid API Key

```json
{
  "success": false,
  "error": "API key required in header"
}
```

#### 402 Forbidden - Insufficient credits

```json
{
  "success": false,
  "error": "Insufficient credits"
}
```

#### 403 Forbidden - Insufficient Paid Endpoint Permission

```json
{
  "success": false,
  "error": "Paid endpoints require credit billing to be enabled"
}
```

#### 403 Forbidden - Insufficient API Key Permissions&#x20;

```json
{
  "success": false,
  "error": "API key not authorized for this endpoint"
}
```

#### 404 Not Found - Request path invalid

```json
{
  "success": false,
  "error": "Not found"
}
```

#### 404 Not Found - Unsupported Network

```json
{
  "success": false,
  "error": "Network not supported"
}
```

#### 429 Rate Limit Exceeded

```json
{
  "success": false,
  "error": "Rate limit exceeded"
}
```

#### 500 Internal Server Error - API Unavailable

```json
{
  "success": false,
  "error": "External service unavailable"
}
```