Python API Client & KVChecker Response Fields

Why Python

Most of our public validator traffic is still PHP and the homepage drop-zone, but a lot of restock and Discord bots are Python. This post is the current mapping from https://api.unshared.shop/api/ onto KVChecker.com’s payload so you do not treat partner_checks as the same thing as ?action=info.

Quick check

from UnsharedApiWrapper import UnsharedApi

api = UnsharedApi()  # token not required for validate
result = api.validate_file("kv.bin")

if result.get("multi"):
    print(result.get("summary"))
elif result.get("success"):
    print(result.get("status"), result.get("serial"))
    sharing = result.get("sharing") or {}
    print("partner hit:", sharing.get("is_shared"), sharing.get("shared_partners"))
else:
    print(result.get("message") or result.get("error"))

Save the wrapper next to your script or rename the class file; the download is a single module named UnsharedApiWrapper.py.

KVChecker fields you should persist

• unbanned / status — live Xbox Live result. Unknown means KDC was unreachable; retry later, do not treat it as banned.
• console_serial vs parsed serial — we prefer the 12-digit API serial when KVChecker returns one.
• console_name, console_id — identity strings from the checker, not NAND dumps.
• partner_checks.{Name}.checked and .first_seen — per service.
• sharing.is_shared / shared_partners — rolled-up hits (a date means “seen on that network”).
• kvchecker.server_time, xbl_system_version, total_unique_keyvaults, partners.
• kvchecker.verify_link and signature — show these to customers; they prove the JSON was not edited in transit.

Two different “shared” flags

After validate, many integrations call GET ?action=info&id={serial}. That endpoint only knows UnsharedSHOP’s kv_api log (other site users who checked the same serial). A KV can be info.shared = false and still have sharing.is_shared = true because xbGuard or Nfinite had a first-seen date. Always display both.

info = api.check_serial(result["serial"])
internal = bool(info.get("shared"))
partners = (result.get("sharing") or {}).get("shared_partners") or {}
print("internal checks:", info.get("info", {}).get("amount"))
print("partner names:", list(partners.keys()))

Verify links

Single checks often include kvchecker.verify_link. Packs put one entry per KVChecker HTTP batch in kvchecker.verifications[]. Open those URLs on kvchecker.com — that is the same signed blob the homepage validator shows.

Errors worth retrying

• HTTP 5xx or invalid_json — transient.
• status: "Unknown" — Xbox Live side; wait and validate again.
• Invalid KV file size — not retryable; the blob is not 16,384 bytes and is not a ZIP of KVs.

Related: PHP docs, C# docs. Need help? Support.