EV Battery Critical Minerals & Provenance Oracle (minerals-oracle-x402)

🤖 100% Pure Autonomous Agent-Native (M2M Exclusive) Critical Minerals Supply-Chain & Bilateral Trade Oracle.
Built strictly for autonomous AI agents, multi-agent swarms, and algorithmic trading execution. Humans and fiat credit cards are strictly prohibited. All settlements execute machine-to-machine via Native USDC across Solana (501), Polygon (137), Base (8453), and Arbitrum One (42161), backed by cryptographic on-chain transaction receipt RPC verification, anti-replay guards, and EIP-712 Dual-Attestation bound to the Security Gate x402 and EU AI Act (Article 50).

⚡ 3-Line AI Agent Quickstart (Python · TypeScript · LangChain · CrewAI)

1. TypeScript / Node.js (minerals-oracle-x402)

👉 npm 공식 레지스트리 바로가기 (npmjs.com/package/minerals-oracle-x402)

npm install minerals-oracle-x402
# or
pnpm add minerals-oracle-x402
# or
bun add minerals-oracle-x402

import { MineralsOracleClient } from 'minerals-oracle-x402';

const client = new MineralsOracleClient();
const res = await client.verifyTungsten({
  batch_id: 'W-APT-2026-T01', tenement_id: 'SANGDONG',
  latitude: 37.150, longitude: 128.833, apt_wo3_grade_pct: 88.5
});
console.log(res.audit_verdict?.status, res.proof_hash); // 'FULLY_COMPLIANT' 0x...

2. Python / LangChain Tool

import httpx

client = httpx.Client(base_url="https://minerals-oracle-x402-7qxtp3324q-du.a.run.app")
verdict = client.post("/api/v1/tungsten/verify-origin", json={
    "batch_id": "W-APT-2026-T01", "tenement_id": "SANGDONG",
    "latitude": 37.150, "longitude": 128.833, "apt_wo3_grade_pct": 88.5
}).json()["audit_verdict"]
print(f"Sangdong NDAA Sec 848: {verdict['status']}")  # FULLY_COMPLIANT

3. CrewAI / AI Agent Swarm Tool Call

from crewai.tools import tool
import httpx

@tool("Verify Defense Mineral Provenance")
def audit_mineral(batch_id: str, tenement_id: str, lat: float, lon: float) -> str:
    """Verifies critical defense mineral origin against US NDAA Sec 848 and EU CRM regulations."""
    r = httpx.post("https://minerals-oracle-x402-7qxtp3324q-du.a.run.app/api/v1/tungsten/verify-origin",
                   json={"batch_id": batch_id, "tenement_id": tenement_id, "latitude": lat, "longitude": lon})
    return r.text

4. Claude Desktop / Cursor FastMCP (Model Context Protocol)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "minerals-oracle": {
      "command": "python",
      "args": ["-m", "app.mcp_stdio"],
      "env": { "ORACLE_API_KEY": "YOUR_AGENT_KEY" }
    }
  }
}

Related MCP server: hyperd-mcp

🌊 Harmonious Collaborator Architecture & Fluid Pipeline ("Like Flowing Water")

The entire oracle system is orchestrated by the Collaborator Mediator (app/collaborator_mediator.py), unifying 5 domain subsystems into a single event-driven fluid pipeline with microsecond latency and zero human friction:

flowchart TD
    subgraph Flow ["🌊 Harmonized Fluid Trade Lifecycle (POST /api/v1/trade/harmonize-flow)"]
        S1["🤝 Node 1: A2A Deal Engine<br/>Bilateral Spec Negotiation & Dual-Signature"]
        S2["🚢 Node 2: Maritime Logistics & eBL<br/>Chokepoint Routing, MLETR Verification, Landed Cost"]
        S3["🛰️ Node 3: Sentinel-1/2 SAR Radar<br/>EUDR Concession Screening (Cutoff: 2020-12-31)"]
        S4["⛓️ Node 4: Multi-Chain Escrow<br/>Polygon (137) / Base (8453) / Arbitrum (42161) / Solana (501)"]
        S5["⚡ Node 5: A.GRID Real-Time Clearing<br/>Zero-Polling Webhook Event Mesh & SSE Streaming"]

        S1 --> S2 --> S3 --> S4 --> S5
    end

    subgraph Architecture ["🏗️ Decomposed Modular Domain APIRouters"]
        R1["📦 routers/minerals.py<br/>Provenance, Passport, ZK Proof"]
        R2["🌐 routers/logistics.py<br/>Corridors, Tariffs, Customs, eBL"]
        R3["🤝 routers/a2a_trade.py<br/>Bilateral Deals, Vaults, SSE Stream"]
        R4["📊 routers/oracle_pricing.py<br/>Pyth Consensus, Spreads, Precedents"]
        R5["🤖 routers/mcp.py<br/>FastMCP Tooling & SSE Transport"]
    end

1. 5-Pillar End-to-End Fluid Lifecycle

• POST /api/v1/trade/harmonize-flow: Single-call orchestration that takes trade intent from bilateral inception to on-chain escrow readiness and clearing in $<10\text{ms}$.

• GET /api/v1/trade/events/stream: Real-time Server-Sent Events (SSE) broadcasting live deal events and milestone releases.

• GET /api/v1/trade/events/recent: High-performance in-memory circular buffer for autonomous bot state recovery.

2. Pure Autonomous Agent-Native Architecture (M2M Exclusive)

1. Zero Human Gateways (No KYC, No Credit Cards, No Passwords):

   • Autonomous self-serve onboarding (POST /api/v1/agent/onboard) instantly provisions an agent vault with free trial queries.

   • Authentication is strictly cryptographic via X-Agent-Vault-Key or EIP-712 wallet signatures.

2. A2A (Agent-to-Agent) Bilateral Contract & Negotiation Engine (app/a2a_deal_engine.py):

   • Machine-readable deal lifecycle: PROPOSED $\rightarrow$ DUAL_SIGNED_CONFIRMED $\rightarrow$ VERIFIED (or REJECTED / CANCELLED).

   • Electronic Bill of Lading (eBL) cryptographic digest binding, IMO vessel tracking, and real-time sanctions screening.

   • Hybrid 2-Track Settlement: Combines micro-metered oracle queries ($0.005 USDC) with automated 10% Gain-Share on realized logistics & tariff savings ($10,000 cap).

3. Multi-Chain Real-Time RPC Receipt Verification & Replay Defense (app/x402_verifier.py):

   • Queries live EVM nodes on Polygon, Base, and Arbitrum with a strict 3.0-second timeout bound.

   • Decodes native USDC Transfer events and enforces immutable replay attack caching (logs/redeemed_tx_hashes.json) with thread-safe atomic file replacement.

4. Agent Session Vault (app/agent_session_vault.py):

   • High-frequency trading agents can lock USDC once and execute dozens of queries gas-free at sub-millisecond latency.

   • Automatic refund of unused balances on session close with zero-reentrancy protection.

5. Security Gate x402 & ElizaOS Fail-Closed Integration (app/security_gate_client.py):

   • Zero-trust prompt injection pre-filtering, Agent FICO credit scoring, and EU AI Act Article 50 Dual-Attestations.

   • Enforces Fail-Closed safety when strict mode is active.

🌐 Deployed & Verified Multi-Chain Smart Contracts

All contracts are deployed on live mainnets and registered across Polygon (137), Base (8453), Arbitrum One (42161), and Solana (501) from canonical creator wallet 0x356ECeA957b85120fef8cF5D89b85Cb3d4c13D5b (Solana: 411ksMz9...):

👉 Detailed Contract Verification & Multi-Chain Setup Guide (VERIFICATION_GUIDE.md)

1. Composite EV Battery Master Passport Orchestrator (app/composite_battery_pipeline.py)

Synthesizes the 3 primary battery critical minerals into a unified cell/pack compliance attestation:

• Cathode Chemistries: NCM 811 (80% Ni, 10% Co, 10% Mn), NCM 622, NCM 523.

• US IRA 30D Critical Minerals $3,750 Tax Credit Formula: $$\text{Procurement Value} = (\text{Li Tons} \times $18,500) + (\text{Ni Tons} \times $17,000) + (\text{Co Tons} \times $32,000)$$ $$\text{FTA Qualifying Ratio} = \frac{\text{Value}{\text{AUS (FTA)}}}{\text{Value}{\text{Total}}} \times 100% \ge 50.0%$$

• Strict Zero-Tolerance FEOC Taint Propagation: If any mineral component carries $\ge 25%$ covered nation (China/Russia/Iran/North Korea) equity or operational control, the entire battery pack is disqualified (FLAG_COMPOSITE_FEOC_TAINT).

• EU Battery Regulation (2023/1542) & CBAM Scope 1-3 Carbon Footprint:

  • Captive coal power smelting in Indonesian HPAL triggers FLAG_EU_BATTERY_CBAM_SURCHARGE (+26.5 kg CO₂e/kWh penalty).

• Cryptographic Merkle Tree & Polygon EIP-712 Master Signature: $$\text{Merkle Root} = \text{0x} + \text{SHA256}(\text{Leaf}{\text{Li}} + \text{Leaf}{\text{Ni}} + \text{Leaf}_{\text{Co}})$$ Signs typed structured data binding battery_pack_id, chemistry, merkle_root, composite score, and legal disclaimer terms.

2. Dedicated Provenance Pipelines for Core Minerals

flowchart TD
    subgraph Mining["1. Global Extraction & Geofencing"]
        Li["🇦🇺 Australia (Greenbushes / Pilgangoora)<br/>WA MINEDEX GIS Geofencing"]
        Ni["🇮🇩 Indonesia (IMIP Morowali / IWIP)<br/>Sulawesi/Halmahera Geofencing"]
        Co["🇨🇩 DRC (Kamoto KCC / Tenke / Mutanda)<br/>Katanga Copperbelt Geofencing"]
    end

    subgraph Processing["2. Stoichiometric Mass Balance & Traps"]
        LiProc["Spodumene to LiOH (7.5:1 Yield)<br/>Anti-Transshipment Geofencing"]
        NiProc["Limonite to MHP (31.34:1 Yield)<br/>ESDM SIMBARA NTPN Tax Clear<br/>EU CBAM Coal Smelting Audit"]
        CoProc["Heterogenite to Hydroxide (23.53:1 Yield)<br/>CEEC Barcode Seal Verification<br/>ILO 138/182 Zero Child Labor Audit"]
    end

    subgraph Composite["3. Composite Battery Orchestrator"]
        Master["NCM 811 Pack Synthesis<br/>IRA FTA Value Ratio (>= 50%)<br/>FEOC Taint Propagation (< 25%)<br/>EU Cradle-to-Gate Carbon Footprint"]
    end

    subgraph Attestation["4. Cryptographic Proof & Settlement"]
        Merkle["Merkle Tree Synthesis<br/>sha256(Leaf_Li + Leaf_Ni + Leaf_Co)"]
        Onchain["Polygon EIP-712 Master Signature<br/>x402 0.10 USDC Gasless Settlement"]
    end

    Li --> LiProc --> Master
    Ni --> NiProc --> Master
    Co --> CoProc --> Master
    Master --> Merkle --> Onchain

🇦🇺 Australian Spodumene Lithium Pipeline (app/lithium_pipeline.py)

• GIS Geofencing: Validates WA DMIRS MINEDEX tenement boundaries (e.g. Greenbushes M01/03, Pilgangoora M45/1256).

• Stoichiometric Mass Balance: Enforces strict theoretical yield ratio ($7.5 \pm 0.8\text{t}$ Spodumene concentrate $\rightarrow$ $1.0\text{t}$ Battery-Grade LiOH·H₂O).

• Defenses: Defends against Trap 13 (Chinese transshipment relabeling) and Trap 14 (non-linear recovery exaggeration).

🇮🇩 Indonesian Nickel MHP Pipeline (app/nickel_pipeline.py)

• Concession Geofencing: Monitors Central Sulawesi (IMIP Morowali) and North Maluku (IWIP Weda Bay) mining polygons.

• Fiscal Verification: Validates Ministry of Energy (ESDM) SIMBARA NTPN tax receipt codes and Bank Indonesia 30% forex export deposits (DHE BI).

• EU CBAM & Carbon Duty: Detects captive coal power plant usage and flags European Carbon Border Adjustment liabilities.

🇨🇩 DRC Cobalt Hydroxide Pipeline (app/cobalt_pipeline.py)

• Artisanal Segregation (Trap 1): Blocks uncertified artisanal mining (ASM) co-mingling via Entreprise Générale du Cobalt (EGC) custody validation.

• CEEC Security Seals: Cryptographically authenticates Centre d'Expertise (CEEC) tamper-proof barcode export seals.

• ILO Human Rights Diligence: Enforces mandatory independent audits for ILO Convention 138 (Minimum Age) and 182 (Worst Forms of Child Labor).

🇨🇱 Chilean Copper Cathode Pipeline (app/copper_pipeline.py)

• Concession Geofencing: Monitors major porphyry operations (Codelco Chuquicamata, El Teniente, Andina, BHP Escondida, Antofagasta Los Pelambres, Cerro Verde).

• Smelter Acid Balance (Trap 16): Validates sulfuric acid ($H_2SO_4$) reagent supply balance ($\le 5.0%$ deficit tolerance).

• Grid & Purity Standard: Certifies ASTM B115 Grade 1 electrolytic cathode purity ($\ge 99.9935%$) for AI datacenter HVDC power grids and COCHILCO export clearances.

🇲🇽 Mexican Silver Doré Pipeline (app/silver_pipeline.py)

• Concession Geofencing: Monitors high-grade silver operations (Endeavour Silver Terronera, Fresnillo, Antamina, Uchucchacua, Los Pelambres).

• N-Type TOPCon Solar Standard (Trap 16): Enforces ultra-pure $\ge 99.99%$ silver powder certification for next-gen solar PV metallization paste.

• Security & LBMA Assurance: Defends against cartel-tainted artisanal extraction and validates LBMA Good Delivery refiner accreditation.

🧲 Western Rare Earths & MOFCOM 0.1% Defense (app/rare_earths_pipeline.py)

• Non-China Geofencing: Validates primary Western NdPr producers (Lynas Mt Weld, MP Materials Mountain Pass, Vital Nechalacho, Pensana Longonjo).

• China MOFCOM Notice 61 '0.1% Rule' (D-35 Nov 10 Rule): Enforces strict $<0.100%$ PRC input ratio threshold to prevent extraterritorial export embargoes.

• High-Purity & Radiation Safety: Certifies $\ge 99.5%$ NdPr oxide assay purity and verifies Th+U radionuclide limits ($\le 500\text{ ppm}$).

🛡️ Western Tungsten & Defense NDAA Pipeline (app/tungsten_pipeline.py)

• Western Geofencing: Validates key deposits (NATC Cantung, American Tungsten IMA Project, Almonty Panasqueira, Sangdong).

• NDAA Sec 848 Defense Procurement: Certifies non-covered nation origin for US Department of Defense and semiconductor fabrication.

• APT Grade Standard: Verifies ASTM B783/ISO 10386 Ammonium Paratungstate grade ($\text{WO}_3 \ge 88.5%$) and 3TG conflict-free status.

♻️ Recycled Battery Black Mass Pipeline (app/black_mass_pipeline.py)

• US BIS Export License Enforcement: Validates Department of Commerce export authorizations (ABTC, Redwood Materials, Li-Cycle, BASF).

• EU Battery Reg 2023/1542: Verifies recycled mass content ratio ($\ge 85.0%$) and hazardous fluorine residue safety ($\le 500\text{ ppm}$).

2.5 Advanced 2026/2027 Regulatory, Logistics & ZK Privacy Upgrades

1. EU CBAM Statutory Mark-up Penalty Engine (app/regulatory_advanced_engine.py):

   • Calculates mandatory statutory default mark-up surcharges: 2026: +10%, 2027: +20%, 2028: +30%.

   • Quantifies exact EUR liability and immediate savings achieved with 3rd-party Scope 1/2 verified reports.

2. EU Industrial Accelerator Act (IAA) & W3C Battery Passport VC (app/regulatory_advanced_engine.py):

   • Evaluates $\ge 70%$ EU domestic content and $\ge 40%$ green steel content for clean vehicle subsidies.

   • Issues W3C-standard JSON-LD Digital Product Passport (DPP) Verifiable Credentials with on-chain ECDSA signatures.

3. Logistics Oracle Bridge (app/logistics_bridge.py):

   • Anchors multimodal Bill of Lading (B/L) and container numbers to mineral concessions.

   • Evaluates Port-of-Loading (POL) to Port-of-Discharge (POD) maritime speed/transit plausibility and inland mine-to-port spatial distance.

   • Issues Customs Clearance Proof Bundles for accelerated green-channel port clearance.

4. Pyth Dynamic Escrow Smart Contract (contracts/DynamicTradeEscrow.sol):

   • Dynamic real-time LTV mark-to-market valuation via Pyth price feeds with automated margin-call protection.

   • Tripartite conditional settlement: Oracle Proof Hash + Carrier B/L Arrival + Independent Laboratory Assay.

5. Zero-Knowledge Privacy Compliance Prover (app/zk_compliance_prover.py):

   • Shields exact mine coordinates, supplier IDs, and unit production costs.

   • Emits Groth16/Plonk zero-knowledge proofs mathematically proving concession Merkle inclusion and China origin $< 0.1%$.

3. Autonomous Agent Operations Terminal & Telemetry HUD

The built-in M2M console (app/static/index.html served at /dashboard) provides an agent-dedicated compliance cockpit (Pure English RFC-compliant):

One-Click Real-World Scenario Presets

• ✅ Clean Baseline (clean): Australia Greenbushes + Indonesia Clean IMIP + DRC Kamoto KCC $\rightarrow$ IRA Eligible ($3,750), EU Passport Approved, Low Carbon (51.5 kg CO₂e/kWh).

• ⚠️ FEOC Taint Trap (feoc): Injects 80% Chinese state ownership into DRC Cobalt $\rightarrow$ Entire battery pack disqualified under FEOC 25% threshold.

• ⚠️ Captive Coal CBAM Trap (cbam): Injects captive coal power smelting in Indonesia $\rightarrow$ EU CBAM carbon tariff liabilities triggered.

• ❌ Child Labor Trap (child): Injects uncertified artisanal pit ore in DRC $\rightarrow$ EU Battery Passport immediate rejection.

• 🚨 Trap 15 Tech Defense (trap15): Evaluates Chinese Mineral Resources Law extraterritorial licensing taint ($>50%$ SX tech dependency without MOFCOM clearance).

• ⚡ Copper HVDC Grid Ready (copper): Codelco Chuquicamata copper cathode audit, $H_2SO_4$ acid balance, and ASTM B115 Grade 1 HVDC power grid certification.

• ☀️ Silver TOPCon Solar PV (silver): Endeavour Silver Terronera doré audit, LBMA Good Delivery, and N-Type TOPCon $\ge 99.99%$ solar paste verification.

🤖 Model Context Protocol (FastMCP) Tools

Integrates natively with Claude Desktop, Cursor, Gemini, and autonomous AI agents:

{
  "mcpServers": {
    "minerals-oracle-x402": {
      "command": "python",
      "args": ["-m", "app.mcp_stdio"],
      "env": {
        "ORACLE_API_KEY": "YOUR_AGENT_KEY"
      }
    }
  }
}

Supported MCP Tools

1. verify_composite_battery_passport: Evaluates end-to-end NCM EV battery packs and generates Master Merkle EIP-712 attestations.

2. verify_lithium_origin: Verifies Australian hard-rock spodumene extraction and conversion.

3. verify_nickel_origin: Verifies Indonesian laterite limonite HPAL MHP provenance and SIMBARA tax clearance.

4. verify_cobalt_origin: Verifies DRC Katanga heterogenite cobalt hydroxide provenance, CEEC seals, and child labor audits.

5. verify_copper_origin: Verifies Chilean/South American copper cathode provenance, COCHILCO quotas, H2SO4 acid balance, and ASTM B115 HVDC compliance.

6. verify_silver_origin: Verifies Mexican/South American silver doré provenance, LBMA certification, N-Type TOPCon solar PV 99.99% purity, and cartel defense.

7. verify_mineral_compliance: Legacy 7-pillar compliance audit engine for individual mineral lots.

8. minerals_submit_agent_feedback: Zero-fee protocol feedback submission for autonomous agent evolution.

💳 Autonomous x402 Web3 Settlement on Polygon

All M2M API invocations support micro-payments in USDC on Polygon (Chain ID 137):

• Composite Battery Master Verification: 0.10 USDC (PricingTier.STANDARD)

• Dedicated Mineral Lot Verification: 0.05 USDC (PricingTier.LIGHT)

• Polygon USDC Address: 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359

• Treasury Recipient: 0x356ECeA957b85120fef8cF5D89b85Cb3d4c13D5b

• Agent Vault Fast-Path: Zero-latency verification via pre-funded X-Agent-Vault-Key headers.

🚀 Quick Start & Local Execution

1. Clone & Install Dependencies

git clone https://github.com/nohosa001-pixel/minerals-oracle-x402.git
cd minerals-oracle-x402

python -m venv .venv
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

pip install -e .

2. Run Tests (424 Automated Tests - 100% Passing)

# Run full regression suite
pytest tests/

3. Launch Local Server & Web Observatory

# Option A: Built-in CLI runner
minerals-oracle-x402

# Option B: Uvicorn development server
uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload

Navigate to:

• Autonomous Agent Observatory Console: http://localhost:8000/dashboard

• Interactive OpenAPI Documentation: http://localhost:8000/docs

• Model Context Protocol (MCP) Tools: http://localhost:8000/mcp/tools

• OpenAI-Compatible Model Registry: http://localhost:8000/v1/models (Supports Cursor, AutoGen, LangChain)

• Official EU 2023/1542 Battery Passport Sample: http://localhost:8000/sample-battery-passport.json

📜 Full Technical Specifications

For full mathematical formulations, threshold constants, legal citations, and EIP-712 type declarations, consult the Global Battery Minerals Compliance Specification v2.4.0.

📄 License

MIT License. Copyright (c) 2026 Minerals Oracle x402 Project Contributors.