{"authentication":{"methods":[{"type":"Bearer token","header":"Authorization: Bearer YOUR_API_KEY","description":"API key returned at registration or first x402 deposit; simplest method for getting started"},{"type":"EIP-712 signed authorization","header":"Authorization: EIP712 BASE64_ENCODED_PAYLOAD","description":"Advanced: cryptographic per-query spending cap — each request is signed and bound to a max_cost; the server rejects if scan would exceed it. Most agents do not need this; the deposit balance is the effective spending cap."},{"type":"x402 per-query payment","header":"X-PAYMENT: BASE64URL_ENCODED_JSON","description":"Pay per query with an EIP-3009 transferWithAuthorization — no registration required. Omit Authorization to receive a 402 challenge with the exact cost; sign for that amount and retry. Minimum 10,000 micro-USDC ($0.01) per query. Account is auto-created on first payment; api_key returned in X-Payment-Account-Key response header."}]},"base_url":"https://microquery.dev","datasets":[{"name":"nvd","description":"NVD/CVE vulnerability records with CVSS scores and descriptions (~5 GB)","example_sql":"SELECT id, descriptions[0].value AS description FROM cve WHERE metrics.cvssMetricV31[0].cvssData.baseScore \u003e 9 LIMIT 5"},{"name":"osv","description":"OSV.dev open-source vulnerability advisories, one row per affected package (~400 MB)","example_sql":"SELECT id, summary FROM advisories WHERE ecosystem = 'npm' LIMIT 5"},{"name":"sec","description":"SEC EDGAR XBRL structured financial facts for all US public companies, 8,898 companies (~6 GB)","example_sql":"SELECT company, concept, val, filed FROM edgar WHERE ticker = 'AAPL' AND concept = 'Revenues' ORDER BY filed DESC LIMIT 5"},{"name":"pubmed","description":"PubMed biomedical literature titles and abstracts (~350 GB decompressed, 36M articles)","example_sql":"SELECT MedlineCitation.Article.ArticleTitle FROM baseline WHERE MedlineCitation.Article.ArticleTitle ~ 'COVID' LIMIT 5"},{"name":"eth","description":"Ethereum on-chain data: blocks, transactions, ERC-20 token transfers, Uniswap V2/V3 DEX swaps, AAVE/Compound lending events, and Uniswap LP events","example_sql":"SELECT from_address, to_address, token_address FROM transfers WHERE block_number \u003e 21000000 LIMIT 5"},{"name":"btc","description":"Bitcoin blocks with transaction counts and metadata (~6,300 days)","example_sql":"SELECT height, hash, tx_count FROM blocks WHERE height \u003e 880000 LIMIT 5"}],"datasets_url":"https://microquery.dev/datasets.md","deposit":{"chain":"Base","methods":[{"auth":"Bearer YOUR_API_KEY","body_fields":["amount (micro-USDC)","deadline (Unix timestamp)","v","r","s"],"description":"Sign an EIP-2612 permit off-chain (no ETH needed), POST amount+deadline+v+r+s. Operator sponsors gas.","endpoint":"POST /v1/deposit","escrow_contract":"0xb1f8eE89bc8E51558a3C2A216620aBa1b7B2d01A","name":"EIP-2612 permit (primary — requires existing account)"},{"auth":"X-PAYMENT header (no prior registration needed)","description":"Sign an EIP-3009 transferWithAuthorization, encode as base64url JSON, send as X-PAYMENT header. First deposit auto-creates account and returns api_key. No ETH required. Note: x402 facilitator fee ($0.001/tx) adds overhead for low-cost queries.","endpoint":"POST /v1/deposit","name":"x402 (advanced — auto-register on first deposit)","response_first_deposit":{"fields":["api_key","balance_micro_usdc","transaction","network"],"status":201},"response_top_up":{"fields":["balance_micro_usdc","transaction","network"],"status":200},"steps":["1. Build TransferWithAuthorization: from=YOUR_WALLET, to=operator_address, value=amount, validAfter=0, validBefore=now+300, nonce=random_bytes32","2. Sign with EIP-712 using domain {name:'USD Coin', version:'2', chainId:8453, verifyingContract:usdc_contract}","3. Build payload: {x402Version:1, scheme:'exact', network:'base', payload:{signature:'0x...', authorization:{from,to,value,validAfter,validBefore,nonce}}}","4. Base64url-encode the JSON (no padding), set as X-PAYMENT header","5. POST /v1/deposit with Content-Type: application/json, body: {}"]}],"minimum_micro_usdc":250000,"operator_address":"0x5da586b29c3bb0f86cf820b9ac4331b289a6e50b","token":"USDC","usdc_contract":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"},"description":"Pay-per-query SQL over SEC EDGAR financials, NVD/CVE vulnerabilities, OSV open-source advisories, Ethereum DeFi on-chain data, Bitcoin blocks, and PubMed biomedical literature. An agent registers, receives 100,000 micro-USDC trial credit ($0.10), and runs SQL queries immediately. Deposit USDC to continue beyond the trial.","discovery":{"description":"Lists all databases and tables with field names, partition key, and total decompressed size. No authentication required.","endpoint":"GET /v1/databases","parameters":{"partitions":"Set to 'true' to include a per-partition byte breakdown for each table (response grows to ~500 KB uncompressed; use only when you need to reason about specific date/year coverage)."}},"docs_url":"https://microquery.dev/docs.md","examples_url":"https://microquery.dev/examples.md","faq_url":"https://microquery.dev/faq.md","first_query":{"database":"nvd","note":"Run this immediately after registration using your trial credit","sql":"SELECT id, descriptions[0].value AS description FROM cve WHERE metrics.cvssMetricV31[0].cvssData.baseScore \u003e 9 LIMIT 3"},"pricing":{"description":"150 micro-USDC per GiB of data scanned. Trial credit of 100,000 micro-USDC ($0.10) covers all example scripts. 1 USDC = 1,000,000 micro-USDC.","micro_usdc_per_gib":150,"minimum_deposit_micro_usdc":250000,"trial_credit_micro_usdc":100000,"typical_query_micro_usdc":"150–3000 depending on dataset size"},"query":{"cost_headers":["X-Microquery-Cost-MicroUSDC","X-Microquery-Balance-MicroUSDC"],"endpoint":"GET or POST /query","parameters":["database (required)","query (required SQL string)"],"response_format":"newline-delimited JSON (application/x-ndjson), one object per row","status_402":{"insufficient_balance":{"action":"Deposit USDC via POST /v1/deposit to continue","body":{"balance":"\u003cM micro-USDC\u003e","error":"insufficient balance","estimated_cost":"\u003cN micro-USDC\u003e"},"when":"Authenticated request (Bearer token) but balance too low"},"x402_challenge":{"action":"Sign EIP-3009 transferWithAuthorization for maxAmountRequired, base64url-encode as X-PAYMENT header, and retry the same request","body":{"accepts":[{"asset":"\u003cUSDC_contract_on_Base\u003e","maxAmountRequired":"\u003cestimated_micro_usdc\u003e","maxTimeoutSeconds":60,"network":"base","payTo":"\u003coperator_wallet\u003e","scheme":"exact"}],"x402Version":1},"when":"No Authorization header (unauthenticated request)"}}},"registration":{"endpoint":"POST /v1/register","fields":[{"name":"name","type":"string","required":true,"description":"Display name for this agent (max 64 chars)"},{"name":"wallet_addr","type":"string","required":false,"description":"Ethereum wallet address (0x + 40 hex chars); enables EIP-712 per-query authorization and account recovery by wallet"}],"response_includes":["id","api_key","balance","first_query","deposit_instructions"]},"service":"Microquery","sql_syntax":{"critical_differences":[{"example":"Step 1: SELECT id FROM nvd WHERE score \u003e 9  →  Step 2: SELECT * FROM osv WHERE id IN ('CVE-...')","instead":"Two-step: run query A to get IDs, then use WHERE id IN ('x','y','z') in query B","rule":"NO JOIN"},{"instead":"Every large table has a partition key (pub_year, obs_year, block_number, etc.) — include it in WHERE","large_tables":[{"example":"WHERE pub_year \u003e= 2020","partition_key":"pub_year","size":"350 GB","table":"pubmed.baseline"},{"example":"ORDER BY fy DESC LIMIT 10 is sufficient","partition_key":"none — 6 GB, scans in ~1s, no filter needed","size":"6 GB","table":"sec.edgar"},{"example":"WHERE block_number \u003e= 21000000","partition_key":"block_number","size":"large","table":"eth.transfers"},{"example":"WHERE partition_date \u003e= '2024-01-01'","partition_key":"partition_date","size":"large","table":"eth.dex_swaps"},{"example":"WHERE block_number \u003e= 21000000","partition_key":"block_number","size":"large","table":"eth.mev"},{"example":"WHERE cycle \u003e= 2022","partition_key":"cycle","size":"37 GB","table":"fec.contributions"},{"example":"WHERE obs_year \u003e= 2020","partition_key":"obs_year","size":"medium","table":"fred.series"}],"rule":"ALWAYS use partition key on large tables or query will time out"},{"example":"✗ WHERE \"MedlineCitation.Article.ArticleTitle\" ~ 'covid'  →  ✓ WHERE MedlineCitation.Article.ArticleTitle ~ 'covid'","instead":"Write the path bare without quotes — double-quoting treats the entire dotted string as one literal column name and silently returns null for all rows","only_quote":"Only double-quote actual SQL reserved words that are also field names: \"value\" in fred.series, \"end\" in sec.edgar","rule":"Never double-quote dotted nested field paths"},{"example":"descriptions[0].value  or  FROM cve AS c, c.descriptions AS d WHERE d.lang = 'en'","instead":"Use array[0].field for a single element, or comma in FROM to unnest all elements","rule":"Array field access uses index notation; string operators on bare array columns return no rows","trap":"LIKE, ILIKE, ~ and = applied directly to an array-typed column always return no rows — access elements first: phases[0] = 'PHASE3' not phases LIKE '%PHASE3%'"},{"example":"WHERE published \u003e= `2024-01-01T00:00:00Z`","instead":"Use backtick-quoted ISO-8601 strings for timestamp comparisons","rule":"Timestamp literals use backticks"},{"example":"DATE_TRUNC('month', block_timestamp)","instead":"DATE_TRUNC('month', field) — grain is a quoted string","rule":"DATE_TRUNC uses string grain"}],"dialect":"Sneller — vectorised columnar SQL, mostly ANSI-compatible with the following critical differences","reserved_words":"Some field names are SQL reserved words and must be double-quoted: \"value\" (fred.series), \"end\" (sec.edgar). Example: SELECT AVG(\"value\") FROM series","string_matching":"LIKE, ILIKE, and ~ (regex) are all supported. ~ is faster for complex patterns: WHERE name ~ '(?i)sema.*tide' matches case-insensitively. LIKE '%word%' also works."},"use_cases":[{"datasets":["nvd","osv"],"description":"NVD gives severity; OSV gives ecosystem-aware fix versions. Together they answer the question developers actually need: is there a safe version to upgrade to, or do I have to mitigate another way?","name":"Patch-or-not security triage","prompt":"Which npm and PyPI packages have a CVSS 9+ CVE from 2024, and does OSV show a patched version available — or is it still unpatched?","steps":[{"database":"nvd","note":"Pull vector string alongside score — if vectorString is missing or score looks wrong, cvssMetricV31 may be absent for that entry; also pull title to sanity-check: if 'Linux kernel' appears for a Python/npm package row that is a cross-contamination signal","sql":"SELECT id, metrics.cvssMetricV31[0].cvssData.baseScore AS score, metrics.cvssMetricV31[0].cvssData.vectorString AS vector, descriptions[0].value AS title FROM cve WHERE metrics.cvssMetricV31[0].cvssData.baseScore \u003e= 9.0 AND published \u003e= `2024-01-01T00:00:00Z` LIMIT 20"},{"database":"osv","note":"Use aliases field (array of CVE IDs) not id for the join — OSV primary IDs are GHSA-* not CVE-*; verify the alias round-trips back to the expected CVE ID before trusting the score","sql":"SELECT id, aliases, package_name, ecosystem, summary, affected[0].ranges[0].events FROM advisories WHERE aliases[0] IN ('CVE-2024-...') AND ecosystem IN ('npm', 'PyPI') LIMIT 20"}]},{"datasets":["sec","fred"],"description":"SEC EDGAR gives audited 10-K revenue; FRED gives the monetary policy backdrop. No single financial data vendor combines micro (company) and macro (central bank) in one query interface.","name":"Earnings vs macro environment","prompt":"Show Apple's annual revenue for 2020–2024 alongside the Fed Funds Rate for each year — did earnings growth outpace the rate environment?","steps":[{"database":"sec","note":"sec.edgar has no partition key — full table is only 6 GiB so scans in ~1s; ORDER BY fy DESC LIMIT 5 is sufficient to get recent years","sql":"SELECT fy, val AS revenue_usd FROM edgar WHERE ticker = 'AAPL' AND concept = 'RevenueFromContractWithCustomerExcludingAssessedTax' AND form = '10-K' AND fp = 'FY' ORDER BY fy DESC LIMIT 5"},{"database":"fred","note":"\"value\" must be quoted — it is a reserved word in Sneller; field is already numeric, no CAST needed","sql":"SELECT obs_year, AVG(\"value\") AS avg_rate FROM series WHERE series_id = 'DFF' AND obs_year \u003e= 2020 GROUP BY obs_year ORDER BY obs_year DESC"}]},{"datasets":["fda","pubmed","clinicaltrials"],"description":"FDA FAERS captures post-market safety signals; PubMed shows research momentum; ClinicalTrials reveals the active pipeline. Together they give a complete drug-class intelligence picture that pharmacovigilance, investment, and clinical teams all need.","name":"GLP-1 drug class full picture","prompt":"For GLP-1 agonists: how many FDA adverse event reports were filed in 2023, how many PubMed papers published each year since 2020, and how many Phase 3 trials are currently active?","steps":[{"database":"fda","note":"drugname is a flat field (not nested); year is the partition key","sql":"SELECT drugname, COUNT(*) AS reports FROM faers WHERE drugname ILIKE '%semaglutide%' AND year = 2023 GROUP BY drugname ORDER BY reports DESC LIMIT 10"},{"database":"pubmed","note":"pub_year partition key required — omitting it causes a full 350 GB scan and timeout. CRITICAL: do NOT double-quote the dotted path — write MedlineCitation.Article.ArticleTitle bare; quoting it as \"MedlineCitation.Article.ArticleTitle\" treats it as a single column name and silently returns null for all rows","sql":"SELECT pub_year, COUNT(*) AS papers FROM baseline WHERE MedlineCitation.Article.ArticleTitle ~ '(?i)GLP-1|glucagon.like peptide' AND pub_year \u003e= 2020 GROUP BY pub_year ORDER BY pub_year DESC"},{"database":"clinicaltrials","note":"overall_status (not status); phases and interventions are arrays — use phases[0] = 'PHASE3' and interventions[0].name ILIKE '...'; applying LIKE directly to an array column (phases LIKE '%PHASE3%') always returns no rows","sql":"SELECT phases[0] AS phase, COUNT(*) AS trials FROM studies WHERE interventions[0].name ILIKE '%semaglutide%' AND overall_status = 'RECRUITING' GROUP BY phase ORDER BY trials DESC LIMIT 10"}]},{"datasets":["eth"],"description":"Both tables live in the eth database: mev holds builder-level extraction data; dex_swaps holds Uniswap V2/V3 swap events. Correlating them shows whether MEV is driven by market volatility or just volume — a question quant funds and MEV researchers track closely.","name":"MEV extraction vs DEX activity","prompt":"Compare MEV extraction by builder with Uniswap DEX swap volume by day in 2024 — do high-MEV days correlate with high DEX activity?","steps":[{"database":"eth","note":"Daily MEV per builder; partition key is date (string), extraction field is value_eth","sql":"SELECT date, builder_pubkey, SUM(value_eth) AS total_mev, COUNT(*) AS blocks FROM mev WHERE date \u003e= '2024-01-01' GROUP BY date, builder_pubkey ORDER BY date DESC, total_mev DESC LIMIT 20"},{"database":"eth","note":"Daily DEX swap count by protocol (v2/v3); table is dex_swaps, partition key is partition_date","sql":"SELECT partition_date, protocol, COUNT(*) AS swaps FROM dex_swaps WHERE partition_date \u003e= '2024-01-01' GROUP BY partition_date, protocol ORDER BY partition_date DESC, swaps DESC LIMIT 20"}]}]}