Pentagon NFT Data API

🚀 Getting Started

Get up and running with the NFT Data API in three steps.

X-PG-App-Key: pk_live_your_key

Overview

The Pentagon NFT Data API provides unified NFT ownership tracking across the Pentagon Games ecosystem. Query any wallet, any chain, any collection — one API, one answer.

Base URL

https://nft-data.pentagon.games

Authentication

Pass your app key via the X-PG-App-Key header:

curl -H "X-PG-App-Key: pk_live_your_key" \
  "https://nft-data.pentagon.games/api/v1/nft/owner/0x1234..."

Rate Limits

Rate limits are configurable per app key. When exceeded, the API returns 429 Too Many Requests with a retry_after field.

API Endpoints

Quick Reference

Look Up NFTs by Owner

GET /api/v1/nft/owner/:wallet_address

Returns all NFTs owned by a wallet address across all tracked chains and collections.

Example request:

curl "https://nft-data.pentagon.games/api/v1/nft/owner/0x37224cFD71347Da6f097c94B8649f9C552f803c9?chain_id=3344"

Response:

{
  "owner": "0x37224cFD71347Da6f097c94B8649f9C552f803c9",
  "total": 17,
  "page": 1,
  "limit": 50,
  "nfts": [
    {
      "tokenId": "4201",
      "name": "BCSH #4201",
      "owner": "0x37224cfd71347da6f097c94b8649f9c552f803c9",
      "collection": "BCSH OASYS",
      "contractAddress": "0xcDAD57bFc48E8373280C6dc3039C5169353B6879",
      "chain": 3344,
      "standard": "ERC721",
      "image": "https://images.pfpvault.com/3344/0xcdad.../4201.webp",
      "fileType": "image",
      "mediaType": "image",
      "desc": "After shattering her katana...",
      "transferable": true,
      "updatedAt": "2026-05-11T04:15:39+00:00"
    }
  ]
}

With ?group_by=chain:

{
  "chains": [
    {"chainId": 1, "count": 610, "nfts": [...]},
    {"chainId": 3344, "count": 1, "nfts": [...]}
  ]
}

Look Up NFT by Token ID

GET /api/v1/nft/:contract_address/:token_id

Returns details for a specific NFT including current owner, metadata, and trait attributes.

Response:

{
  "contract": "0xcDAD57bFc48E8373280C6dc3039C5169353B6879",
  "tokenId": "5555000000553",
  "collection": "BCSH OASYS",
  "chain": 3344,
  "owner": "0x6e28399aa9dd598caa49df9fa46d0ae87c0e7d57",
  "transferable": true,
  "standard": "ERC721",
  "metadata": {
    "name": "Dark Setsuko",
    "description": "After shattering her katana...",
    "image": "https://images.pfpvault.com/3344/0xcdad.../5555000000553.webp",
    "imageSource": "cached",
    "attributes": [
      {"trait_type": "Background", "value": "Blue"}
    ]
  },
  "license": {
    "schema": "erc721l-metadata-v1",
    "rights_model": "base-plus-upgrade",
    "current_tier": 4,
    "current_name": "COMMERCIAL_DERIVS_NONEXCLUSIVE",
    "base_tier": 2,
    "upgraded_tier": 4,
    "terms_uri": "https://nft-data.pentagon.games/licenses/tier-4",
    "source": "override"
  },
  "storage": {
    "image": {
      "tier": "cached",
      "provider": "s3+cloudfront",
      "permanence": "managed",
      "url": "https://images.pfpvault.com/3344/0xcdad.../5555000000553.webp",
      "archivalOriginal": "s3://pg-nft-images/originals/3344/0xcdad.../5555000000553.png"
    },
    "metadata": {
      "tier": "override",
      "provider": "pg_nft_db",
      "tokenUri": "https://api.bcsh.xyz/metadata/5555000000553"
    }
  },
  "source": {
    "tokenUri": "https://api.bcsh.xyz/metadata/5555000000553",
    "lastSync": "2026-05-08T18:19:02+00:00"
  }
}

Chain Summary for Owner

GET /api/v1/nft/owner/:address/chains

Returns a lightweight breakdown of how many NFTs a wallet holds on each chain, without fetching full NFT data. Useful for building chain selectors or quick portfolio overviews.

Example request:

curl "https://nft-data.pentagon.games/api/v1/nft/owner/0x37224cFD71347Da6f097c94B8649f9C552f803c9/chains"

Response:

{
  "total": 611,
  "chains": [
    {"chainId": 1, "count": 610},
    {"chainId": 3344, "count": 1}
  ]
}

Multi-Address Lookup

GET /api/v1/nft/owners?addresses=0xABC,0xDEF
POST /api/v1/nft/owners

Merges NFTs from multiple wallet addresses into a single response (max 10 addresses). Supports all the same filters as the single-address endpoint (chain_id, collection, contract, group_by).

GET example:

curl "https://nft-data.pentagon.games/api/v1/nft/owners?addresses=0xABC...,0xDEF...&chain_id=3344"

POST example:

curl -X POST "https://nft-data.pentagon.games/api/v1/nft/owners" \
  -H "Content-Type: application/json" \
  -H "X-PG-App-Key: pk_live_your_key" \
  -d '{"addresses": ["0xABC...", "0xDEF..."]}'

List Tracked Collections

GET /api/v1/collections

Returns the tracked NFT collections with contract address, chain, token standard, indexed token count, and a display logo. Useful for building collection-filter UIs.

Example request:

curl "https://nft-data.pentagon.games/api/v1/collections?chain=1"

Response:

{
  "count": 82,
  "collections": [
    {
      "name": "MoonCats",
      "logo": "https://images.pfpvault.com/1/0xc3f7.../.webp",
      "logoIsFallback": true,
      "logoFilename": null,
      "contractAddress": "0xc3f733ca98e0dad0386979eb96fb1722a1a05e69",
      "chain": 1,
      "standard": "ERC721",
      "count": 20921
    },
    {
      "name": "Gunnies",
      "logo": "https://pentagon.games/images/gunnies-logo.png",
      "logoIsFallback": false,
      "logoFilename": "https://pentagon.games/images/gunnies-logo.png",
      "contractAddress": "0x...",
      "chain": 3344,
      "standard": "ERC721",
      "count": 9093
    }
  ]
}

Fields: name (display name), logo, logoIsFallback, logoFilename, contractAddress, chain (chain ID), standard (ERC721 / ERC1155 / etc), and count (indexed token count). Results are ordered by count descending.

Collection Item Index

GET /api/v1/collection/{contract}/items

Returns every item (token) in a collection, paginated — the collection “item index.” This is the single source of truth for a collection's enumeration: ownership + names + cached-CDN images + transferable/SBT flags, keyed by tokenId.

Example (bulk attributes + rarity, one call):

curl "https://nft-data.pentagon.games/api/v1/collection/0xed5af38...c544/items?limit=200&include=traits,rarity"

Response:

{
  "contractAddress": "0xBF01e486...766",
  "chain": 3344,
  "collection": "EtherFantasy PentaPet",
  "total": 10,
  "page": 1, "limit": 50, "pageSize": 50,
  "items": [
    {
      "tokenId": "10",
      "name": "Pudde #10",
      "image": "https://images.pfpvault.com/3344/0xbf01.../10.webp",   // cached CDN
      "imageOriginal": "https://api.etherfantasy.com/api/pets/image/10",
      "fileType": "image", "mediaType": "image",
      "standard": "ERC721",
      "transferable": false,
      "owner": "0x03ae56d4...9294",
      "updatedAt": "2026-07-12T07:30:39+00:00"
    }
  ]
}

Page through with page/limit until you have all total items. Returns 404 if the contract isn't tracked.

Tradability & Soulbound

Every item carries a transferable boolean. nft-data is the source of truth for whether an NFT can be traded — marketplaces should depend on this rather than deriving it.

Rarity

Trait-frequency rarity is precomputed by nft-data (so every Pentagon surface shows the same rank for a token) and returned on the single-token endpoint and via ?include=rarity on the item index. It ranks within the collection; rank 1 = rarest.

"rarity": {
  "rank": 763,            // 1 = rarest, within the collection
  "totalSupply": 10000,
  "traitCount": 7,
  "rarityScore": 744.76,  // rarity.tools style: Σ (total / count(trait value))
  "infoContent": 34.16    // Σ −log2(freq) — less gameable than rarityScore
}

Two independent standards are exposed so consumers pick: rarityScore (familiar, rarity.tools-compatible) and infoContent (information-theoretic, harder to game by stuffing common traits). rarity is null for collections without indexed traits.

Collection Stats

GET /api/v1/collection/:contract_address/stats

Returns ownership statistics for a collection including total supply, unique holder count, and top holders.

Response:

{
  "contract": "0xcDAD57bFc48E8373280C6dc3039C5169353B6879",
  "name": "BCSH OASYS",
  "total_supply": 10000,
  "unique_owners": 3421,
  "top_holders": [
    {"address": "0x...", "count": 150},
    {"address": "0x...", "count": 87}
  ]
}

Transfer History

GET /api/v1/nft/:contract_address/:token_id/transfers

Returns the full transfer history for a specific NFT, from mint to present.

Response:

{
  "transfers": [
    {
      "from": "0x0000000000000000000000000000000000000000",
      "to": "0x37224cfd71347da6f097c94b8649f9c552f803c9",
      "tx_hash": "0xabc123...",
      "block_number": 1234567,
      "timestamp": "2026-01-15T12:30:00Z"
    }
  ]
}

Report an Issue (flag this)

POST /api/v1/report

Lets any API-enabled site (e.g. a marketplace or explorer) forward an end-user “flag this” report about a data-quality issue — a broken or wrong image, missing metadata, wrong owner, etc. Each project can surface reporting to its own users however it likes; reports land in one shared queue for staff to triage. Requires an app key (submit from your backend, not the browser, so the key is not exposed).

Body (JSON):

Example:

curl -X POST https://nft-data.pentagon.games/api/v1/report \
  -H "X-PG-App-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{
    "chain": 3344,
    "contractAddress": "0x8F83c6122Dd4d275B53a7846B3D3dB29Cca1e698",
    "tokenId": "9549",
    "type": "broken_image",
    "message": "grey background, transparency not removed",
    "reporter": "0x37224cfd71347da6f097c94b8649f9c552f803c9"
  }'

Response:

{ "status": "ok", "reportId": 42 }

List reports (staff triage): GET /api/v1/report (also app-key gated). Filters: ?status=open&chain=3344&contract=0x..&type=broken_image&page=1&limit=50.

{
  "count": 1, "page": 1, "limit": 50,
  "reports": [
    { "id": 42, "chain": 3344, "contractAddress": "0x8f83...", "tokenId": "9549",
      "type": "broken_image", "message": "grey background...", "reporter": "0x3722...",
      "source": "nftmining", "status": "open", "createdAt": "2026-07-04T07:23:51Z" }
  ]
}

Error Responses

// 401 — Invalid or inactive app key
{"error": "Invalid or inactive app key"}

// 404 — NFT or collection not found
{"error": "NFT not found"}

// 429 — Rate limit exceeded
{"error": "Rate limit exceeded", "retry_after": 60}

Supported Chains

The NFT Data API tracks collections across 14 blockchain networks. Pentagon Chain contracts get real-time WebSocket tracking (sub-second updates). All other chains use block-range scanning with 2–6 minute sync intervals.

Tracked Collections

49 collections are actively tracked. Here are the key Pentagon Chain collections. Use GET /api/v1/collections for the full list.

Pentagon Chain (3344)

Ethereum (1)

Adding a New Collection

Want your collection tracked by the Pentagon NFT Data API? Contact the Pentagon Games team with:

• Contract address and chain ID
• Collection name and type (ERC721 or ERC1155)
• Metadata endpoint (tokenURI or custom API), if applicable

Once registered, all four sync layers begin tracking your collection automatically. You'll receive an app key for API access.

How It Works

The NFT Data API is backed by a four-layer sync engine that guarantees ownership accuracy. Every layer cross-checks the others — if they disagree, on-chain truth wins.

Triangulation

When layers disagree on ownership:

• Scanner (Layer 2) takes priority over Listener (Layer 1) — block-range scanning is more reliable than real-time subscriptions
• If disagreement persists, the Verifier (Layer 3) calls ownerOf() on-chain
• On-chain is always ground truth

Integration Examples

import requests

API_BASE = "https://nft-data.pentagon.games"
APP_KEY = "pk_live_your_key"
HEADERS = {"X-PG-App-Key": APP_KEY}

def get_nfts(wallet, chain_id=None):
    """Fetch all NFTs owned by a wallet."""
    url = f"{API_BASE}/api/v1/nft/owner/{wallet}"
    params = {}
    if chain_id:
        params["chain_id"] = chain_id
    resp = requests.get(url, headers=HEADERS, params=params)
    resp.raise_for_status()
    return resp.json()

def get_nft_detail(contract, token_id):
    """Fetch metadata for a specific NFT."""
    url = f"{API_BASE}/api/v1/nft/{contract}/{token_id}"
    resp = requests.get(url, headers=HEADERS)
    resp.raise_for_status()
    return resp.json()

# Example: List all Pentagon chain NFTs for a wallet
wallet = "0x37224cFD71347Da6f097c94B8649f9C552f803c9"
data = get_nfts(wallet, chain_id=3344)
print(f"Found {data['total']} NFTs on Pentagon Chain")
for nft in data["results"]:
    print(f"  {nft['collection']} #{nft['token_id']} - {nft.get('name', 'N/A')}")

const API_BASE = "https://nft-data.pentagon.games";
const APP_KEY = "pk_live_your_key";

async function getNFTs(wallet, chainId) {
  const params = new URLSearchParams();
  if (chainId) params.set("chain_id", chainId);

  const res = await fetch(
    `${API_BASE}/api/v1/nft/owner/${wallet}?${params}`,
    { headers: { "X-PG-App-Key": APP_KEY } }
  );
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

async function getNFTDetail(contract, tokenId) {
  const res = await fetch(
    `${API_BASE}/api/v1/nft/${contract}/${tokenId}`,
    { headers: { "X-PG-App-Key": APP_KEY } }
  );
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

// Example: Check if a wallet holds any Gunnies PFPs
const GUNNIES = "0x7a8a3236e3783E7cC33b97729378e31Cf14d3Ebc";
const wallet = "0x37224cFD71347Da6f097c94B8649f9C552f803c9";
const data = await getNFTs(wallet, 3344);
const gunnies = data.results.filter(n => n.contract.toLowerCase() === GUNNIES.toLowerCase());
console.log(`Wallet holds ${gunnies.length} Gunnies PFP(s)`);

// Discord.js bot — NFT verification command
const { SlashCommandBuilder } = require("discord.js");

const API_BASE = "https://nft-data.pentagon.games";
const APP_KEY = "pk_live_your_key";

module.exports = {
  data: new SlashCommandBuilder()
    .setName("verify-nft")
    .setDescription("Check NFT ownership for a wallet")
    .addStringOption(opt =>
      opt.setName("wallet").setDescription("Wallet address").setRequired(true)
    )
    .addStringOption(opt =>
      opt.setName("collection").setDescription("Collection name filter")
    ),

  async execute(interaction) {
    await interaction.deferReply();

    const wallet = interaction.options.getString("wallet");
    const collection = interaction.options.getString("collection");

    const params = new URLSearchParams();
    if (collection) params.set("collection", collection);

    const res = await fetch(
      `${API_BASE}/api/v1/nft/owner/${wallet}?${params}`,
      { headers: { "X-PG-App-Key": APP_KEY } }
    );
    const data = await res.json();

    if (data.total === 0) {
      return interaction.editReply("No NFTs found for this wallet.");
    }

    const lines = data.results.slice(0, 10).map(
      nft => `**${nft.collection}** #${nft.token_id}`
    );

    await interaction.editReply(
      `Found **${data.total}** NFT(s):\n${lines.join("\n")}`
    );
  }
};

# Health check
curl "https://nft-data.pentagon.games/"

# Look up NFTs by owner (public, no key)
curl "https://nft-data.pentagon.games/api/v1/nft/owner/0x37224cFD71347Da6f097c94B8649f9C552f803c9"

# Look up NFTs with app key + chain filter
curl -H "X-PG-App-Key: pk_live_your_key" \
  "https://nft-data.pentagon.games/api/v1/nft/owner/0x37224cFD71347Da6f097c94B8649f9C552f803c9?chain_id=3344"

# Single NFT detail
curl -H "X-PG-App-Key: pk_live_your_key" \
  "https://nft-data.pentagon.games/api/v1/nft/0xcDAD57bFc48E8373280C6dc3039C5169353B6879/4201"

# List all tracked collections
curl -H "X-PG-App-Key: pk_live_your_key" \
  "https://nft-data.pentagon.games/api/v1/collections"

# Collection stats
curl -H "X-PG-App-Key: pk_live_your_key" \
  "https://nft-data.pentagon.games/api/v1/collection/0xcDAD57bFc48E8373280C6dc3039C5169353B6879/stats"

# Transfer history
curl -H "X-PG-App-Key: pk_live_your_key" \
  "https://nft-data.pentagon.games/api/v1/nft/0xcDAD57bFc48E8373280C6dc3039C5169353B6879/4201/transfers"

Image Resolution

The API uses a four-tier image fallback to ensure NFTs always display the best available artwork:

CDN Image Spec

• Format: WebP, 512px max dimension, quality 80
• Size: ~30–50 KB average (down from 1–6 MB originals)
• URL pattern: https://images.pfpvault.com/{chain_id}/{contract_address}/{token_id}.webp
• Caching: 1-year cache headers (immutable), served via CloudFront edge

Smart Caching

The image cacher detects when a collection shares a single source image across all tokens (common with PFP passes and hero collections). In these cases, the image is downloaded and converted once, then server-side copied to all token slots — caching thousands of tokens in seconds rather than hours.

For collections with variant artwork (e.g. BCSH OASYS with Setsuko, Dark Setsuko, and Obelith Setsuko), the cacher groups tokens by source image and handles each variant independently.

Original Image Archival

When the cacher downloads a source image, it stores the pre-conversion original in a separate S3 path before resizing to the CDN WebP. This gives us a full-fidelity copy that doesn't depend on external sources staying online.

• CDN path: s3://pg-nft-images/{chain}/{contract}/{token_id}.webp — optimized, served via CloudFront
• Originals path: s3://pg-nft-images/originals/{chain}/{contract}/{token_id}.{ext} — full-size, not on CDN, archival only
• Why: External sources (Arweave, IPFS, project APIs) can go down or change. Our copy is the insurance policy.

Image Change History Coming Soon

The system will track dated snapshots of NFT images over time. When the cacher detects that a token's source image has changed (e.g. an NFT upgrade, evolution, or metadata update), it preserves the previous version with a timestamp.

• Change detection: Content hash comparison on each sync — if the image bytes differ, a new snapshot is stored
• History path: s3://pg-nft-images/history/{chain}/{contract}/{token_id}/{timestamp}.webp
• History endpoint: GET /api/v1/nft/:contract/:tokenId/images — returns all dated captures with timestamps
• Use cases: Track NFT evolution (e.g. Setsuko → Dark Setsuko), audit visual changes, prove historical state

Metadata Refresh Coming Soon

A queued metadata refresh system is planned for handling upgradeable NFT collections:

• User-facing: POST /api/v1/nft/refresh/:contract/:tokenId — rate-limited to 1 refresh per token per user per 10 minutes, queued via RabbitMQ
• Admin: Full collection refresh from the admin panel with progress tracking
• Dedup: Images are stored by content hash — identical images across tokens share one copy

Metadata & Licensing

The Metadata Override Layer

For every collection we support, the API returns a metadata override — a normalized metadata object that we build and serve, regardless of what the underlying contract exposes. This mirrors the four-tier image system: the contract's tokenURI is one possible input, but it is not the source of truth our API hands back.

This matters because many collections (Gunnies PFP included) never wired working on-chain metadata — their tokenURI is empty or returns a generic base record. The override layer fills that gap with consistent, indexer-friendly fields across all 49 collections.

Transferable (SBT) Flag

The top-level transferable boolean tells you whether a token is freely tradable (true) or soulbound/locked (false). It is promoted out of the trait list for easy filtering, and also kept inside metadata.attributes as a Transferable trait for backward compatibility.

"transferable": false   // soulbound / locked
"transferable": true    // freely tradable

For collections using a tiered-transfer model (e.g. Gunnies PFP: locked by default, unlockable per token), this flag reflects each token's current state.

Licensing (ERC-721L)

The license object exposes machine-readable usage rights following the ERC-721L licensing-aware NFT standard. It lets wallets, marketplaces, games, and AI agents reliably understand what a holder is permitted to do with the content — commercial use, derivatives, exclusivity, and so on.

"license": {
  "schema": "erc721l-metadata-v1",
  "rights_model": "base-plus-upgrade",
  "current_tier": 4,
  "current_name": "COMMERCIAL_DERIVS_NONEXCLUSIVE",
  "base_tier": 2,
  "upgraded_tier": 4,
  "terms_uri": "https://nft-data.pentagon.games/licenses/tier-4",
  "source": "override"
}

Canonical Tier Ladder (0–7)

For AI Agents

Treat the license tier as a permission boundary. Before generating, publishing, selling, or remixing content derived from an NFT, read license.current_tier and verify the action is allowed: display is fine for tiers 1–7, commercial use of unmodified art for tiers 2/4/5/6/7, derivatives for tiers 3–7 (commercial only for 4–7). If an action isn't permitted, refuse and surface the minimum tier required.

Collection License Provenance (official links)

Every collection also carries research-verified license provenance — the license's official name and the canonical URL published by the project itself (never a blog or aggregator). This is served on /api/v1/collections items and on the single-token endpoint, right alongside contractAddress:

"license": {
  "type": "commercial",          // cc0 | commercial | limited_commercial | personal
                                 // | proprietary | copyleft | custom | unknown
  "name": "Azuki IP License",    // human-readable license name
  "url": "https://www.azuki.com/license",   // official license/terms page (project's own domain)
  "notes": "Confirm Elementals/Beanz enumerated"  // one-line nuance, may be null
},
"officialUrl": "https://www.azuki.com"       // project main site

Storage

The storage field tells integrators not just what the image and metadata are, but where they live and how permanent they are — so you can reason about reliability and durability.

"storage": {
  "image": {
    "tier": "cached",            // cached | project | onchain | original
    "provider": "s3+cloudfront", // s3+cloudfront | gcs | arweave | ipfs | external
    "permanence": "managed",     // managed | arweave | ipfs | external
    "url": "https://images.pfpvault.com/3344/0xcdad.../5555000000553.webp",
    "archivalOriginal": "s3://pg-nft-images/originals/3344/0xcdad.../5555000000553.png"
  },
  "metadata": {
    "tier": "override",          // override | onchain-tokenuri | project-api
    "provider": "pg_nft_db",
    "tokenUri": "https://api.bcsh.xyz/metadata/5555000000553"
  }
}

Mutable NFTs & Refresh Patterns

Why Transfer-Based Sync Isn't Enough

The core sync engine (see How It Works) keys off ownership change — it reacts to Transfer events and re-checks ownerOf(). That is the right model for ownership, but a post-mint upgrade changes a token's state, not its owner. No transfer fires, so nothing re-indexes, and the cached metadata captured at first ingest goes stale. The fix is a separate refresh path, triggered by something other than a transfer.

The Two Mutation Types

Refresh Triggers

1. Project Callback (preferred)

After a qualifying action completes (an upgrade tx confirms, or a backend upgrade finalizes), the project's frontend or backend notifies us with just the contract and token id. We enqueue the refresh (RabbitMQ) and run the appropriate recipe for that collection. This is a push model — no polling, and no guessing which token changed, because the project tells us.

# Type A — on-chain upgrade (we re-verify on-chain before writing)
POST /api/v1/nft/notify_upgrade
Authorization: project app key (scoped to the collection)
{ "contract": "0x7a8a3236...3Ebc", "tokenId": "550", "chainId": 3344 }

# Type B — backend-only upgrade (we re-pull the project metadata endpoint)
POST /api/v1/nft/notify_refresh
Authorization: project app key (scoped to the collection)
{ "contract": "0x10d2d273...9a01", "tokenId": "232", "chainId": 3344 }

2. Tx-Scanning Cron (Type A backstop)

For Type A collections, an upgrade is a real on-chain write even when it emits no event (the call simply flips a storage flag). A project-specific cron scans the upgrade contract's transactions (not just Transfer logs), decodes the affected token id from calldata, and re-runs the on-chain read. This guarantees we catch upgrades even if a callback is never sent. Because it requires project-specific decoding logic and a read selector, each Type A collection submits its recipe for review and, once approved, gets a registered cron under a project-specific directory. Type B has no cron — there is nothing on-chain to scan.

3. User-Initiated Refresh

A best-effort, rate-limited self-serve path (POST /api/v1/nft/refresh/:contract/:tokenId, 1 per token per user per 10 min) lets a holder force a re-check from a project UI. It runs the same recipe as the callback. Useful as a fallback, but the project callback is preferred because it fires automatically at the exact moment state changes.

Refresh Recipe

Each mutable collection is described by a small recipe that the refresh worker reads to know how to re-derive state:

{
  "collection": "Gunnies PFP",
  "mutable": true,
  "type": "A",                       // A = on-chain read, B = project-api pull
  "refresh_source": "web3",          // web3 | project_api
  "read_fn": "isUpgraded(uint256)",  // Type A: on-chain read function
  "selector": "0x82f11a1a",          // Type A: function selector
  "maps_to_trait": "Transferable",   // how the read result is stored
  "api_url_template": null           // Type B: ".../{collection}/{id}"
}

Support & Contact