Repository avatar
Monitoring
v1.5.0
active

nullclear

io.github.Nullclear-Protocol/nullclear

Zero-key EVM/Solana token forensics, tx simulator, calldata decoder & x402 escrow arbiter

Documentation

NullClear (nullclear.dev / nullclear.com)

Autonomous Non-Custodial Clearing & Reputation Protocol for x402 AI Agents

NullClear Arbiter MCP server – quality and maintenance score on Glama Listed on mcpservers.org x402 V1 & V2 ERC-8004 Agent #124595

NullClear Arbiter MCP server – Glama Card    NullClear Arbiter MCP server

NullClear eliminates payment risk in Agent-to-Agent (A2A) commerce. In standard HTTP 402 Payment Required flows, buyers are forced to pay before seeing whether an upstream agent hallucinates, crashes, or returns malformed data. NullClear introduces deferred non-custodial schema escrow: the buyer signs an EIP-3009 TransferWithAuthorization, the arbiter cryptographically validates the upstream agent's output against the buyer's schema contract, and only settles payment upon 100% verification. If the seller hallucinates or crashes, the authorization is voided and $0 is spent.


Architecture Overview

                      ┌──────────────────────────────────────────┐
                      │              BUYER AGENT                 │
                      │  (@nullclear/x402-arbiter client/fetch)   │
                      └─────────────────────┬────────────────────┘
                                            │
                          1. Target request │ (Intercepted 402)
                          2. EIP-3009 signed│ & Schema defined
                                            ▼
                      ┌──────────────────────────────────────────┐
                      │          NULLCLEAR ARBITER               │
                      │     (Cloudflare Worker + Hono)           │
                      │  - Sybil & Wash-Trade Engine             │
                      │  - Deterministic JSON Schema Validator   │
                      │  - EIP-712 Receipt Attestation           │
                      └─────────────┬──────────────┬─────────────┘
                                    │              │
                   3. Proxy Request │              │ 4. If Valid: Settle
                      with Escrow   │              │    If Invalid: VOID ($0)
                                    ▼              ▼
                     ┌──────────────────┐    ┌───────────────────┐
                     │   SELLER AGENT   │    │  EIP-3009 SETTLE  │
                     │  (HTTP 402 API)  │    │  (USDC on Base)   │
                     └──────────────────┘    └───────────────────┘

Monorepo Packages

PackagePathDescription
@nullclear/sharedpackages/sharedCore constants (Base Mainnet 8453, Sepolia 84532), ERC-8004 ABIs, x402 V2 types, EIP-3009 & KYA EIP-712 schemas.
@nullclear/worker-arbiterpackages/worker-arbiterCloudflare Worker Hono app handling deferred escrow clearing (/v1/clear), Sybil-resistant trust scores (/v1/score), KYA mandates (/v1/kya), and machine discovery honeypots (/llms.txt, /.well-known/*, /openapi.json).
@nullclear/x402-arbiterpackages/x402-arbiterAgent SDK providing createNullClearFetch with automatic HTTP 402 interception, EIP-3009 authorization signing, and Zod/JSON schema protection.
@nullclear/mcppackages/mcp-serverModel Context Protocol server (STDIO + Streamable HTTP at https://api.nullclear.dev/mcp) exposing 13 forensic, token-audit, clean-markdown, ERC-8004 reputation, KYA mandate, and x402 escrow tools to autonomous agents.
@nullclear/e2e-simulatorpackages/e2e-simulatorSelf-contained local simulator validating honest sellers, hallucination voids, 500 crash voids, and Sybil wash-trade detection.

Protocol Guarantees

  1. Non-Custodial Deferred Settlement: Buyer authorizations are held in escrow by the arbiter and only executed via EIP-3009 if the seller fulfills the schema contract. If the seller returns invalid schema or error codes, settlement is discarded.
  2. Sybil & Wash-Trade Detection: Analyzes counterparty concentration graph. If $>60%$ of transaction volume comes from a single buyer address across $\ge 3$ transactions, a wash-trading penalty is applied and the HIGH_COUNTERPARTY_CONCENTRATION_WASH_RISK flag is raised.
  3. KYA (Know Your Agent) Corporate Liability Mandates: Cryptographically ties an on-chain agent wallet to a legally registered corporate entity with defined liability coverage and per-transaction limits.
  4. Machine Discovery & Self-Describing Agents: Complete llms.txt, /.well-known/agent.json, /.well-known/x402.json, /.well-known/mcp.json, and OpenAPI 3.1.0 specifications.

What's New in v1.5.0

  • \$0.005 Micro-Tier Pricing & Standard /.well-known/x402 Resources: Aligned high-frequency Bazaar intelligence routes (/v1/bazaar/token-security, /v1/bazaar/wallet-risk, /v1/bazaar/verified-fetch) to \$0.005 USDC (5000 atomic), added KV-cached top-level "resources": [...] + machine-readable "guarantee" blocks on /.well-known/x402 and /.well-known/agent.json, served RFC 9728 /.well-known/oauth-protected-resource* and /.well-known/agent-registration.json, and prevented /llms.txt documentation false-positives in the Canary Auditor.
  • SDK & Shared v1.5.0 (@nullclear/shared, @nullclear/x402-arbiter): Added NullClearClient methods for x402 directory discovery (discoverEndpoints) and zero-key forensics (scanToken, inspectContract, decodeCalldata, simulateTx), Bazaar/Guarantee TypeScript schemas, and Base RPC failover constants.

What's New in v1.4.0

  • 13-Tool MCP Server & Streamable HTTP Endpoint (https://api.nullclear.dev/mcp): Disambiguated tool descriptions/schemas (scan_token_forensics, inspect_contract_abi_and_proxy, decode_calldata_or_failed_tx, simulate_transaction_preflight, read_url_clean_markdown, nullclear_discover_verified_x402_apis, nullclear_token_security_audit, nullclear_wallet_risk_score, nullclear_crypto_market_oracle, nullclear_safe_fetch, nullclear_escrow_x402_call, nullclear_check_reputation, nullclear_verify_kya_mandate) plus live /.well-known/glama.json, /.well-known/mcp.json, and /.well-known/mcp/server-card.json metadata.
  • PayAI settlement_pending & On-Chain EIP-3009 Recovery: Polls PayAI /settle pending settlements and verifies AuthorizationUsed / transaction receipts on Base Mainnet so confirmed payments return HTTP 200 and record clearings deterministically.
  • Bazaar Discovery & Paid Forensics: Emits resource + serverExtensions.bazaar metadata during facilitator settlement for PayAI/CDP Bazaar indexing, and enables $0.005 (5000 atomic USDC) EIP-3009 paid access on forensic endpoints alongside the 100 req/day free tier.

What's New in v1.1.0

  • 🛡️ Deep Deterministic Value Invariants: Extend basic JSON schema validation with field-level semantic invariants (gt, gte, lt, lte, eq, neq, minLength, maxLength, pattern, notContains, and maxStalenessSeconds). Stale data or numeric drift triggers instant authorization voiding ($0 charged).
  • 🛑 Canonical LLM Refusal Guard: Automatically inspects text and JSON responses for common LLM refusal boilerplate ("as an ai language model", "i cannot fulfill this request", "i am unable to assist", rate limits, and server error strings), treating refusal as non-delivery.
  • 🔀 Autonomous Multi-Seller Failover Routing: Callers can provide ordered fallback candidates (fallbacks: [{ targetUrl, sellerAgentId, paymentSignatureHeader }]). If the primary seller crashes or fails validation, the Arbiter voids the primary authorization and automatically routes to the secondary candidate without roundtripping back to the client agent.
  • 🔒 Outbound Spend Firewall & Anti-Abuse Guards: Protect buyer agent wallets with per-call caps (maxPerCallAtomic) and daily rolling spend policies (maxDailyWalletAtomic). Rejects self-clearing wash-loops (buyer address === seller address) and enforces minimum on-chain settlement floors.

Quickstart

Prerequisites

  • Node.js $\ge 20$
  • pnpm $\ge 9$

Install Dependencies

pnpm install

Build All Packages

pnpm build

Typecheck

pnpm typecheck

Run Tests

pnpm test

Run Live Autonomous E2E Simulator

pnpm demo
NPM
@nullclear/mcp
Install Command
npm install @nullclear/mcp

Remote