NFTPARS API v1

curl -s https://nftpars.app/api/v1/gifts/SnoopDogg-534281 \
  -H "Authorization: Bearer $NFTPARS_KEY"

{
    "ok": true,
    "data": {
        "slug": "SnoopDogg-534281",
        "owner": {
            "status": "VERIFIED",
            "freshness": "FRESH",
            "…": "…"
        }
    },
    "meta": {
        "request_id": "req_01jc…",
        "generated_at": "2026-11-04T10:00:00Z",
        "api_version": "v1",
        "freshness": "FRESH",
        "billing": {
            "charged_nano": 1000000,
            "reserved_nano": 1000000
        }
    }
}

import os, requests

API = "https://nftpars.app/api/v1"
headers = {"Authorization": f"Bearer {os.environ['NFTPARS_KEY']}"}

r = requests.get(f"{API}/gifts/SnoopDogg-534281", headers=headers, timeout=15)
body = r.json()
if not body["ok"]:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")

owner = body["data"]["owner"]
print(owner["status"], owner["freshness"])          # e.g. VERIFIED FRESH
if owner["status"] == "VERIFIED":
    print("current owner:", owner["telegram"]["id"])
elif owner["status"] == "HISTORICAL":
    print("last known (not current) owner:", owner["telegram"]["id"])
print("charged nanoton:", r.headers["X-NFTPARS-Charged-Nano"])

const API = "https://nftpars.app/api/v1";
const res = await fetch(`${API}/gifts/SnoopDogg-534281`, {
  headers: { Authorization: `Bearer ${process.env.NFTPARS_KEY}` },
});
const body = await res.json();
if (!body.ok) throw new Error(`${body.error.code}: ${body.error.message}`);

const { owner } = body.data;
console.log(owner.status, owner.freshness, body.meta.request_id);

<?php
$ch = curl_init('https://nftpars.app/api/v1/gifts/SnoopDogg-534281');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer '.getenv('NFTPARS_KEY')],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
]);
$body = json_decode(curl_exec($ch), true);
if (! $body['ok']) {
    throw new RuntimeException($body['error']['code'].': '.$body['error']['message']);
}
echo $body['data']['owner']['status'], PHP_EOL;

import time, uuid, requests

# Fresh mode: ask for a new observation. Use an Idempotency-Key so a retry never charges twice.
r = requests.get(f"{API}/gifts/SnoopDogg-534281/owner", params={"refresh": "true"},
                 headers={**headers, "Idempotency-Key": str(uuid.uuid4())}, timeout=15)
job = r.json()["data"]["job"]                       # HTTP 202

while job["status"] in ("QUEUED", "RUNNING"):
    time.sleep(2)
    job = requests.get(f"{API}/jobs/{job['id']}", headers=headers, timeout=15).json()["data"]

print(job["status"], job["billing"])                # only SUCCEEDED items are charged

const start = await fetch(`${API}/gifts/batch`, {
  method: "POST",
  headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({ mode: "fresh", slugs: ["SnoopDogg-534281", "PlushPepe-1234"] }),
});
let { data: { job } } = await start.json();          // 202 Accepted
while (["QUEUED", "RUNNING"].includes(job.status)) {
  await new Promise((r) => setTimeout(r, 2000));
  job = (await (await fetch(`${API}/jobs/${job.id}`, { headers: { Authorization: `Bearer ${KEY}` } })).json()).data;
}

# Two-hour temporary filter; the previous profile is restored automatically.
curl -s -X POST https://nftpars.app/api/v1/applications/$APP_ID/filters/temporary \
  -H "Authorization: Bearer $NFTPARS_KEY" -H "Content-Type: application/json" \
  -d '{"criteria": {"country": "RU", "gender": "female", "unknown": {"country": "exclude", "gender": "exclude"}},
       "duration_minutes": 120}'

# How many indexed owners actually have reliable (self-declared, consented) attributes?
curl -s "https://nftpars.app/api/v1/filters/coverage?country=RU&gender=female" -H "Authorization: Bearer $NFTPARS_KEY"

import hmac, hashlib, time

def verify(secret: str, raw_body: bytes, header: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    ts = int(parts["t"])
    if abs(time.time() - ts) > tolerance:            # replay protection
        return False
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

# Then de-duplicate on the X-NFTPARS-Delivery header (stable across retries).

import crypto from "node:crypto";

export function verify(secret, rawBody, header, tolerance = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const ts = Number(parts.t);
  if (Math.abs(Date.now() / 1000 - ts) > tolerance) return false;   // replay protection
  const expected = crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

<?php
function nftpars_verify(string $secret, string $rawBody, string $header, int $tolerance = 300): bool
{
    parse_str(str_replace(',', '&', $header), $parts);
    $ts = (int) ($parts['t'] ?? 0);
    if (abs(time() - $ts) > $tolerance) {
        return false; // replay protection
    }
    $expected = hash_hmac('sha256', $ts.'.'.$rawBody, $secret);

    return hash_equals($expected, (string) ($parts['v1'] ?? ''));
}

import Pusher from "pusher-js";

// 1) GET https://nftpars.app/api/v1/ws/config for host/key, 2) add channels via POST https://nftpars.app/api/v1/ws/subscriptions
const pusher = new Pusher(APP_KEY, {
  wsHost: "nftpars.app", wsPort: 443, forceTLS: true, enabledTransports: ["ws", "wss"], cluster: "",
  channelAuthorization: {
    endpoint: "https://nftpars.app/api/v1/ws/auth",
    headers: { Authorization: `Bearer ${KEY}` },   // server-side only — never ship keys to browsers
  },
});
pusher.subscribe("private-market.PlushPepe").bind("nftpars.event", (event) => console.log(event.type, event.data));
pusher.subscribe(`private-application.${APP_ID}.offers`).bind("nftpars.event", console.log); // filtered offer stream