# Critical Minerals & Battery Supply-Chain Compliance Oracle (LLM & Autonomous Agent Standard)

> **The Decentralized Micro-Oracle for Autonomous Trading, Critical Mineral Provenance, and Battery Passport Compliance on Polygon Network (Chain ID: 137).**
> Features real-time spot pricing, 7-pillar provenance audit, 12-trap regulatory defense, and EIP-712 cryptographic battery passports.
> Zero Subscriptions. Machine-to-Machine HTTP 402 Micropayments (0.005 ~ 0.50 USDC per verification).

---

## ⚡ 1-Click MCP Setup (Claude Desktop, Cursor & uvx)

```json
{
  "mcpServers": {
    "minerals-oracle-x402": {
      "command": "uvx",
      "args": ["minerals-oracle-x402"]
    }
  }
}
```

---

## 🧪 Free Tier Sandbox & Example Presets

- **Sandbox Free Trial**: First 2 queries per agent IP are completely FREE without wallet signature.
- **Example Presets**:
  - `mineral_type`: `"NICKEL_MHP"` (or `"LITHIUM_HYDROXIDE"`, `"COBALT_HYDROXIDE"`, `"NATURAL_GRAPHITE"`, `"NEODYMIUM_DYSPROSIUM"`)
  - `source_country`: `"IDN"` (or `"COD"`, `"CHL"`, `"ARG"`, `"AUS"`, `"BRA"`, `"CHN"`, `"ZAF"`)
  - `net_weight_metric_tons`: `500.0`
  - `target_yield_currency`: `"USDC"`

---

## ⚡ Quick Agent API Directory

- **A2A Propose Trade Deal**: `POST /api/v1/trade/deals/propose` (Cryptographically signed deal specification)
- **A2A Dual-Sign Deal**: `POST /api/v1/trade/deals/dual-sign` (Countersignature & Oracle attestation minting)
- **A2A Escrow Calldata**: `GET /api/v1/a2a/deals/{deal_id}/escrow-calldata` (EVM payload for Polygon/Base/Arbitrum)
- **Electronic Bill of Lading (eBL) Audit**: `POST /api/v1/trade/verify-ebl` (UNCITRAL MLETR, IMO & dark fleet check)
- **Trade Route Optimization**: `POST /api/v1/trade/optimize-route` (Chokepoint detour & landed cost arbitrage)
- **General Compliance Verification**: `POST /api/v1/oracle/compliance/verify` (Full 7-pillar audit + EIP-712 passport)
- **Australian Lithium Provenance**: `POST /api/v1/lithium/verify-origin` (WA MINEDEX, 7.5:1 yield, US IRA FEOC 25%)
- **Indonesian Nickel MHP Provenance**: `POST /api/v1/nickel/verify-origin` (SIMBARA NTPN, HPAL 31.34:1 yield, CBAM)
- **DRC Cobalt Hydroxide Provenance**: `POST /api/v1/cobalt/verify-origin` (CEEC barcode seals, EGC ASM segregation, ILO child labor)
- **South American Copper Provenance**: `POST /api/v1/copper/verify-origin` (Chilean COCHILCO, Codelco/Escondida geofencing, ASTM B115 Grade 1 Cu)
- **Mexican / Global Silver Provenance**: `POST /api/v1/silver/verify-origin` (Terronera/Fresnillo geofencing, N-Type TOPCon solar PV assay >=99.99%)
- **Compliance Engine Status**: `GET /api/v1/oracle/compliance/status` (Active 10-nation laws & 14-trap status)
- **Trade Jurisprudence Precedents**: `GET /api/v1/oracle/compliance/precedents` (WTO DS592, DS431, ICSID, US CIT)
- **Free Public Alpha Hook**: `GET /api/v1/oracle/alpha-signals` (Pollable 24/7 without authentication)
- **Direct 402 Challenge**: `GET /api/v1/oracle/challenge`
- **ROI & Cost Advantage**: `GET /api/v1/oracle/economics-roi` (Quantified proof of 99.89% savings vs Fastmarkets)
- **Instant Agent Onboarding**: `POST /api/v1/agent/onboard` (Zero-friction 0.05 USDC trial balance)
- **Google AP2 Manifest**: `GET /.well-known/ap2`
- **Agent Protocol Manifest**: `GET /.well-known/agent.json`
- **A2A Skills Manifest**: `GET /.well-known/a2a.json`
- **FastMCP Tool Definition**: `GET /mcp/tools`
- **Interactive OpenAPI Spec**: `GET /openapi.json`
- **Machine Sitemap**: `GET /sitemap.xml`

---

## 💎 Monitored Critical Minerals & Supply Chains

1. **Nickel (`NICKEL_MHP`)**: Indonesia UU 3/2020 SIMBARA & DHE 30% export forex verification.
2. **Lithium (`LITHIUM_HYDROXIDE` / `LITHIUM_CARBONATE`)**: Chile DGA water permit & Argentine Ley 26.639 periglacial compliance.
3. **Cobalt (`COBALT_HYDROXIDE`)**: DRC CEEC official tamper-evident barcode seal & RMI RMAP 3rd-party child labor audit.
4. **Copper (`COPPER_CATHODE`)**: Chilean Codelco / Escondida GIS geofencing, flotation mass-balance loss <=2.0%, H2SO4 acid deficit, COCHILCO clearance, ASTM B115 Grade 1 AI Datacenter HVDC spec.
5. **Silver (`SILVER_REFINED` / Solar Paste)**: Mexican Terronera/Fresnillo geofencing, electrolytic mass-balance loss <=2.0%, N-Type TOPCon solar PV grade (>=99.99% Ag), LBMA Good Delivery.
6. **Graphite (`NATURAL_GRAPHITE` / `SYNTHETIC_GRAPHITE`)**: China MOFCOM dual-use export control license verification.
7. **Rare Earths (`NEODYMIUM_DYSPROSIUM`)**: Permanent Magnet NdFeB PrNd/DyFe origin & WTO DS431 compliance.
8. **Manganese (`MANGANESE_SULFATE`)**: South Africa Transnet logistics corridor monitoring.

---

## 💳 How Autonomous Agents Pay via x402 Protocol

```http
Authorization: x402 <base64_encoded_payload>
```
Or use the instant pre-funded Vault key:
```http
X-Agent-Vault-Key: vault_key_...
```

---

## 🤖 Python Client Quickstart

```python
import httpx

base_url = "http://localhost:8000"

# 1. Zero-friction self-onboarding (Free trial key)
onboard_resp = httpx.post(f"{base_url}/api/v1/agent/onboard", json={"agent_name": "ComplianceAgent"}).json()
session_key = onboard_resp["session_key"]

# 2. Verify mineral lot compliance
audit_result = httpx.post(
    f"{base_url}/api/v1/oracle/compliance/verify",
    headers={"X-Agent-Vault-Key": session_key},
    json={
        "lot_id": "LOT-2026-NI-IDN-01",
        "mineral_type": "NICKEL_MHP",
        "source_country": "IDN",
        "net_weight_metric_tons": 500.0,
        "declared_purity_pct": 38.5,
        "mine_permits": {
            "mining_license_id": "IUP-OP-4491-SULAWESI",
            "mine_operator_name": "PT Sulawesi Nickel Resources",
            "simbara_ntpn": "NTPN-884219482109",
            "simbara_rkab_quota_id": "RKAB-2026-IDN-771",
            "dhe_forex_deposit_ref": "DHE-BI-992144-USD"
        },
        "ecological_spatial": {
            "latitude": -2.812451,
            "longitude": 121.341209,
            "eudr_deforestation_free": True,
            "periglacial_zone_violation": False,
            "indigenous_territory_encroachment": False,
            "tailing_dam_dce_certified": True,
            "aquifer_depletion_alert": False
        },
        "labor_human_rights": {
            "child_labor_free_certified": True,
            "rmi_rmap_audit_id": "RMI-RMAP-2026-0811",
            "forced_labor_uapa_cleared": True
        },
        "refining_mass_balance": {
            "refinery_id": "HPAL-IWIP-LINE-3",
            "feedstock_input_metric_tons": 4200.0,
            "refined_output_metric_tons": 500.0,
            "recovery_yield_pct": 91.4,
            "mass_balance_loss_discrepancy_pct": 1.12,
            "captive_coal_power_used": False
        },
        "maritime_logistics": {
            "vessel_imo_number": 9842144,
            "vessel_name": "MV Pacific Compliance",
            "cii_rating": "B",
            "ebl_document_hash": "0x7a8f3b91c4d2e5a6f7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0",
            "iso_17025_lab_coa_hash": "0x11223344556677889900aabbccddeeff11223344556677889900aabbccddeeff",
            "tml_moisture_safe": True
        },
        "geopolitical_sanctions": {
            "feoc_shareholding_pct": 14.5,
            "feoc_board_control_pct": 10.0,
            "contractual_operational_control": False,
            "ofac_sdn_sanctioned": False,
            "us_substantial_transformation_compliant": True
        }
    }
).json()

print("Compliance Verdict:", audit_result["verdict"]["is_fully_compliant"])
print("EIP-712 Battery Passport Signature:", audit_result["eip712_signature"])
```

---

## 📜 ERC-MilestoneTradeEscrow (A2A Physical Trade Settlement Rails)

Autonomous agents settling physical commodity contracts (lithium, nickel, cobalt, copper, silver) replace legacy bank Letters of Credit (L/C, $50,000+ fees) with deterministic 3-stage milestone escrows on EVM chains.

### ⛓️ Verified Mainnet Escrow Deployments
- **Polygon (137)**: `0x1270ddebad0ca90070342336a581eaACBA2060Ab`
- **Base (8453)**: `0xfCf3BF5fB5858db9aE81bE458B39b0032fc0C638`
- **Arbitrum (42161)**: `0xfCf3BF5fB5858db9aE81bE458B39b0032fc0C638`
- **Native USDC**: `0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359` (Polygon)

### 🚢 3-Stage Milestone Settlement Rules
1. **Stage 1 (30% Payout)**: Title Transfer & eBL Ingestion. Trigger: `deal.eblHash == verifiedEblHash`.
2. **Stage 2 (40% Payout)**: Mid-Transit Geofence Integrity. Trigger: Satellite AIS corridor ping.
3. **Stage 3 (30% Final)**: Port of Discharge (POD) customs clearance, lab assay certificate (SGS/ALS), and EU Battery Passport/CBAM clearance.

### ⚡ A2A Trade Escrow API Execution
```python
# 1. Propose Deal between Buyer & Seller AI Agents
deal = httpx.post(f"{base_url}/api/v1/trade/deals/propose", json={
    "deal_id": "DEAL-2026-LIT-001",
    "commodity": "LITHIUM_HYDROXIDE",
    "volume_tons": 500.0,
    "unit_price_usd_per_ton": 25000.0,
    "total_deal_value_usd": 12500000.0,
    "origin_country": "AUS",
    "destination_country": "USA",
    "ebl_document_id": "EBL-MAERSK-2026-LIT09",
    "buyer_agent_address": "0x2222222222222222222222222222222222222222",
    "seller_agent_address": "0x1111111111111111111111111111111111111111",
    "created_at_utc": "2026-09-25T12:00:00Z",
    "seller_signature": "0x..."
}).json()

deal_id = deal["deal_id"]

# 2. Dual-Sign Deal (EIP-712 binding)
signed_deal = httpx.post(f"{base_url}/api/v1/trade/deals/dual-sign", json={
    "deal_id": deal_id,
    "buyer_signature": "0x...",
    "buyer_agent_address": "0x2222222222222222222222222222222222222222"
}).json()

# 3. Retrieve Live Smart Contract Calldata for on-chain deposit
calldata_resp = httpx.get(f"{base_url}/api/v1/a2a/deals/{deal_id}/escrow-calldata?chain=polygon").json()
print("Escrow Contract:", calldata_resp["escrow_contract_address"])
print("Calldata Hex:", calldata_resp["calldata"]) # createEscrow(bytes32,address,uint256,bytes32,uint256) -> selector 0x1df04324
```

---

## 🛡️ Statutory Limitation of Liability & Legal Disclaimer
All oracle heuristics and escrow calldata are provided strictly **"AS-IS"** without merchantability warranty.
1. **Strict $0.50 USDC Cumulative Liability Cap**: Development and infrastructure liability is strictly hard-capped at $0.50 USDC.
2. **EIP-712 Disclaimer Binding**: Consent is mathematically bound on-chain via immutable `bytes32 disclaimerHash`.
3. **Non-Delegable Importer Due Diligence**: Importing agents retain sole, non-delegable responsibility for physical laboratory assay and customs clearance under applicable trade jurisprudence.
