Критические сырьевые минералы и оракул городской добычи (minerals-oracle-x402)

Высокопроизводительный детерминированный микросервис-оракул, предназначенный для автономной торговли, цепочек поставок и агентов RWA (реальный мировой актив). Предоставляет котировки спот-цен в реальном времени, арбитражные спреды между биржами COMEX/LME и эталонные оценки доходности лома для городской добычи критически важных сырьевых физических товаров.

⚡ Ключевые особенности

1. Нормализованные ценовые каналы критических сырьевых товаров:

   • Серебро (Ag): спот LBMA и COMEX в USD/troy_oz, USD/g, USD/kg.

   • Платина (Pt): спот LPPM и NYMEX в USD/troy_oz, USD/g.

   • Медь (Cu): катод Grade A LME и COMEX в USD/mt, USD/lb, USD/kg.

   • Литий (Li): аккумуляторный сорт 99.5% $\text{Li}_2\text{CO}_3$ / $\text{LiOH}$ в USD/mt, USD/kg.

   • Редкоземельные металлы (NdDy): композит неодим-диспрозий ($\text{PrNd}/\text{DyFe}$) магнитотвердого сорта в USD/kg.

2. Локационный арбитраж и базисные спреды:

   • Расчет арбитража меди COMEX против LME с учетом трансокеанского фрахта и импортных пошлин.

   • Спред серебра COMEX против LBMA Loco London.

   • Премия/дисконт лития SMM Внутренний Китай против Fastmarkets CIF Роттердам.

   • Спред платины NYMEX против LPPM.

3. Движок оценки городской добычи и циркулярной экономики:

   • EV_BATTERY_BLACK_MASS: гидрометаллургическое извлечение $\text{Li}$, $\text{Ni}$, $\text{Co}$ и $\text{Mn}$ с оплачиваемыми выходами извлечения и платой за переработку (TC/RC).

   • AUTO_CATALYST_CERAMIC: извлечение PGM ($\text{Pt}$, $\text{Pd}$, $\text{Rh}$) из отработанных каталитических нейтрализаторов по анализам керамических монолитов.

   • E_WASTE_HIGH_GRADE_PCB: извлечение драгоценных и основных металлов ($\text{Au}$, $\text{Ag}$, $\text{Cu}$) из измельченного сырья печатных плат.

   • WIND_EV_PERMANENT_MAGNETS: переработка лома NdFeB для получения раздельных оксидов редкоземельных элементов ($\text{Nd}$, $\text{Dy}$, $\text{Pr}$).

4. Монетизация Web3 через x402 на Base:

   • Обеспечивает микроплатежи (0.005 USDC за запрос) через HTTP 402 challenge-response на Base (Chain ID 8453).

   • Нативный токен Base USDC: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.

   • Поддерживает криптографические подписи EIP-712/EIP-191 и проверку фасилитатора.

5. Нативная поддержка мультиагентных стандартов:

   • Google AP2 (/.well-known/ap2): манифест Agent Protocol v2.

   • Model Context Protocol (MCP): определения схем инструментов (mcp_tool_spec.json) и диспетчер /mcp/invoke.

   • OpenAPI / Swagger (/docs): стандартная машиночитаемая и интерактивная документация API.

Related MCP server: hyperd-mcp

📁 Структура репозитория

minerals-oracle-x402/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI application, routing & MCP endpoints
│   ├── feed_engine.py       # Deterministic commodity pricing, spread & scrap engine
│   ├── x402_verifier.py     # HTTP 402 challenge & EIP-712 payment verifier
│   └── schemas.py           # Pydantic data contracts & schemas
├── tests/
│   ├── __init__.py
│   └── test_client.py       # Autonomous agent payment test suite
├── .well-known/
│   └── ap2.json             # Google Agent Protocol AP2 manifest
├── mcp_tool_spec.json       # FastMCP tool definition for LLM agents
├── Dockerfile               # Ultra-lightweight multi-stage container
├── requirements.txt         # Python dependencies
└── README.md                # Documentation & quickstart

🚀 Быстрый старт

1. Локальная настройка

# Clone and enter directory
cd minerals-oracle-x402

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run development server
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Интерактивная документация будет доступна по адресу http://localhost:8000/docs.

2. Запуск через Docker

# Build lightweight container
docker build -t minerals-oracle-x402 .

# Run container
docker run -p 8000:8000 minerals-oracle-x402

💳 Спецификация платежного потока x402

sequenceDiagram
    autonumber
    actor Agent as Autonomous AI Agent
    participant Oracle as minerals-oracle-x402
    participant Base as Base Network (USDC)

    Agent->>Oracle: GET /api/v1/oracle/prices
    Oracle-->>Agent: HTTP 402 Payment Required<br/>(Nonce, Price: 0.005 USDC, Base Chain ID: 8453)
    Note over Agent: Agent signs payment challenge<br/>using private key (EIP-712/EIP-191)
    Agent->>Oracle: GET /api/v1/oracle/prices<br/>Header: Authorization: x402 <base64_payload>
    Oracle->>Oracle: Verify signature / Facilitator settle
    Oracle-->>Agent: HTTP 200 OK<br/>Certified Oracle Feeds & Attestation Hashes

Формат заголовка авторизации платежа

Authorization: x402 eyJub25jZSI6ICIxYTIz...IiwgInNpZ25hdHVyZSI6ICIweDk5...In0=

Где декодированный JSON-полезная нагрузка содержит:

{
  "nonce": "7f8b92c4a90184b2ef019a823b102938",
  "signature": "0x...",
  "signer": "0xYourAgentWalletAddress"
}

🤖 Интеграция MCP (Model Context Protocol)

Для использования с агентами Claude Desktop, Cursor, Gemini или Antigravity загрузите mcp_tool_spec.json.

Доступные инструменты:

1. get_mineral_prices: получить все текущие спот-цены и конвертации единиц.

2. get_arbitrage_spreads: получить базисные спреды и маржу COMEX/LME/SMM.

3. calculate_urban_mining_value: рассчитать выходы извлечения для партий EV Black Mass, автокатализаторов, электронных отходов или постоянных магнитов.

Пример вызова MCP-инструмента из Python-агента:

import httpx

resp = httpx.post(
    "http://localhost:8000/mcp/invoke",
    json={
        "name": "calculate_urban_mining_value",
        "arguments": {
            "scrap_category": "EV_BATTERY_BLACK_MASS",
            "quantity_metric_tons": 5.0,
            "custom_assay_overrides": {"Li": 4.1, "Co": 6.5}
        }
    },
    headers={"X-Dev-Bypass": "true"}  # Or with valid x402 signature
)
print(resp.json())

🧪 Запуск тестов

Выполните автоматический набор тестов, проверяющий поток 402 challenge, криптографическую проверку EIP-712, расчеты лома и конечные точки AP2:

pytest -v tests/test_client.py

📜 Лицензия

Лицензия MIT. Создано для автономной агентной коммерции и устойчивости критических минералов.