Critical Raw Minerals & ESG Compliance Oracle(x402)
# EV Battery Critical Minerals & Provenance Oracle (`minerals-oracle-x402`)
<div align="center">
[](https://www.npmjs.com/package/minerals-oracle-x402)
[](https://pypi.org/project/minerals-oracle-x402/)
[](https://minerals-oracle-x402-7qxtp3324q-du.a.run.app/dashboard)
<br/>
[](https://www.npmjs.com/package/minerals-oracle-x402)
[](https://pypi.org/project/minerals-oracle-x402/)
[](https://github.com/nohosa001-pixel/minerals-oracle-x402/actions/workflows/ci.yml)
[](https://github.com/nohosa001-pixel/minerals-oracle-x402/actions/workflows/npm-publish.yml)
[](https://github.com/nohosa001-pixel/minerals-oracle-x402)
[](contracts/verification/VERIFICATION_GUIDE.md)
[](mcp_tool_spec.json)
[](https://opensource.org/licenses/MIT)
</div>
> ๐ค **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`)
[](https://www.npmjs.com/package/minerals-oracle-x402)
[](https://www.npmjs.com/package/minerals-oracle-x402)
๐ **[npm ๊ณต์ ๋ ์ง์คํธ๋ฆฌ ๋ฐ๋ก๊ฐ๊ธฐ (npmjs.com/package/minerals-oracle-x402)](https://www.npmjs.com/package/minerals-oracle-x402)**
```bash
npm install minerals-oracle-x402
# or
pnpm add minerals-oracle-x402
# or
bun add minerals-oracle-x402
```
```typescript
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
```python
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
```python
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`:
```json
{
"mcpServers": {
"minerals-oracle": {
"command": "python",
"args": ["-m", "app.mcp_stdio"],
"env": { "ORACLE_API_KEY": "YOUR_AGENT_KEY" }
}
}
}
```
---
## ๐ 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:
```mermaid
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...`):
| Network | Smart Contract | Mainnet Deployed Address | Explorer Status |
| :--- | :--- | :--- | :---: |
| **Polygon Mainnet** (137) | `TradeFinanceSettlementEngine` | [`0x1dD725fB4860e1e9E00aA887F4bda5acD3789d10`](https://polygonscan.com/address/0x1dD725fB4860e1e9E00aA887F4bda5acD3789d10#code) | โ
**Deployed (Gas Paid)** |
| | `DynamicTradeEscrow` | [`0x3A863A2b1018B47FE79041FCDF56efEa3f8b978F`](https://polygonscan.com/address/0x3A863A2b1018B47FE79041FCDF56efEa3f8b978F#code) | โ
**Verified (exact_match)** |
| | `MineralTradeEscrow` | [`0xd1F37196A1fe73Caa89ce7f4a58D6Fe49FD47655`](https://polygonscan.com/address/0xd1F37196A1fe73Caa89ce7f4a58D6Fe49FD47655#code) | โ
**Active** |
| | `MineralsOracleConsumer` | [`0x5F565115441188b5dCa06539615Fc154BC7f3028`](https://polygonscan.com/address/0x5F565115441188b5dCa06539615Fc154BC7f3028#code) | โ
**Active** |
| | `AgentPaymentVault` | [`0xbFc79F55E410508aBCa2FF8ebA1120de4F209f68`](https://polygonscan.com/address/0xbFc79F55E410508aBCa2FF8ebA1120de4F209f68#code) | โ
**Active** |
| **Base Mainnet** (8453) | `TradeFinanceSettlementEngine` | [`0x9462587838fb8436C286AC9E04AAb6D42Eaf6D93`](https://basescan.org/address/0x9462587838fb8436C286AC9E04AAb6D42Eaf6D93#code) | โ
**Deployed (Gas Paid)** |
| | `DynamicTradeEscrow` | [`0x54786360Db4582AEC2435E216479FD4ff093CB80`](https://basescan.org/address/0x54786360Db4582AEC2435E216479FD4ff093CB80#code) | โ
**Verified (exact_match)** |
| | `MineralTradeEscrow` | [`0xbFc79F55E410508aBCa2FF8ebA1120de4F209f68`](https://basescan.org/address/0xbFc79F55E410508aBCa2FF8ebA1120de4F209f68#code) | โ
**Active** |
| | `MineralsOracleConsumer` | [`0xF0A781372cd7E32485603823390c791495140ca9`](https://basescan.org/address/0xF0A781372cd7E32485603823390c791495140ca9#code) | โ
**Active** |
| | `AgentPaymentVault` | [`0x8eB40eF1f032dd66CD54c6e1D0C29980C31d5E57`](https://basescan.org/address/0x8eB40eF1f032dd66CD54c6e1D0C29980C31d5E57#code) | โ
**Active** |
| **Arbitrum One** (42161) | `TradeFinanceSettlementEngine` | [`0x402E95B6aE9BBD26A227A1AE2aC7f52E14E1A314`](https://arbiscan.io/address/0x402E95B6aE9BBD26A227A1AE2aC7f52E14E1A314#code) | โ
**Deployed (Gas Paid)** |
| | `DynamicTradeEscrow` | [`0x54786360Db4582AEC2435E216479FD4ff093CB80`](https://arbiscan.io/address/0x54786360Db4582AEC2435E216479FD4ff093CB80#code) | โ
**Verified (exact_match)** |
| | `MineralTradeEscrow` | [`0x1884025dD7E510a4490533eC46A362fCb08D3822`](https://arbiscan.io/address/0x1884025dD7E510a4490533eC46A362fCb08D3822#code) | โ
**Active** |
| | `MineralsOracleConsumer` | [`0x75F36e1682f283feBfB683dD40e93785715cE404`](https://arbiscan.io/address/0x75F36e1682f283feBfB683dD40e93785715cE404#code) | โ
**Active** |
| | `AgentPaymentVault` | [`0xC089E5f72a7F5550Bb383C31B04Bf430a4E31372`](https://arbiscan.io/address/0xC089E5f72a7F5550Bb383C31B04Bf430a4E31372#code) | โ
**Active** |
| **Solana Mainnet** (501) | `TradeFinanceSettlementEngine` | `TrdFx402ZkR3M5vW9aK7nB1pQ2eC8sY6tU4jH7vL9mNp` | โ
**Anchor IDL Registered** |
| | `DynamicTradeEscrow` | `DynSxW8JCy6296toTYrdhJqnoxtMvf3CPmtSSFEyqNnz` | โ
**Anchor IDL Registered** |
| | `MineralTradeEscrow` | `AGR3W3R9pKxnuZGYrpaggfkbMKVrjoniLaGvi1voBFSC` | โ
**Active** |
| | `MineralsOracleConsumer` | `21ZR1QCyAbNrRLs1iWEkdbNsfCFdJcy6ip9R2JxDbkTL` | โ
**Active** |
| | `AgentPaymentVault` | `7oZ16YaazQzN6z5uA1nAZWD9oGUDXyvHwXGJLFYyWi3y` | โ
**Active** |
๐ **[Detailed Contract Verification & Multi-Chain Setup Guide (VERIFICATION_GUIDE.md)](contracts/verification/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
```mermaid
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`](app/static/index.html) served at `/dashboard`) provides an agent-dedicated compliance cockpit (Pure English RFC-compliant):
| Tab | Key Features |
| :--- | :--- |
| ๐ **NCM 811 Composite Master Passport** | Real-time IRA 30D eligibility, FTA value progress bar, EU Battery Passport approval status, Carbon Footprint gauge, on-chain Merkle Root & EIP-712 JSON terminal |
| ๐ฆ๐บ **Australian Lithium Observatory** | Hard-rock mine selection (Greenbushes, Pilgangoora, Mt Marion), ore feed vs LiOH yield calculation |
| ๐ฎ๐ฉ **Indonesian Nickel MHP Observatory** | IMIP/IWIP concession verification, ESDM SIMBARA tax receipt verification, captive coal power toggle |
| ๐จ๐ฉ **DRC Cobalt Hydroxide Observatory** | Kamoto KCC/Tenke concession check, CEEC barcode verification, ILO 138/182 child labor audit toggle |
#### 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:
```json
{
"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
```bash
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)
```bash
# Run full regression suite
pytest tests/
```
### 3. Launch Local Server & Web Observatory
```bash
# 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](http://localhost:8000/dashboard)
- **Interactive OpenAPI Documentation**: [http://localhost:8000/docs](http://localhost:8000/docs)
- **Model Context Protocol (MCP) Tools**: [http://localhost:8000/mcp/tools](http://localhost:8000/mcp/tools)
- **OpenAI-Compatible Model Registry**: [http://localhost:8000/v1/models](http://localhost:8000/v1/models) (Supports Cursor, AutoGen, LangChain)
- **Official EU 2023/1542 Battery Passport Sample**: [http://localhost:8000/sample-battery-passport.json](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](GLOBAL_BATTERY_MINERALS_COMPLIANCE_SPEC.md).
---
## ๐ License
MIT License. Copyright (c) 2026 Minerals Oracle x402 Project Contributors.
TDQS
Scored across 39 tools
Most tools are distinct (per-mineral verify_*_origin, A2A deal lifecycle, session management), but several boundaries blur: verify_mineral_lot_compliance overlaps conceptually with the specific verify_*_origin tools, verify_customs_clearance vs verify_electronic_bill_of_lading both anchor bills of lading, and get_agent_vault_balance vs get_agent_session_info both report balances. Descriptions mitigate these overlaps but an agent must read carefully to pick correctly.
The dominant convention is a clear verb_noun snake_case pattern (verify_*_origin, get_*, list_*, propose_*/dual_sign_*/reject_*). Minor deviations exist: minerals_submit_agent_feedback and minerals_list_evolution_proposals carry an odd namespace prefix, and eudr_satellite_mine_audit lacks a leading verb. Still highly readable and predictable overall.
39 tools is heavy for a single oracle server and spans at least five sub-domains (mineral verification, A2A trade deals, payments/sessions, logistics/tariffs, evolution feedback). Each cluster is reasonable on its own, but the combined surface likely exceeds what an agent can navigate without a routing layer.
Coverage is broad and coherent: origin verification across seven-plus minerals, composite battery passport, eBL/customs, tariffs/freight/route optimization, ZK proofs, and a full A2A deal lifecycle plus session/onboarding flow. Minor gaps remain (e.g., no update/revoke or listing of issued verification proofs, and some minerals like graphite or manganese lack dedicated verifiers), but no dead ends in the core workflows.