# NFTPriceFloor API — Extended Reference for AI Agents (llms-full.txt)
# Following llmstxt.org extended format conventions
# Last Updated: 2026-02-21

This file provides a complete, single-document API reference optimised for
AI agent consumption. It includes all endpoints, full response schemas,
field-level descriptions, and usage examples — everything needed to integrate
without navigating a SPA or following multiple links.

For a concise summary see: https://nft-api.nftpricefloor.com/llms.txt
OpenAPI 3.0.3 machine-readable spec: https://nft-api.nftpricefloor.com/openapi.json
AI plugin manifest: https://nft-api.nftpricefloor.com/.well-known/ai-plugin.json

---

## 1. Service Overview

**Name:** NFTPriceFloor API
**Version:** 2.0
**Category:** NFT Data Infrastructure / Blockchain Analytics
**Base URL:** https://nftpf-api-v0.p.rapidapi.com/
**Auth method:** API key via `X-RapidAPI-Key` HTTP header (obtain from RapidAPI)
**Uptime SLA:** 99.9%
**Response format:** JSON (application/json)
**Avg response time:** <100 ms

---

## 2. Authentication

All requests require two headers:

```
X-RapidAPI-Key: YOUR_API_KEY
X-RapidAPI-Host: nftpf-api-v0.p.rapidapi.com
```

Obtain an API key by subscribing to the NFT Price Floor API on RapidAPI:
https://rapidapi.com/nftpricefloor/api/nftpf-api-v0

Rate limits are enforced per plan tier (see Section 4 — Pricing).

---

## 3. Endpoints

### 3.1 GET /projects-v2
**Summary:** List all NFT collections
**Description:** Returns all tracked NFT collections with current stats and floor price data. Suitable for building rankings tables, dashboards, and collection pickers.

**Parameters:** None

**Response 200 schema:**
```json
{
  "projects": [
    {
      "name": "string",               // Human-readable collection name
      "slug": "string",               // URL-safe identifier used in other endpoints
      "ranking": "integer",           // Current floor-cap ranking (1 = highest)
      "imageBlur": "string",          // Base64-encoded blurred preview image (data URI)
      "creator": "string",            // Creator / studio name
      "parentCollection": "string | null",
      "subCollection": "boolean",
      "types": ["string"],            // e.g. ["pfp", "art"]
      "blockchain": "string",         // e.g. "ethereum", "polygon", "solana"
      "bestPriceUrl": "string (uri)", // Marketplace URL for best current listing
      "updatedAt": "string (datetime)",
      "reservoirCollectionId": "string",
      "stats": {
        "totalSupply": "integer",
        "listedCount": "integer",
        "ownersCount": "integer",
        "count": "integer",           // 24h sales count
        "floorInfo": {
          "currentFloorEth": "number",
          "currentFloorUsd": "number",
          "tokenInfo": {
            "contract": "string",     // EVM contract address
            "tokenId": "string",
            "blockchain": "string",
            "source": "string"        // Marketplace where floor was found
          }
        },
        "floorCapEth": "number",      // Floor price × total supply
        "floorCapUsd": "number",
        "floorTemporalityEth": "number",  // 24h floor cap change in ETH
        "floorTemporalityUsd": "number",
        "salesTemporalityEth": "number",  // 24h volume in ETH
        "salesTemporalityUsd": "number"
      }
    }
  ]
}
```

**Example response (truncated):**
```json
{
  "projects": [
    {
      "name": "Bored Ape Yacht Club",
      "slug": "boredapeyachtclub",
      "ranking": 1,
      "creator": "Yuga Labs",
      "blockchain": "ethereum",
      "types": ["pfp"],
      "stats": {
        "totalSupply": 10000,
        "listedCount": 582,
        "ownersCount": 6397,
        "count": 45,
        "floorInfo": {
          "currentFloorEth": 29.5,
          "currentFloorUsd": 47200.15,
          "tokenInfo": {
            "contract": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
            "tokenId": "1234",
            "blockchain": "ethereum",
            "source": "opensea"
          }
        },
        "floorCapEth": 295000,
        "floorCapUsd": 472001500,
        "floorTemporalityEth": 2.5,
        "salesTemporalityEth": 234.5
      }
    }
  ]
}
```

---

### 3.2 GET /projects/{slug}
**Summary:** Get details for a specific NFT collection
**Description:** Returns rich metadata plus current stats for a single collection identified by its slug.

**Path parameters:**
- `slug` (required, string) — collection slug (e.g. `azuki`, `boredapeyachtclub`, `cryptopunks`)

**Response 200 schema:**
```json
{
  "stats": {
    "projectId": "string",
    "slug": "string",
    "totalSupply": "integer",
    "listedCount": "integer",
    "totalOwners": "integer",
    "floorInfo": {
      "currentFloorEth": "number",
      "currentFloorUsd": "number",
      "tokenInfo": {
        "contract": "string",
        "tokenId": "string",
        "blockchain": "string",
        "source": "string"
      }
    },
    "floorCapEth": "number",
    "floorCapUsd": "number",
    "floorTemporalityEth": "number",
    "floorTemporalityUsd": "number",
    "salesTemporalityEth": "number",
    "salesTemporalityUsd": "number",
    "updatedAt": "string (datetime)"
  },
  "details": {
    "name": "string",
    "slug": "string",
    "ranking": "integer",
    "imageBlur": "string",         // Base64 data URI
    "releaseDate": "string (date)",
    "creator": "string",
    "parentCollection": "string | null",
    "subCollection": "boolean",
    "types": ["string"],
    "blockchain": "string",
    "totalSupply": "integer",
    "socialMedia": {
      "twitter": "string (uri)",
      "discord": "string (uri)",
      "website": "string (uri)"
    },
    "contract": "string",
    "textEn": "string",            // English collection description
    "textEs": "string",            // Spanish collection description
    "floorPriceEth": "number",
    "floorPriceUsd": "number",
    "floorInfo": {
      "currentFloorEth": "number",
      "currentFloorUsd": "number"
    },
    "marketplaces": ["string"],    // Marketplaces where this collection is listed
    "bestPriceUrl": "string (uri)",
    "creatorsFee": "number",       // Royalty percentage
    "creatorsFeePayoutAddress": "string",
    "mintPriceEth": "number",
    "mintPriceUsd": "number",
    "reservoirCollectionId": "string"
  }
}
```

---

### 3.3 GET /projects/{slug}/history
**Summary:** Historical floor prices by time interval
**Description:** Returns daily floor price snapshots for a collection. Available to ULTRA and MEGA plan subscribers.

**Path parameters:**
- `slug` (required, string)

**Query parameters:**
- `interval` (optional, string) — one of: `1d`, `7d`, `30d`, `90d`, `180d`, `365d`, `all`
  Default behaviour when omitted: returns all available history.

**Response 200 schema:**
```json
[
  {
    "date": "string (date)",        // e.g. "2024-01-15"
    "floorPrice": "number",         // Floor in ETH
    "floorPriceUSD": "number"
  }
]
```

---

### 3.4 GET /projects/{slug}/history/pricefloor/1d
**Summary:** Granular 1-day floor price history with custom date range
**Description:** Returns index-aligned arrays of timestamps, floor prices, volume, and sales for each day within the specified date window. Available to ULTRA and MEGA plan subscribers.

**Path parameters:**
- `slug` (required, string)

**Query parameters:**
- `start` (optional, integer) — Unix timestamp for range start
- `end` (optional, integer) — Unix timestamp for range end

**IMPORTANT — Array alignment:** All arrays in the response share the same index. Index 0 of `timestamps`, `floorEth`, `floorUsd`, `volumeEth`, `volumeUsd`, and `salesCount` all correspond to the same calendar day.

**Response 200 schema:**
```json
{
  "slug": "string",
  "granularity": "string",         // Always "1d" for this endpoint
  "timestamps": ["integer"],       // Unix timestamps (one per day)
  "floorEth": ["number"],          // Floor price in ETH
  "floorUsd": ["number"],          // Floor price in USD
  "volumeEth": ["number"],         // Daily trading volume in ETH
  "volumeUsd": ["number"],         // Daily trading volume in USD
  "salesCount": ["integer"]        // Number of sales that day
}
```

**Example response:**
```json
{
  "slug": "azuki",
  "granularity": "1d",
  "timestamps": [1640995200, 1641081600, 1641168000],
  "floorEth": [15.2, 14.8, 15.5],
  "floorUsd": [24320, 23680, 24800],
  "volumeEth": [1250.5, 980.2, 1456.8],
  "volumeUsd": [2000800, 1568320, 2330880],
  "salesCount": [45, 32, 67]
}
```

---

### 3.5 GET /brands/stats
**Summary:** Aggregated statistics for NFT brands
**Description:** Returns performance metrics for NFT brands / studios, including floor cap, market dominance, and aggregated sales data.

**Parameters:** None

**Response 200 schema:**
```json
{
  "brands": [
    {
      "name": "string",
      "type": "string",                        // e.g. "creator", "studio"
      "ranking": "integer",
      "totalProjects": "integer",
      "floorCapEth": "number",
      "floorCapUsd": "number",
      "totalFloorCollectionsUp": "integer",    // Collections with rising floor today
      "totalFloorCollectionsDown": "integer",
      "totalFloorCollectionsNoChange": "integer",
      "floorCapTemporalityEth": "number",      // 24h floor cap change
      "floorCapTemporalityUsd": "number",
      "marketDominance": "number",             // % share of total NFT floor cap
      "aggregatedSales": "integer",            // 24h sales count across all collections
      "aggregatedVolumeEth": "number",
      "aggregatedVolumeUsd": "number",
      "socialMedia": {
        "twitter": "string (uri)",
        "website": "string (uri)"
      }
    }
  ]
}
```

---

### 3.6 GET /creators/stats
**Summary:** Performance metrics for individual NFT creators
**Description:** Returns detailed floor cap and volume temporality data for individual creators across multiple time windows.

**Parameters:** None

**Response 200 schema:**
```json
[
  {
    "name": "string",
    "type": "string",
    "ranking": "integer",
    "totalProjects": "integer",
    "floorCapNative": "number",      // Floor cap in native chain token
    "floorCapUsd": "number",
    "totalFloorCollectionsUp": "integer",
    "totalFloorCollectionsDown": "integer",
    "totalFloorCollectionsNoChange": "integer",
    "floorCapTemporalityNative": {
      "val24h": "number",   "diff24h": "number",
      "val7d": "number",    "diff7d": "number",
      "val14d": "number",   "diff14d": "number",
      "val30d": "number",   "diff30d": "number",
      "val90d": "number",   "diff90d": "number"
    },
    "floorCapTemporalityUsd": {
      "val24h": "number",   "diff24h": "number",
      "val7d": "number",    "diff7d": "number",
      "val14d": "number",   "diff14d": "number",
      "val30d": "number",   "diff30d": "number",
      "val90d": "number",   "diff90d": "number"
    }
  }
]
```

The `diff*` fields represent percentage change from the previous period.

---

## 4. Pricing & Plan Limits

| Plan  | Price      | API Calls / Month | Historical Data | Notes                          |
|-------|------------|-------------------|-----------------|--------------------------------|
| Basic | Free       | 1,000             | No              | For testing and prototypes     |
| PRO   | $99/month  | 500,000           | No              | Production applications        |
| ULTRA | $199/month | 500,000           | Yes (540 days)  | Analytics and trading tools    |
| MEGA  | Enterprise | Unlimited         | Yes             | Contact sales@nftpricefloor.com|

Historical data endpoints (3.3 and 3.4) require ULTRA or MEGA plan.

---

## 5. Error Codes

Standard HTTP status codes are used:

| Code | Meaning                                          |
|------|--------------------------------------------------|
| 200  | Success                                          |
| 400  | Bad Request — malformed parameters               |
| 401  | Unauthorised — missing or invalid API key        |
| 403  | Forbidden — plan does not include this endpoint  |
| 404  | Not Found — slug does not exist                  |
| 429  | Too Many Requests — rate limit exceeded          |
| 500  | Internal Server Error                            |

---

## 6. Common Slug Examples

| Collection                | Slug                      |
|---------------------------|---------------------------|
| Bored Ape Yacht Club      | boredapeyachtclub         |
| CryptoPunks               | cryptopunks               |
| Azuki                     | azuki                     |
| Mutant Ape Yacht Club     | mutant-ape-yacht-club     |
| Doodles                   | doodles-official          |
| CloneX                    | clonex                    |
| Art Blocks Curated        | art-blocks-curated        |
| Pudgy Penguins            | pudgy-penguins            |

The full list is returned by GET /projects-v2 (field: `slug`).

---

## 7. Integration Examples

### 7.1 JavaScript — Fetch all collections
```javascript
const res = await fetch('https://nftpf-api-v0.p.rapidapi.com/projects-v2', {
  headers: {
    'X-RapidAPI-Key': 'YOUR_API_KEY',
    'X-RapidAPI-Host': 'nftpf-api-v0.p.rapidapi.com'
  }
});
const { projects } = await res.json();
// Sort by ranking
const ranked = projects.sort((a, b) => a.ranking - b.ranking);
```

### 7.2 JavaScript — Get collection details
```javascript
const slug = 'azuki';
const res = await fetch(`https://nftpf-api-v0.p.rapidapi.com/projects/${slug}`, {
  headers: {
    'X-RapidAPI-Key': 'YOUR_API_KEY',
    'X-RapidAPI-Host': 'nftpf-api-v0.p.rapidapi.com'
  }
});
const { stats, details } = await res.json();
console.log(`${details.name} floor: ${stats.floorInfo.currentFloorEth} ETH`);
```

### 7.3 JavaScript — 90-day floor price history (ULTRA/MEGA)
```javascript
const res = await fetch(
  'https://nftpf-api-v0.p.rapidapi.com/projects/boredapeyachtclub/history?interval=90d',
  {
    headers: {
      'X-RapidAPI-Key': 'YOUR_API_KEY',
      'X-RapidAPI-Host': 'nftpf-api-v0.p.rapidapi.com'
    }
  }
);
const history = await res.json(); // Array of { date, floorPrice, floorPriceUSD }
```

### 7.4 Python — Granular 1-day history with date range (ULTRA/MEGA)
```python
import requests
from datetime import datetime

start = int(datetime(2024, 1, 1).timestamp())
end   = int(datetime(2024, 3, 31).timestamp())

res = requests.get(
  f'https://nftpf-api-v0.p.rapidapi.com/projects/azuki/history/pricefloor/1d',
  params={'start': start, 'end': end},
  headers={
    'X-RapidAPI-Key': 'YOUR_API_KEY',
    'X-RapidAPI-Host': 'nftpf-api-v0.p.rapidapi.com'
  }
)
data = res.json()
# data['timestamps'], data['floorEth'], data['salesCount'] are index-aligned arrays
for i, ts in enumerate(data['timestamps']):
    print(f"{datetime.fromtimestamp(ts).date()}  {data['floorEth'][i]} ETH  {data['salesCount'][i]} sales")
```

### 7.5 Python — Brand market dominance ranking
```python
import requests

res = requests.get(
  'https://nftpf-api-v0.p.rapidapi.com/brands/stats',
  headers={
    'X-RapidAPI-Key': 'YOUR_API_KEY',
    'X-RapidAPI-Host': 'nftpf-api-v0.p.rapidapi.com'
  }
)
brands = res.json()['brands']
brands.sort(key=lambda b: b['marketDominance'], reverse=True)
for b in brands[:5]:
    print(f"{b['ranking']}. {b['name']}  {b['marketDominance']:.1f}% dominance")
```

---

## 8. Data Dictionary (Key Fields)

| Field                  | Type    | Description                                                    |
|------------------------|---------|----------------------------------------------------------------|
| slug                   | string  | Unique URL-safe collection identifier                          |
| currentFloorEth        | number  | Lowest active listing price in ETH                             |
| currentFloorUsd        | number  | Lowest active listing price in USD                             |
| floorCapEth            | number  | Floor price × total supply (market cap proxy)                  |
| floorTemporalityEth    | number  | 24-hour change in floor cap (ETH)                              |
| salesTemporalityEth    | number  | 24-hour trading volume (ETH)                                   |
| listedCount            | integer | Number of tokens currently listed for sale                     |
| ownersCount            | integer | Number of unique wallet owners                                 |
| totalSupply            | integer | Total number of tokens in the collection                       |
| marketDominance        | number  | Brand's percentage of total tracked NFT floor cap              |
| diff24h / diff7d / …   | number  | Percentage change over the named period                        |
| timestamps             | array   | Unix timestamps; index-aligned with floorEth, volumeEth, etc. |
| imageBlur              | string  | Base64 data URI of a low-resolution blurred preview image      |

---

## 9. Data Coverage & Supported Blockchains

- **Ethereum** — full coverage (OpenSea, Blur, LooksRare, X2Y2, NFTx)
- **Polygon** — major collections tracked
- **Solana** — Magic Eden collections

Total collections tracked: 1500+
Historical data depth: up to 540 days (ULTRA / MEGA plans)

---

## 10. Contact & Resources

- Documentation: https://nft-api.nftpricefloor.com/#docs
- OpenAPI spec: https://nft-api.nftpricefloor.com/openapi.json
- Concise llms.txt: https://nft-api.nftpricefloor.com/llms.txt
- AI plugin manifest: https://nft-api.nftpricefloor.com/.well-known/ai-plugin.json
- Support email: team@nftpricefloor.com
- Sales / enterprise: sales@nftpricefloor.com
- Twitter: @nftpricefloor
- Discord: https://discord.com/invite/FgD7J6YjDC