Critical Raw Minerals & ESG Compliance Oracle(x402)
README.md
# 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 **100% verified (Green Checkmark)** with open-source Solidity code and ABIs:
| Network | Smart Contract | Mainnet Deployed Address | Explorer Status |
| :--- | :--- | :--- | :---: |
| **Polygon Mainnet** (137) | `MineralTradeEscrow` | [`0x1270ddebad0ca90070342336a581eaACBA2060Ab`](https://polygonscan.com/address/0x1270ddebad0ca90070342336a581eaACBA2060Ab#code) | โ
**Verified** |
| | `AgentPaymentVault` | [`0xb44Bc2Acdd156cE08b549A00a3102e4B01276654`](https://polygonscan.com/address/0xb44Bc2Acdd156cE08b549A00a3102e4B01276654#code) | โ
**Verified** |
| | `MineralsOracleConsumer` | [`0x835d01534a5D2e63D52636Fafb1019f889d1E66B`](https://polygonscan.com/address/0x835d01534a5D2e63D52636Fafb1019f889d1E66B#code) | โ
**Verified** |
| **Base Mainnet** (8453) | `MineralTradeEscrow` | [`0xfCf3BF5fB5858db9aE81bE458B39b0032fc0C638`](https://basescan.org/address/0xfCf3BF5fB5858db9aE81bE458B39b0032fc0C638#code) | โ
**Verified** |
| | `AgentPaymentVault` | [`0x8ACafCEce0B1BFE140e75614b90FD1307b6f389d`](https://basescan.org/address/0x8ACafCEce0B1BFE140e75614b90FD1307b6f389d#code) | โ
**Verified** |
| | `MineralsOracleConsumer` | [`0xe43a9C368808B2dfF139D27789C40A3C8F2282cF`](https://basescan.org/address/0xe43a9C368808B2dfF139D27789C40A3C8F2282cF#code) | โ
**Verified** |
| **Arbitrum One** (42161) | `MineralTradeEscrow` | [`0xfCf3BF5fB5858db9aE81bE458B39b0032fc0C638`](https://arbiscan.io/address/0xfCf3BF5fB5858db9aE81bE458B39b0032fc0C638#code) | โ
**Verified** |
| | `AgentPaymentVault` | [`0x8ACafCEce0B1BFE140e75614b90FD1307b6f389d`](https://arbiscan.io/address/0x8ACafCEce0B1BFE140e75614b90FD1307b6f389d#code) | โ
**Verified** |
| | `MineralsOracleConsumer` | [`0xe43a9C368808B2dfF139D27789C40A3C8F2282cF`](https://arbiscan.io/address/0xe43a9C368808B2dfF139D27789C40A3C8F2282cF#code) | โ
**Verified** |
### 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**: `0xA185B43fDD19619f99952AAed6eabf1029bF36a1`
- **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 (278 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)
---
## ๐ 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
B3.3/5.0
Scored across 38 tools
Disambiguation4/5
Most tools target clearly distinct resources or lifecycle stages, especially the A2A trade-deal and mineral-specific origin verification tools. However, the generic `verify_mineral_lot_compliance` can overlap conceptually with the mineral-specific `verify_*_origin` tools, and the account/session/vault/payment tools have related scopes that may cause some hesitation. Descriptions generally help clarify boundaries.
Naming Consistency4/5
The set primarily follows a snake_case verb_noun pattern (`verify_*`, `get_*`, `list_*`, `propose_*`, `cancel_*`), which is easy to scan. Minor deviations exist, such as `eudr_satellite_mine_audit` and the `minerals_*` prefix on feedback/evolution tools, but these remain readable and not chaotic.
Tool Count3/5
At 38 tools, the surface is heavy and likely overwhelming for many agent workflows. The domain is broadโcompliance verification, trade deals, logistics, payments, and agent sessionsโso many tools are individually justified, but consolidation is still possible for some related operations. It sits at the borderline of being too large.
Completeness4/5
The server covers a wide compliance and trade lifecycle: mineral origin verification, A2A deal proposal through cancellation, customs/eBL checks, tariffs, freight, and agent session management. Minor gaps remain, such as post-deal escrow release or settlement operations and explicit retrieval of generated ZK proof artifacts, but core workflows are well represented.
Maintenance
ActivityActive
ResponsivenessNo issues