API Documentation — 20 Critical Minerals, x402 Payment, Base Mainnet

Base URL

https://assaychain.com/api

All paths below are relative to the base URL above.

Payment

Endpoints are gated by x402 (USDC on Base mainnet) at the listed call price, or free with no payment required. Credit card purchases available at assaychain.com/buy — generates an API key for Bearer-token auth.

Extraction — The Refinery

Turn documents into structured, attested data

Upload public assay reports, drill logs, or lab certificates — AI extracts every sample row as structured JSON with structured provenance (site, county, state, assayer, sample dates). Grade A–D with 80% refund on Grade D. Or ask natural-language questions across 199 attested corpus documents.

Endpoint	Price	What it does
`/extract/estimate`	Free	Probe any public document URL (PDF, image, CSV, TXT). Returns estimate_id, page count, quality grade floor (A–D), USDC price quote. No payment taken.
`/extract/run`	$0.10–$5.00	Execute paid extraction. Gemini 2.5 Flash reads document, returns structured JSON with samples array, quality grade, QA verdict, and provenance fields. Grade D triggers 80% refund. Results cached in Firestore + IPFS for re-use.
`/extract/result/{id}`	Free (HMAC)	Re-fetch paid extraction result within 24h using signed result_token. Token-gated, no extra payment.
`/ask`	$0.10	Grounded Q&A over 199 attested corpus files (20 USGS commodities + 18 district reports + field runs). Returns synthesized answer with inline source citations and attestation UIDs.

Experimental — Risk, Compliance & Intelligence

Research tools: risk scores, compliance checklists, geological screening

Heuristic, AI-assistive research context. Not investment, procurement, or regulatory determinations. Compliance outputs require Qualified Person review. Score methodology: published here. Each endpoint returns structured JSON with provenance (EAS attestation UID + IPFS CID) where applicable.

Endpoint	Price	What you get
`/risk/{commodity}`	$0.50	Supply-chain risk score (0–100), China dependency, allied supply ratio, per-country producer risk breakdown, recommended alternative sourcing countries, production diversity score.
`/resilience/{commodity}`	$0.50	5-factor resilience score with 3 scenario stress tests (China export ban, DLA depletion, allied disruption). Per-factor breakdown with weights.
`/esg/{commodity}`	$0.50	Recycling metrics (rate, scrap splits, EOL recovery), carbon intensity by producing country, regulatory exposure (CBAM, Battery Passport, IRA §45X, SEC climate).
`/compliance/check`	$0.50	Per-commodity, per-country regulatory check against DFARS (US defense), IRA §45X (EV tax credits), EU Battery Passport (2023/1542).
`/compliance/ni43-101`	$0.50	Structured 8-item NI 43-101 compliance checklist — Qualified Person, QA/QC, chain of custody, data verification, lab accreditation, independent review, disclosure standards, report format.
`/compliance/jorc`	$0.50	JORC 2012 Table 1 compliance report — 10 items across 3 sections (Sampling, Exploration Results, Mineral Resources).
`/criticality/{commodity}`	$0.25	Multi-jurisdiction critical mineral crosscheck — US DoD, EU, IEA, Japan METI lists. Jurisdictions-rating-critical count.
`/trade-controls/{commodity}`	$0.25	China export restriction status, effective date, legal basis, source URL. Covers gallium, germanium, graphite, antimony.
`/supply/{commodity}`	$0.25	Supply concentration: top-3 producers, Herfindahl-Hirschman Index (HHI), allied vs adversarial production share.
`/stockpile/{commodity}`	$0.25	DLA National Defense Stockpile status — quantity held, active/sold-out/not-stockpiled classification.
`/intelligence/{commodity}`	$0.50	NEW: Aggregate intelligence report — composes risk, resilience, criticality, trade-controls, supply, stockpile, ESG, and price-snapshot into one response. Saves ~80% vs 8 individual calls ($2.55 → $0.50).
`/intelligence/company/{name}`	$0.50	NEW: Full company dossier — 3-agent enrichment pipeline (company context → USGS overlay → synthesis) plus per-commodity supply-chain risk and resilience scores. Optional `?domain=` and `?commodities=` filters.
`/enrich/criticalminerals`	$0.50	Company exposure profile across all 20 USGS critical minerals. 3-agent DeepSeek swarm: research → USGS overlay → synthesized report with confidence score, per-commodity resilience, China share. Ideal for ESG, underwriting, M&A due diligence.
`/procurement/find`	$0.50	Ranked supplier intelligence — top producers by allied preference and risk score with market context and a single best-option recommendation.
`/deposit-model/{type}`	$0.50	Geological deposit model profiles (skarn, porphyry, VMS): expected mineralogy, gangue minerals, processing recommendations, exploration indicators.
`/ore-potential`	$0.50	AI-powered in-situ ore valuation from assay data with real-time metal prices. Deposit type classification, processing route indications, penalty element flags.

Benchmarks & Prices

USGS commodity data and daily market context

20 critical minerals, each with attested production, reserves, trade, and carbon-bridge data from the official USGS Mineral Commodity Summaries. Plus daily spot prices, Baltic Dry Index, WTI crude, and FX rates.

Endpoint	Price	Coverage
`/benchmark/{commodity}`	$0.10	20 minerals: copper, gold, silver, lithium, cobalt, nickel, manganese, graphite, antimony, gallium, germanium, platinum-group, rare-earths, tellurium, tin, titanium, tungsten, uranium, vanadium, zinc. Each response includes production, reserves, typical grade ranges, top producers, China share, carbon-bridge fields, EAS attestation UID, and IPFS source CID.
`/price-snapshot/{commodity}`	$0.05	Daily spot price + 1d/1m change, source (LME/FRED/Yahoo), BDI, WTI crude, producing-country FX rate. Optional historical lookup by date. Attested weekly.
`/benchmark/research/mineral-processing/{study}`	$0.10	Paginated attested field run logs — feed type, tray geometry, processing parameters, recovery rate, EAS attestation UID. Filterable by feed type, frequency, recovery threshold.

Land & Geospatial

BLM claims, geophysics, operations, and Earth MRI

Public-domain land and survey data curated for agent consumption — BLM LR2000 mining claims, historical geophysical surveys, active US mining operations, and USGS Earth MRI focus areas. All $0.25/call.

Endpoint	Price	Coverage
`/blm-claims/{state}/{county}`	$0.25	BLM LR2000 mining claims — lode/placer/millsite counts, total acres. 10 counties across NV, AZ, CA, CO, NM, AK.
`/geophysics/{district}`	$0.25	Historical aeromagnetic, gravity, EM, and radiometric survey metadata — year, coverage sq-km, resolution. 12 western-US districts.
`/active-operations/{commodity}`	$0.25	Active US mining operations per critical mineral — name, operator, location, stage, capacity. 10 commodities.
`/earth-mri/{state}`	$0.25	USGS Earth MRI focus areas — completed and planned surveys by state, target minerals, survey type. 12 states.
`/historical/{c}/{s}/{cnty}/{dist}`	$0.50	Full mining district report — deposit geology, historical production, MRDS references, development history. 182+ districts across 11 US states + 2 MX states. Directory indexes (2–3 path segments) are free.
`/knowledge/graph`	$0.10	Mineral relationship graph — byproduct chains, deposit types, substitutes, host rocks for 18 critical minerals (gallium from bauxite/zinc, germanium from zinc/copper, etc.). Index query returns full graph inventory.

Free Tools

No payment required

Method	Path	Description
GET	`/health`	API status, available endpoints, chain info. Always returns 200.
POST	`/mcp`	MCP JSON-RPC (Streamable HTTP). 19 tools for AI agents. Add to Claude Desktop, Cursor, or VS Code with one URL.
GET	`/receipts/{id}`	Retrieve a stored x402 receipt — full settlement object with payer, route, block explorer link. 30-day TTL.
POST	`/verify`	Verify an existing EAS attestation by UID — returns schema, attester, timestamp, verified flag.
POST	`/data-license/inquiry`	Enterprise/bulk corpus licensing inquiry. Submit contact + use-case; returns confirmation token.
POST	`/agent/research-session`	Create a persistent research session — stores context for multi-turn analysis across AssayChain tools. Free to create.
GET	`/library/search`	NEW: Search the Data Library — every paid API response is automatically cataloged with metadata. Filter by `?commodity=copper&type=criticality`. Browse past purchased results without re-paying. Free to query.

Pricing

Six tiers, no surprises

Free

$0.00

Health checks, MCP discovery, extraction estimates, receipt retrieval, data-license inquiries, agent/session creation. No wallet required.

Market Data

$0.05

Daily price snapshots — spot price, BDI, WTI, FX, LME stock. Attested weekly.

Benchmark

$0.10

USGS commodity benchmarks (20 minerals), RAG answers (/ask), knowledge graph, mineral-processing run logs.

Spatial & Criticality

$0.25

Criticality crosscheck, trade controls, supply concentration, stockpile status, BLM claims, geophysics, active operations, Earth MRI focus areas.

Intelligence

$0.50

Risk, resilience, ESG, compliance (check/NI 43-101/JORC), enrichment, procurement, deposit-model, ore-potential, historical district reports.

Extraction

$0.10–$5.00

Document-dependent pricing. Estimate is always free. Grade D triggers 80% refund.

All paid endpoints use x402 (USDC on Base mainnet) — HTTP 402 challenge, EIP-3009 authorization, automatic settlement. Payment recipient: 0x750977976Ab85A4Ce5AAbb2e1a9fc80a633f2769
No credit card? Buy credits via Stripe →

MCP

AI agent integration via MCP

The API exposes a Model Context Protocol JSON-RPC endpoint at POST /api/mcp (Streamable HTTP, stateless). Any MCP-compatible client can add it with a single URL. 19 tools available across three categories:

10 Intelligence Tools

criticality.crosscheck, china_trade_control, supply_share, stockpile_level, supply_resilience, esg_profile, blm_claims_data, geophysics_surveys, active_operations, earth_mri_focus_areas — preview free, full data via x402 REST.

5 Core Tools

sales.ask (free), benchmark.commodity ($0.10), benchmark.sample (free), benchmark.runs ($0.10), enrich.criticalminerals ($0.50). The main query surfaces for agents.

4 Extract & Corpus Tools

extract.estimate (free), extract.run (paid guide), extract.result (free token-gated), corpus.search (free BM25 over 199 docs), district.history (free preview).

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json

              {
  "mcpServers": {
    "assaychain": {
      "url": "https://assaychain.com/api/mcp"
    }
  }
}
            

VS Code / GitHub Copilot — .vscode/mcp.json (workspace) or User Settings

              {
  "servers": {
    "assaychain": {
      "type": "http",
      "url": "https://assaychain.com/api/mcp"
    }
  }
}
            

Cursor — ~/.cursor/mcp.json

              {
  "mcpServers": {
    "assaychain": {
      "url": "https://assaychain.com/api/mcp"
    }
  }
}
            

ChatGPT / OpenAI Agents SDK (Python)

              from agents.mcp import MCPServerStreamableHTTP

assaychain = MCPServerStreamableHTTP(
    url="https://assaychain.com/api/mcp"
)
            

Any x402 SDK (direct HTTP, no MCP)

              // Node.js / TypeScript
import { wrapFetchWithPayment } from 'x402-fetch';
import { createWalletClient, http } from 'viem';
import { baseSepolia } from 'viem/chains';

const fetch402 = wrapFetchWithPayment(fetch, wallet);
const res = await fetch402(
  'https://assaychain.com/api/benchmark/gold'
);

# Python
pip install x402
from x402.client import x402Client
client = x402Client(private_key=PRIVATE_KEY)
data = client.get('https://assaychain.com/api/benchmark/gold')
            

Quick Start

Test the API in 30 seconds

1. Free health check

curl https://assaychain.com/api/health

2. Trigger the 402 gate (expected response)

curl -i https://assaychain.com/api/benchmark/copper

Returns HTTP/1.1 402 Payment Required with a machine-readable USDC offer. This is correct — the gate is working.

3. Free extraction estimate

            curl -X POST \
  "https://assaychain.com/api/extract/estimate" \
  -H "content-type: application/json" \
  -d '{"source_url":"https://pubs.usgs.gov/circ/1968/0592/report.pdf"}'
          

Returns estimate_id, page count, quality floor grade (A–D), and USDC price. Free to call.

4. Admin preview (no payment, needs admin token)

            curl -H "authorization: Bearer \$ADMIN_TOKEN" \
  "https://assaychain.com/api/admin/peek/criticality/gallium"
          

FAQ

Developer FAQ

What is HTTP 402 and why did I get it?

402 Payment Required is not an error — the gate is working correctly. The response body contains a machine-readable USDC offer. An x402-aware client reads the offer, signs an EIP-3009 authorization, and retries with the X-PAYMENT header automatically.

To test without paying: call GET /health (always free) or POST /extract/estimate (free probe).

Which AI clients work with this API?

MCP clients (add the /mcp URL in settings): Claude Desktop, VS Code / GitHub Copilot, Cursor, Windsurf, and any client built on the MCP SDK. The x402 payment flow for paid tools runs through the client's built-in x402 support.

OpenAI Agents SDK (Python): use MCPServerStreamableHTTP pointing at /mcp.

Any custom agent: use x402-fetch (NPM) or x402 (Python) to call endpoints directly.

What wallet and tokens do I need?

A wallet holding USDC on Base mainnet and a small amount of ETH on Base for gas (~$0.001 per call). Base USDC contract: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.

To fund: bridge from Ethereum via bridge.base.org, or buy directly on Base via Coinbase. No wallet? Buy credits via credit card →

Does the system cache results so I don't pay twice for the same query?

Yes. Extraction results are content-hash cached by sha256(source_url) — requesting the same document again returns the stored result at $0.10 (vs $0.50–$5.00 fresh). Enrichment profiles cache by company name on a 7-day sliding window — $0.10 for cached, $0.50 for fresh. Both are persisted to Firestore + IPFS.

What document types does Extract support?

Supported: PDF (digital and scanned), image (PNG, JPG, WEBP), CSV, TXT.

Not supported (HTTP 415, no charge): XLSX, DOCX.

The source URL must be publicly accessible.

How is the A–D extraction grade calculated?

Each job is scored on four signals: (1) structural validity; (2) coverage (≥70% of expected rows); (3) self-consistency (two independent passes match); (4) cross-check (element symbols recognized, values within physical bounds). Grade A = all four pass. D ≤ one pass — triggers 80% refund within 24h.

How do I verify a benchmark attestation?

Take the attestation_uid field from any response and paste it into base.easscan.org. You'll see the full on-chain record: schema UID, attesting wallet, encoded fields, timestamp. Fetch the ipfs_cid from any IPFS gateway to retrieve the original source JSON. See the Provenance page for step-by-step instructions.

How payment works

x402 protocol flow

01 — Request

HTTP GET

Call any gated endpoint. No auth header required initially.

02 — Gate

402 Response

Server returns 402 Payment Required with USDC offer — amount, network, recipient address.

03 — Pay

EIP-3009 Sign

x402 client signs the authorization, sends USDC on Base mainnet. ~$0.001 gas per call.

04 — Data

Full Response

CDP Facilitator verifies. USDC settles. You receive data + EAS attestation UID + IPFS CID.

Compatible with x402-compatible clients — Claude Desktop, Cursor, and any agent using the x402 SDK.

Structure. Attest.Pay per call.

Turn documents into structured, attested data

Research tools: risk scores, compliance checklists, geological screening

USGS commodity data and daily market context

BLM claims, geophysics, operations, and Earth MRI

No payment required

Six tiers, no surprises

Free

Market Data

Benchmark

Spatial & Criticality

Intelligence

Extraction

AI agent integration via MCP

10 Intelligence Tools

5 Core Tools

4 Extract & Corpus Tools

Test the API in 30 seconds

1. Free health check

2. Trigger the 402 gate (expected response)

3. Free extraction estimate

4. Admin preview (no payment, needs admin token)

Developer FAQ

x402 protocol flow

HTTP GET

402 Response

EIP-3009 Sign

Full Response

Structure. Attest.
Pay per call.