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

Base URL

https://assaychain.com/api

Also accessible at assaychain.com. All paths below are relative to the base URL above.

Endpoints

Thirty-four routes, four tiers

Method	Path	Auth	Price	Description
GET	`/health`	None	Free	API status, version, uptime. Always returns 200.
GET	`/benchmark/gold`	x402	$0.10 USDC	USGS gold commodity summary — mine production, reserves, price, global context.
GET	`/benchmark/silver`	x402	$0.10 USDC	USGS silver commodity summary — industrial use, mine output, reserves, price.
GET	`/benchmark/copper`	x402	$0.10 USDC	USGS copper commodity summary — energy transition demand, mine production, reserves.
GET	`/benchmark/lithium`	x402	$0.10 USDC	USGS lithium commodity summary — EV battery demand, hard-rock vs. brine routes, grade cutoffs, CO2e factors.
GET	`/benchmark/cobalt`	x402	$0.10 USDC	USGS cobalt commodity summary — DRC supply concentration, battery vs. superalloy uses, recovery benchmarks.
GET	`/benchmark/nickel`	x402	$0.10 USDC	USGS nickel commodity summary — Indonesian supply, sulfide vs. laterite routes, battery-grade Class I pricing.
GET	`/benchmark/manganese`	x402	$0.10 USDC	USGS manganese commodity summary — steelmaking vs. LMFP battery demand, ore grades, smelting recovery.
GET	`/benchmark/graphite`	x402	$0.10 USDC	USGS graphite commodity summary — natural vs. synthetic anode routes, China supply concentration, SPG battery grade.
GET	`/benchmark/antimony`	x402	$0.10 USDC	USGS antimony commodity summary — China controls >80% of supply; flame retardants, semiconductors, lead-acid batteries.
GET	`/benchmark/gallium`	x402	$0.10 USDC	USGS gallium commodity summary — Chinese export controls 2023; GaAs/GaN semiconductors, LEDs, solar cells.
GET	`/benchmark/germanium`	x402	$0.10 USDC	USGS germanium commodity summary — Chinese export controls 2023; fiber optics, infrared optics, solar cells.
GET	`/benchmark/platinum_group`	x402	$0.10 USDC	USGS platinum-group elements summary — South African supply concentration; autocatalysts (Pt/Pd/Rh), fuel cells, hydrogen electrolyzers.
GET	`/benchmark/rare_earths`	x402	$0.10 USDC	USGS rare-earth elements summary — Nd, Dy, Pr, Tb; permanent magnets for EV motors and wind turbines; Chinese supply dominance.
GET	`/benchmark/tellurium`	x402	$0.10 USDC	USGS tellurium commodity summary — byproduct of copper refining; CdTe thin-film solar cells, thermoelectrics.
GET	`/benchmark/tin`	x402	$0.10 USDC	USGS tin commodity summary — electronics solder, tin plate, bronze alloys; Indonesia and China as primary suppliers.
GET	`/benchmark/titanium`	x402	$0.10 USDC	USGS titanium commodity summary — aerospace alloys, TiO₂ pigments, biomedical implants; rutile vs. ilmenite ore routes.
GET	`/benchmark/tungsten`	x402	$0.10 USDC	USGS tungsten commodity summary — highest melting-point metal; cutting tools, military applications; China controls ~80% of supply.
GET	`/benchmark/uranium`	x402	$0.10 USDC	USGS uranium commodity summary — nuclear fuel feed material; U₃O₈ spot price, enrichment capacity gap, Kazakhstan/Canada supply.
GET	`/benchmark/vanadium`	x402	$0.10 USDC	USGS vanadium commodity summary — steel microalloying, vanadium redox flow batteries (VRFB); China produces ~60% of supply.
GET	`/benchmark/zinc`	x402	$0.10 USDC	USGS zinc commodity summary — galvanizing steel, brass alloys, die-casting; Australia, China, and Peru as leading producers.
GET	`/benchmark/research/mineral-processing/{study}`	x402	$0.10 USDC	Paginated list of attested mineral-processing field run logs. Filterable by feed type, frequency, recovery, attestation status.
GET	`/historical/{country}/{state}`	None	Free	Index of mining districts for a country/state pair. Returns county slugs and district counts (e.g. `US/MT`).
GET	`/historical/{country}/{state}/{county}`	None	Free	Index of mining districts in a county. Returns district slugs and metadata (e.g. `US/MT/Missoula`).
GET	`/historical/{country}/{state}/{county}/{district}`	x402	$0.50 USDC	Curated mining district report — deposit geology, historical production, MRDS references, IPFS CID, and EAS attestation UID. 179 districts indexed across the western US and Mexico.
POST	`/mcp`	None	Free	MCP JSON-RPC endpoint (Streamable HTTP, stateless). Exposes benchmark and run tools for AI agents. Paste URL into Claude Desktop or any MCP-compatible client.
POST	`/ask`	x402	$0.10 USDC	Tier-1 RAG synthesis over 199 attested corpus files. Ask a natural-language question about mineral processing, field methods, or USGS data; returns a cited, grounded answer.
GET	`/price-snapshot/{commodity}?date=`	x402	$0.05 USDC	Daily mineral market context bundle: spot price, Baltic Dry Index, WTI crude, producing-country FX rate, LME warehouse stock. Optional `date=YYYY-MM-DD` for historical lookup. Attested weekly. Supports all 20 commodities.
POST	`/enrich/criticalminerals`	x402	$0.50 USDC	Company critical-minerals exposure profile. Send `{ "company": "...", "domain": "..." }` and receive a structured per-commodity exposure map across all 20 USGS critical minerals: exposure level (direct/indirect/negligible), China concentration, top producers, US self-sufficiency, resilience rating, and evidence citations. Output includes USGS attestation UIDs per commodity. Synthesised by a 3-agent Groq swarm. Useful for ESG, underwriting, supply-chain compliance, and M&A due-diligence agents.
GET	`/receipts/:id`	None	Free	Re-fetch a stored x402 receipt by its `receipt_id`. Returns the full `x402-receipt-v1` object including settlement status, payer, route, and block explorer link. 30-day TTL.
POST	`/data-license/inquiry`	None	Free	Bulk / enterprise corpus licensing inquiry. Submit contact details and use-case description; returns a confirmation token. Rate limited to 10 requests per hour per IP.
POST	`/extract/estimate`	None	Free	Probe a public document URL (PDF, image, CSV, TXT). Returns `estimate_id`, page count, quality floor grade (A–D), and USDC price quote. 15-min TTL. No payment taken. Beta
POST	`/extract/run`	x402	$0.10–$5.00 USDC	Pay and execute structured-data extraction on a previously estimated document. Returns `job_id`, grade (A–D), and HMAC-signed `result_url`. Grade D triggers 80% manual refund. Beta
GET	`/extract/result/:id`	HMAC token	Free	Re-fetch extraction result using the signed token from `result_url`. Returns assay-extract-v0.1 document (samples, lab, grades, OPSEC-rounded coords). 24h TTL. Beta

Pricing

Flat rate, no surprises

Free tier

GET /health always returns 200 at no cost. Use it to verify the API is live, test your client setup, or monitor uptime.

No wallet required.

$0.10 USDC per call

All data endpoints are gated with x402. Each successful call costs exactly $0.10 USDC settled on Base mainnet via CDP Facilitator.

Payment recipient:
0x750977976Ab85A4Ce5AAbb2e1a9fc80a633f2769

Run logs endpoint

Query parameters for `/benchmark/research/mineral-processing/{study}`

Parameter	Type	Default	Description
`feed_type`	string	—	Filter by feed type (e.g. `placer_concentrate`).
`frequency_khz`	number	—	Filter by frequency in kHz (e.g. `28`, `40`).
`min_recovery_pct`	number	—	Return only runs with recovery rate = this value.
`attested_only`	boolean	`false`	If `true`, return only runs with an EAS attestation UID.
`limit`	number	`20`	Number of results per page. Max 100.
`offset`	number	`0`	Pagination offset.

Extract API

Assay extraction in four steps Beta

Upload any public assay report URL. AI-powered extraction reads your document and returns every sample row as structured JSON. E2E proven: USGS Circular 592, 57 fire-assay Au samples, San Juan Mtns CO, grade B.

01

Free estimate — get a price quote (no payment)

POST /extract/estimate · Body: {"source_url":"https://..."}

                  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"}'
                

Response fields: estimate_id (use in step 3), page_count, quality_floor (A/B/C/D — worst-case grade), price_usdc ($0.10 for <5 pages, scales by page count), ttl_seconds (900 = 15 min). No charge.

02

Review the quote

Check price_usdc and quality_floor. The quality floor is based on document structure detected at probe time — actual grade may be higher. The estimate_id expires after 15 minutes. If it expires, call /extract/estimate again — no charge for re-probing.

Supported document types: PDF (digital and scanned), image (PNG/JPG/WEBP), CSV, TXT. XLSX and DOCX return HTTP 415 — no charge.

03

Pay and run (x402 — USDC on Base)

POST /extract/run · Body: {"estimate_id":"<id from step 1>"}

                  curl -X POST \
  "https://assaychain.com/api/extract/run" \
  -H "content-type: application/json" \
  -H "X-PAYMENT: <signed-x402-header>" \
  -d '{"estimate_id":"est_2026-05-14-abc123"}'
                

Response: job_id, grade (A–D), samples[] array (one object per row: element, value, unit, depth, notes), grade_signals object (four boolean scores), and a signed result_url for 24h re-access. Result stored in Firestore.

If grade === "D": 80% refund issued manually within 24h. If grade === "C": result delivered with a review-recommended flag.

04

Re-fetch result within 24h (free)

The result_url from step 3 contains a HMAC-signed token valid for 24 hours. Use it to re-fetch the full result at no cost:

curl "https://assaychain.com/api/extract/result/<job_id>?token=<token>"

After 24h: HMAC token expires (HTTP 410). The Firestore document persists indefinitely but requires a new paid /extract/run to re-access via API.

MCP

AI agent integration via MCP

The API exposes a Model Context Protocol JSON-RPC endpoint at POST /mcp (Streamable HTTP, stateless). Any MCP-compatible client can add it with a single URL. Tools available: get_commodity_benchmark, get_mineral_processing_run_data, ask_sales_agent. Paid tools go through the client’s built-in x402 payment flow.

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"
    }
  }
}
            

Or add to VS Code user settings.json: "mcp.servers": { "assaychain": { "type": "http", "url": "..." } }

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"
)
            

For ChatGPT Custom GPTs (Actions): contact us via the Contact page for the OpenAPI spec.

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')
            

Examples

curl examples

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 in the body. This is correct — the gate is working.

3. Filtered run logs (after paying via x402 client)

            curl -H "X-PAYMENT: <signed-payment-header>" \
  "https://assaychain.com/api/benchmark/research/mineral-processing/thixotropic-elutriation-v1?feed_type=placer_concentrate&attested_only=true&limit=10"
          

4. Free extraction estimate (probe + price quote)

            curl -X POST \
  "https://assaychain.com/api/extract/estimate" \
  -H "content-type: application/json" \
  -d '{"source_url":"https://example.com/assay-report.pdf"}'
          

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

5. Paid extraction run (x402 — $0.10–$5.00 USDC)

            curl -X POST \
  "https://assaychain.com/api/extract/run" \
  -H "content-type: application/json" \
  -H "X-PAYMENT: <signed-payment-header>" \
  -d '{"estimate_id":"<estimate_id-from-step-4>"}'
          

Returns job_id, grade (A–D), full extraction result, and a signed result_url for 24h re-fetch.

6. Fetch stored result (HMAC-gated — free)

            curl "https://assaychain.com/api/extract/result/<job_id>?token=<token-from-result_url>"
          

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 first: call GET /health (always free) or POST /extract/estimate (free probe, no payment taken).

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. See the MCP section above for the snippet.

ChatGPT Custom GPTs (Actions): requires an OpenAPI spec — contact us via the Contact page.

Any custom agent: use x402-fetch (NPM) or x402 (Python) to call endpoints directly with automatic payment. See the SDK examples in the MCP section above.

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.

What document types does Extract support?

Supported in v0.1: 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. Authenticated URLs and local file paths are not supported in v0.1.

How is the A–D extraction grade calculated?

Each job is scored on four signals: (1) structural validity — valid sample rows conforming to the schema; (2) coverage — =70% of expected rows found; (3) self-consistency — two independent extraction passes return the same values; (4) cross-check — element symbols recognized and numeric values within physical bounds.

Grade A = all four pass. B = three. C = two. D = one or fewer. Grade D triggers an 80% manual refund within 24h.

Is extracted data stored on IPFS?

No. Extraction results are stored in Firestore only, token-gated for 24h. IPFS and EAS attestation are reserved for the benchmark and field run log pipeline, which stores permanent on-chain provenance. Extract is designed for one-time job queries, not long-term archival.

Can I re-call POST /extract/run with the same estimate_id?

Yes — within 24h of the first successful run, POST /extract/run with the same estimate_id returns the cached Firestore result without charging again. After 24h the HMAC token expires (HTTP 410) and you need a new estimate + run. Use the result_url from the original response for the cheapest re-access path.

How do I verify a benchmark attestation?

Take the attestation_uid field from any benchmark or /benchmark/research/mineral-processing/thixotropic-elutriation-v1 response and paste it into base.easscan.org. You’ll see the full on-chain record: schema UID, attesting wallet address, encoded field values, and timestamp. Fetch the ipfs_cid from any IPFS gateway to retrieve the original source JSON. No trust in AssayChain required. See the Provenance page for step-by-step verification 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: $0.10 on Base.

03 — Pay

EIP-3009 Sign

x402 client signs the authorization and sends payment on Base mainnet.

04 — Data

Full Response

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

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

Endpoints &Pricing

Thirty-four routes, four tiers

Flat rate, no surprises

Free tier

$0.10 USDC per call

Query parameters for /benchmark/research/mineral-processing/{study}

Assay extraction in four steps Beta

Free estimate — get a price quote (no payment)

Review the quote

Pay and run (x402 — USDC on Base)

Re-fetch result within 24h (free)

AI agent integration via MCP

curl examples

1. Free health check

2. Trigger the 402 gate (expected response)

3. Filtered run logs (after paying via x402 client)

4. Free extraction estimate (probe + price quote)

5. Paid extraction run (x402 — $0.10–$5.00 USDC)

6. Fetch stored result (HMAC-gated — free)

Developer FAQ

x402 protocol flow

HTTP GET

402 Response

EIP-3009 Sign

Full Response

Endpoints &
Pricing

Query parameters for `/benchmark/research/mineral-processing/{study}`