NFT Data / API Docs

API Documentation

NFT Data is a pay-per-request API for AI agents that returns structured market data for any OpenSea collection. Send a collection slug and get floor price, 24h/7d/30d/all-time sales and volume, total supply, unique owners, contract addresses and creation date. Data is sourced from the OpenSea API and passed through as is, with currencies reported in the response (ETH, USDC, etc.). Each successful request costs $0.002, payable in USDC using x402 v2 (Base mainnet or Solana mainnet) or MPP evm/charge (Base mainnet). No API keys or subscriptions required. Registered as OpenSea Tool #778 (ERC-8257).

Overview

Price
$0.002 per request
Payment
x402 v2 (Base + Solana) or MPP evm/charge (Base) - USDC
Data source
OpenSea API v2
Format
JSON over HTTPS

Quick start for AI agents

NFT Data provides structured OpenSea NFT collection and market data for AI agents. A single paid POST request returns floor price, trading volume, sales activity, supply, ownership count, and creation date for any OpenSea collection.

Endpoint
POST https://www.nftdata.app/api/get-collection-data
Price
$0.002 per successful request

Requests require a compatible payment client. Two payment protocols are supported:

  • x402 v2 - send a signed PAYMENT-SIGNATURE header. Accepted on Base mainnet and Solana mainnet. See x402 payment details below.
  • MPP evm/charge - send an Authorization: Payment header. See MPP payment details below.

OpenAPI specification: https://www.nftdata.app/openapi.json

Agent integrations and usage examples: the x402scan server page provides additional integration instructions and usage examples for compatible agent clients and tools.

Try NFT Data with Poncho - open NFT Data in Poncho to try the API.

Endpoint

POST https://www.nftdata.app/api/get-collection-data

Each request requires a valid payment using one of the two supported protocols: x402 v2 or MPP evm/charge. Unauthenticated calls return 402 Payment Required. See the payment sections below for protocol-specific headers, challenge flows, and integration examples.

Payment: x402 v2

x402 v2 - Base mainnet and Solana mainnet. Payment is 0.002 USDC per request. The server accepts payment on either network - use whichever your client supports. The server advertises payment terms for both networks in the PAYMENT-REQUIRED response header on a 402 response. Submit the signed payment in the PAYMENT-SIGNATURE request header on your next call. If the request succeeds, the server returns a PAYMENT-RESPONSE header with the settlement result. Payment verification is handled by the PayAI x402 facilitator.
NetworkCAIP-2USDC asset
Base mainneteip155:84530x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Solana mainnetsolana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpEPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
Settlement timing. Payment settlement is attempted only after collection data has been retrieved successfully from OpenSea. Requests that fail input validation (400) or encounter an upstream data error (404, 429, 502) do not reach the settlement step.
x402 v2 example request
POST https://www.nftdata.app/api/get-collection-data
Content-Type: application/json
PAYMENT-SIGNATURE: <x402 payment token>

{
  "collection": "azuki"
}

Payment: MPP evm/charge

MPP evm/charge on Base mainnet. Payment is 0.002 USDC per request, settled on Base (chain ID 8453). MPP (Machine Payments Protocol) is a protocol for API-level stablecoin payments. The server uses the evm/charge method with Base mainnet USDC.
Settlement timing. As with x402, payment settlement is attempted only after collection data has been retrieved successfully. Requests that fail input validation or encounter an upstream data error do not reach the settlement step.
1. Unauthenticated request - server responds with 402 and a challenge
HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment method="evm", intent="charge",
    realm="www.nftdata.app", request="<base64url-encoded challenge>"
2. Client resolves the challenge and retries with the credential
POST https://www.nftdata.app/api/get-collection-data
Content-Type: application/json
Authorization: Payment <mpp evm credential>

{
  "collection": "azuki"
}

The credential is a signed EIP-3009 token authorization bound to the challenge. Compatible MPP clients handle challenge resolution and credential construction automatically.

3. Server settles and returns the receipt
HTTP/1.1 200 OK
Content-Type: application/json
MPP-Receipt: <receipt token>

{ ... collection data ... }

The server also accepts the credential in a Payment-Authorization: Payment <credential> header when a forwarding proxy preserves the application Authorization header separately. MPP and x402 credentials are mutually exclusive per request - do not send both. For full protocol details, see the MPP evm/charge documentation and the MPP HTTP 402 protocol reference.

Request

Headers - x402 v2
Content-Type: application/json
PAYMENT-SIGNATURE: <x402 payment token>
Headers - MPP evm/charge
Content-Type: application/json
Authorization: Payment <mpp evm credential>

The required payment header depends on the selected protocol. See x402 v2 and MPP evm/charge for the full challenge and retry flow for each.

Body parameters
Field Type Required Description
collection string required OpenSea collection slug. Lowercase alphanumeric, hyphens, and underscores only. The slug is the identifier visible in the collection's OpenSea URL. Example: azuki, milady, basedpunks.

For full integration examples, see x402 v2 example request and MPP evm/charge integration steps above.

Response fields (200)

Field Type Description
name string Collection display name.
slug string Collection slug (matches the value you sent in the request).
contracts array NFT contract addresses and their chains. Each item has address and chain.
floor_price number Current floor price.
floor_price_currency string Currency symbol for the floor price. Not always ETH -- always read this field alongside floor_price to interpret the amount correctly. Examples from live collections: ETH, USDC, HYPE.
one_day_sales number Number of sales in the last 24 hours.
one_day_volume number Trading volume in the last 24 hours.
one_day_volume_currency string | null Currency symbol for 24-hour volume.
seven_day_sales number | null Number of sales in the last 7 days.
seven_day_volume number | null Trading volume in the last 7 days.
seven_day_volume_currency string | null Currency symbol for 7-day volume.
thirty_day_sales number | null Number of sales in the last 30 days.
thirty_day_volume number | null Trading volume in the last 30 days.
thirty_day_volume_currency string | null Currency symbol for 30-day volume.
total_sales number Total lifetime sales count.
total_volume number Total lifetime trading volume.
total_volume_currency string | null Currency symbol for total lifetime volume.
num_owners number Current number of unique owners.
total_supply number | null Total number of NFTs in the collection.
created_date string | null Collection creation date (ISO 8601 format).

Example response (200)

{
  "name": "based punks",
  "slug": "basedpunks",
  "contracts": [
    {
      "address": "0xcb28749c24af4797808364d71d71539bc01e76d4",
      "chain": "base"
    }
  ],
  "floor_price": 0.02391776,
  "floor_price_currency": "ETH",
  "one_day_sales": 1,
  "one_day_volume": 0.0185,
  "one_day_volume_currency": "ETH",
  "seven_day_sales": 16,
  "seven_day_volume": 0.34213836,
  "seven_day_volume_currency": "ETH",
  "thirty_day_sales": 217,
  "thirty_day_volume": 1.50135021,
  "thirty_day_volume_currency": "ETH",
  "total_sales": 18027,
  "total_volume": 4728.07,
  "total_volume_currency": "ETH",
  "num_owners": 2408,
  "total_supply": 5000,
  "created_date": "2024-04-05"
}

Error responses

402 Payment Required. No valid payment credential was supplied. The response initiates the payment flow for the selected protocol. See x402 v2 or MPP evm/charge for the protocol-specific challenge headers and retry steps.
400 Bad Request. The collection field is missing, empty, or contains characters other than lowercase letters, digits, hyphens, and underscores. Body: {"error": "..."}
404 Not Found. No OpenSea collection exists with the given slug. Body: {"error": "Collection not found."}
405 Method Not Allowed. The endpoint only accepts POST requests. GET and other methods are rejected.
429 Rate Limit Exceeded. The upstream OpenSea API rate limit was reached. A Retry-After header indicates how many seconds to wait before retrying.
502 Bad Gateway. The upstream OpenSea API returned a server error or an authentication failure. Body: {"error": "The upstream OpenSea API returned an error. Please try again later."}

Specifications

Machine-readable OpenAPI spec: /openapi.json (OpenAPI 3.1.0)
OpenSea Tool registration: OpenSea Tool #778
AI tool manifest: /.well-known/ai-tool/nft-data.json