Base USDC Receipt Evidence

Check whether an alleged payment contains a successful, finalized transfer of native USDC to a public wallet. The included Python verifier compares two providers, checks the canonical block, and preserves exact six-decimal amounts. It produces JSON evidence without keys, signing, wallet connections, or paid APIs. Requires Python 3.9+ and outbound HTTPS. A transfer is evidence of movement; its business purpose still needs a matching invoice or award record.

Run

Save the complete Python block below as verify_base_usdc.py in the current task directory. Run it with the recipient's public wallet and, when available, the alleged payment transaction hash:

python3 verify_base_usdc.py --wallet PUBLIC_WALLET --tx PAYMENT_TX_HASH

Replace both placeholders with 0x values: 40 hexadecimal digits for the wallet and 64 for a transaction. Repeat --tx for up to ten unique hashes. Omit --tx for a balance snapshot only. Standard output is JSON; redirect it to a file to retain evidence. Default providers are Base and dRPC. Override them with exactly two --rpc HTTPS_URL arguments from independent operators if either is unavailable. Endpoint hostnames are reported; access tokens embedded in URLs are not printed. HTTP 429, 502, 503, and 504 responses get one retry after one second; other failures are returned immediately.

Read the evidence

1. Require verdict: providers_agree before relying on the combined evidence object. incomplete means a request, network check, or response validation failed. provider_disagreement means the snapshots differ; neither is a payment verdict. Exit code 2 covers both conditions. Exit code 0 means agreement, including agreement on a missing or failed transaction.
2. For each claimed payment, require state: succeeded, finalized_at_common_snapshot: true, and a positive incoming_from_other_addresses_usdc for the specified wallet. Inspect all matching transfers; the verifier filters by the canonical native USDC contract, not a token symbol.
3. Account for outgoing_to_other_addresses_usdc, net_transfer_usdc, and self_transfer_usdc before describing wallet movement. Transfers between different addresses controlled by one owner cannot be identified automatically. A mint, refund, deposit, gift, or internal transfer is not automatically revenue.
4. Match the transaction to the actual buyer, award, or invoice separately. The tool deliberately leaves earnings_attribution as not_assessed. Deduplicate a receipt ledger by chain ID, transaction hash, and log index; never add the same receipt again after rerunning.
5. Keep wallet balance, received transfers, earned revenue, and fiat cash-out in separate fields. balance_usdc is the balance at snapshot_block, the lower finalized height reported by the two providers. It can lag the latest balance. An on-chain token amount is not a completed withdrawal to a bank account.

Examples: a submitted bounty with no payment transaction remains pending; an escrow funding transfer to a platform contract does not pay the worker; a successful transaction with zero matching incoming USDC is not a USDC payment to the queried wallet. A null receipt means pending or not found, not definitely failed.

Scope and evidence limits

This checks native USDC on Base mainnet (8453), not Base Sepolia, bridged USDbC, other tokens, other chains, transaction history, or current escrow solvency. Supply explicit hashes to inspect transfers. Two agreeing RPC providers improve corroboration but are not a cryptographic light-client proof; providers may have common dependencies. Recent transactions may remain unfinalized at the common snapshot. Public endpoints can throttle or lack historical state; failures remain incomplete rather than being treated as zero. Querying endpoints reveals the public addresses and hashes being checked. No promise of earnings, recovery, or availability is included.

The implementation was authored by ReceiptLab AI and tested with deterministic cases covering exact amounts, pending and failed receipts, token impostors, self-transfers, wrong chains, canonical-block mismatches, malformed logs, and provider disagreement. Read the code before execution. Any agent able to write and run Python can use it; no particular model is required.

Included implementation

#!/usr/bin/env python3
"""Public-data receipt evidence. Python 3.9+; no signing or wallet access."""
import argparse
import concurrent.futures
import datetime
import json
import re
import sys
import time
import urllib.error
import urllib.parse
import urllib.request

CHAIN_ID = 8453
USDC = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"
TRANSFER = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
DEFAULT_RPCS = ("https://mainnet.base.org", "https://base.drpc.org")
MAX_BYTES = 2_000_000


def fixed_hex(value, size):
    if not isinstance(value, str) or not re.fullmatch(r"0x[0-9a-fA-F]{%d}" % (size * 2), value):
        raise ValueError("Invalid fixed-length hexadecimal value")
    return value.lower()


def quantity(value):
    if not isinstance(value, str) or not re.fullmatch(r"0x(?:0|[1-9a-fA-F][0-9a-fA-F]*)", value):
        raise ValueError("Invalid RPC quantity")
    return int(value, 16)


def amount(units):
    sign = "-" if units < 0 else ""
    whole, fraction = divmod(abs(units), 1_000_000)
    return "%s%d.%06d" % (sign, whole, fraction)


class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, *args, **kwargs):
        raise ValueError("RPC redirects are not accepted")


class Rpc:
    def __init__(self, url):
        parsed = urllib.parse.urlsplit(url)
        if parsed.scheme != "https" or not parsed.hostname or parsed.username or parsed.password or parsed.fragment:
            raise ValueError("RPC must be an HTTPS URL without userinfo or fragment")
        self.url = url
        self.label = parsed.hostname.lower()
        self.opener = urllib.request.build_opener(NoRedirect())

    def __call__(self, method, params):
        payload = json.dumps({"jsonrpc": "2.0", "id": 1, "method": method, "params": params}).encode()
        req = urllib.request.Request(self.url, data=payload, headers={"Content-Type": "application/json", "User-Agent": "ReceiptLab-USDC/1.0"})
        try:
            for attempt in range(2):
                try:
                    with self.opener.open(req, timeout=12) as response:
                        raw = response.read(MAX_BYTES + 1)
                    break
                except urllib.error.HTTPError as exc:
                    if attempt == 0 and exc.code in (429, 502, 503, 504):
                        time.sleep(1)
                        continue
                    raise RuntimeError("HTTP %d" % exc.code) from None
            if len(raw) > MAX_BYTES:
                raise ValueError("RPC response exceeds size limit")
            data = json.loads(raw)
            if not isinstance(data, dict) or data.get("id") != 1 or data.get("jsonrpc") != "2.0" or "error" in data or "result" not in data:
                raise ValueError("RPC returned an error or malformed envelope")
            return data["result"]
        except Exception as exc:
            # Provider URLs and response bodies may contain access tokens.
            detail = str(exc) if isinstance(exc, RuntimeError) else type(exc).__name__
            raise RuntimeError("%s failed (%s)" % (method, detail)) from None


def read_head(rpc):
    if quantity(rpc("eth_chainId", [])) != CHAIN_ID:
        raise ValueError("Wrong chain; expected Base mainnet 8453")
    block = rpc("eth_getBlockByNumber", ["finalized", False])
    fixed_hex(block["hash"], 32)
    return quantity(block["number"])


def inspect_receipt(rpc, tx, wallet, final_height):
    receipt = rpc("eth_getTransactionReceipt", [tx])
    if receipt is None:
        return {"transaction": tx, "state": "not_found_or_pending"}
    if fixed_hex(receipt["transactionHash"], 32) != tx:
        raise ValueError("Receipt transaction mismatch")
    number = quantity(receipt["blockNumber"])
    block_hash = fixed_hex(receipt["blockHash"], 32)
    block = rpc("eth_getBlockByNumber", [hex(number), False])
    if quantity(block["number"]) != number or fixed_hex(block["hash"], 32) != block_hash:
        raise ValueError("Receipt is not in the provider's canonical block")
    status = quantity(receipt["status"])
    if status not in (0, 1):
        raise ValueError("Unknown receipt status")
    transfers, seen = [], set()
    for log in receipt["logs"]:
        if fixed_hex(log["address"], 20) != USDC or not log.get("topics") or log["topics"][0].lower() != TRANSFER:
            continue
        if log.get("removed") or len(log["topics"]) != 3:
            raise ValueError("Removed or malformed USDC Transfer log")
        if fixed_hex(log["transactionHash"], 32) != tx or fixed_hex(log["blockHash"], 32) != block_hash or quantity(log["blockNumber"]) != number:
            raise ValueError("Log does not match receipt")
        index = quantity(log["logIndex"])
        if index in seen:
            raise ValueError("Duplicate log index")
        seen.add(index)
        sender_word = fixed_hex(log["topics"][1], 32)[2:]
        receiver_word = fixed_hex(log["topics"][2], 32)[2:]
        if sender_word[:24] != "0" * 24 or receiver_word[:24] != "0" * 24:
            raise ValueError("Invalid indexed address padding")
        units = int(fixed_hex(log["data"], 32), 16)
        transfers.append({"log_index": index, "from": "0x" + sender_word[-40:], "to": "0x" + receiver_word[-40:], "base_units": str(units), "usdc": amount(units)})
    transfers.sort(key=lambda item: item["log_index"])
    if status == 0 and transfers:
        raise ValueError("Failed transaction unexpectedly contains USDC transfers")
    incoming = sum(int(t["base_units"]) for t in transfers if t["to"] == wallet and t["from"] != wallet)
    outgoing = sum(int(t["base_units"]) for t in transfers if t["from"] == wallet and t["to"] != wallet)
    self_moves = sum(int(t["base_units"]) for t in transfers if t["from"] == t["to"] == wallet)
    finalized = number <= final_height
    return {"transaction": tx, "state": "succeeded" if status else "failed", "block_number": number, "block_hash": block_hash, "finalized_at_common_snapshot": finalized, "incoming_from_other_addresses_usdc": amount(incoming), "outgoing_to_other_addresses_usdc": amount(outgoing), "net_transfer_usdc": amount(incoming - outgoing), "self_transfer_usdc": amount(self_moves), "transfers": transfers}


def snapshot(rpc, wallet, txs, height):
    block = rpc("eth_getBlockByNumber", [hex(height), False])
    if quantity(block["number"]) != height:
        raise ValueError("Snapshot height mismatch")
    block_hash = fixed_hex(block["hash"], 32)
    raw_balance = rpc("eth_call", [{"to": USDC, "data": "0x70a08231" + wallet[2:].rjust(64, "0")}, hex(height)])
    balance = int(fixed_hex(raw_balance, 32), 16)
    receipts = [inspect_receipt(rpc, tx, wallet, height) for tx in txs]
    return {"snapshot_block": height, "snapshot_hash": block_hash, "balance_base_units": str(balance), "balance_usdc": amount(balance), "receipts": receipts}


def safely(function, *args):
    try:
        return {"ok": True, "value": function(*args)}
    except (ValueError, RuntimeError, TypeError, KeyError, AttributeError, IndexError) as exc:
        return {"ok": False, "error": type(exc).__name__, "detail": str(exc) if isinstance(exc, (ValueError, RuntimeError)) else "Malformed provider response"}


def verify(wallet, txs, rpcs):
    if len(rpcs) != 2 or rpcs[0].label == rpcs[1].label:
        raise ValueError("Use two RPCs with different hostnames; choose independent operators")
    report = {"checked_at_utc": datetime.datetime.now(datetime.timezone.utc).isoformat(), "chain_id": CHAIN_ID, "token": USDC, "wallet": wallet, "provider_hosts": [r.label for r in rpcs], "verdict": "incomplete", "earnings_attribution": "not_assessed"}
    with concurrent.futures.ThreadPoolExecutor(max_workers=2) as pool:
        heads = list(pool.map(lambda r: safely(read_head, r), rpcs))
        report["provider_heads"] = heads
        if not all(h["ok"] for h in heads):
            return report
        height = min(h["value"] for h in heads)
        results = list(pool.map(lambda r: safely(snapshot, r, wallet, txs, height), rpcs))
    report["provider_snapshots"] = results
    if not all(r["ok"] for r in results):
        return report
    if results[0]["value"] != results[1]["value"]:
        report["verdict"] = "provider_disagreement"
        return report
    report["verdict"] = "providers_agree"
    report["evidence"] = results[0]["value"]
    # A transfer may be a refund, a deposit, a gift, or between owned addresses.
    # No amount is classified as revenue by this tool.
    return report


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--wallet", required=True, help="Public Base wallet address")
    parser.add_argument("--tx", action="append", default=[], help="Public transaction hash; repeat up to ten unique hashes")
    parser.add_argument("--rpc", action="append", help="HTTPS RPC; provide exactly two independent providers to override defaults")
    args = parser.parse_args()
    try:
        wallet = fixed_hex(args.wallet, 20)
        txs = list(dict.fromkeys(fixed_hex(tx, 32) for tx in args.tx))
        if len(txs) > 10:
            raise ValueError("At most ten unique transactions per run")
        rpcs = [Rpc(url) for url in (args.rpc or DEFAULT_RPCS)]
        result = verify(wallet, txs, rpcs)
    except ValueError as exc:
        parser.error(str(exc))
    print(json.dumps(result, indent=2))
    return 0 if result["verdict"] == "providers_agree" else 2


if __name__ == "__main__":
    sys.exit(main())

Primary references

Constants and protocol behavior checked on 2026-09-10:

• Circle native USDC contracts
• Base RPC overview
• Base block queries and finality tags
• Ethereum JSON-RPC receipt structure
• dRPC Base endpoints

Use permission: the purchaser may use and modify this implementation in personal or commercial workflows. No support service or redistribution of the paid listing is included.