Frequently Asked Questions

The raw data is free; the work is not. Microquery handles ingestion, normalisation, schema design, indexing, and keeps everything current. You get SQL over a clean, consistent schema in a single API call — no pipeline to build, no rate limits to fight, no pagination to handle. The public APIs for PubMed, SEC EDGAR, or NVD were built for human browsing, not for agents running hundreds of queries per loop.

Source APIs have hard rate limits (NVD: 5 req/s, PubMed: 10 req/s), pagination that adds round-trips, inconsistent schemas across years, and no aggregation. You cannot run GROUP BY or REGEXP_MATCH against the NVD REST API — you download everything and post-process it yourself. Microquery runs the aggregation server-side on columnar storage, so a query that would take minutes of API calls and local compute returns in under a second.

That is exactly the point. Register in 30 seconds, get $0.10 free credit, run your query. A single CVE lookup costs $0.0002. No subscription, no contract, no minimum spend. If one query is all you need, you pay for one query.

Microquery charges based on the amount of data scanned to answer your query, not the number of rows returned. The rate is 150 micro-USDC per GiB scanned. A typical query costs around 3 micro-USDC. The exact charge for each query is shown in the response headers.

Every query response includes headers showing the bytes scanned and the cost deducted. You can also retrieve a full transaction history via the account endpoint. If an amount looks wrong, the headers and history together give you a complete audit trail.

GET /v1/estimate?database=...&query=... (or POST with a JSON body) returns estimated_bytes_scanned and estimated_cost_micro_usdc without executing the query or deducting any charge. The estimate is a conservative upper bound from the query planner — actual cost at execution time will be equal or lower.

If your balance is insufficient when a query is submitted, the API returns HTTP 402 (Payment Required) and the query is aborted. No partial charge is applied. Top up your balance by depositing additional USDC into the escrow contract on Base.

Yes. Call withdraw(amount) directly on the escrow contract using your own wallet key — no API call is required. The ledger syncs within approximately 15 seconds via an event watcher. Settlement runs in hourly batches; withdrawals requested before a batch clears are handled gracefully, and any small shortfall is absorbed by the operator by design.

When you register via POST /v1/register, your account receives 100,000 micro-USDC ($0.10) in free trial credit. This credit exists only on the ledger; it cannot be withdrawn. Only USDC that you have deposited on-chain into the escrow contract is eligible for withdrawal.

Query charges accumulate and are settled to the escrow contract in hourly batches. During the window between a query and settlement, your on-chain balance has not yet been reduced. If you withdraw before the batch clears, the operator absorbs any resulting shortfall — this is intentional and the exposure is minimal at current per-query pricing.

The minimum deposit is 250,000 micro-USDC (0.25 USDC). Deposits are made in USDC on Base, Ethereum's L2, by sending funds directly to the escrow contract.

No. You can authenticate with a Bearer token (API key) issued at registration and never interact with a wallet at all. A wallet becomes useful if you want EIP-712 per-query spending caps, or if you need to recover access to your account using GET /v1/wallets/{addr}.

If you registered with an Ethereum wallet, you can recover your account by calling GET /v1/wallets/{addr} with your wallet address. The endpoint returns the account associated with that address. Without a linked wallet there is no recovery path, so agents are encouraged to link a wallet at registration.

Instead of a Bearer token, you can sign each request with an EIP-712 structured-data signature that encodes a spending cap for that query. The server verifies the signature and rejects any charge above the cap you signed. This gives agents trustless, per-query budget control without relying on the operator to honour a spending limit — the constraint is cryptographically enforced.

Yes. Microquery supports two x402 modes:

• x402 deposit (Mode 1): POST /v1/deposit with an X-PAYMENT header containing a signed EIP-3009 transferWithAuthorization. Auto-creates an account on first deposit and returns an API key. Use this when your agent wants a persistent balance without calling approve first.
• x402 per-query (Mode 2): Send an unauthenticated query to POST /query — the server returns HTTP 402 with an exact cost quote and a signed challenge. Re-send the request with an X-PAYMENT header to pay and run the query in one step. No pre-deposit or registration required.

For small or frequent queries the pre-deposit Bearer token path is more efficient: it avoids an extra round-trip and the minimum x402 payment amount is $0.01 (10,000 micro-USDC), whereas a typical query costs under $0.01. Use x402 per-query when your agent cannot hold a pre-funded balance or needs zero-setup access.

Microquery uses SnellerDB, which supports a PartiQL-compatible subset of SQL. Standard SELECT, WHERE, GROUP BY, ORDER BY, and aggregate functions work as expected. Features that require full ANSI SQL or procedural extensions are not available.

Dataset	Approximate size
NVD/CVE vulnerabilities	~5 GB
OSV open-source advisories	~400 MB
SEC EDGAR financials	~8 GB
PubMed abstracts	~350 GB
Ethereum token transfers	~1 TB

If a query does not include a LIMIT clause, Microquery automatically applies a limit of 1,000 rows and sets X-Microquery-Auto-Limit: 1000 in the response. There is no hard wall-clock timeout, but charges accumulate with bytes scanned, so unbounded full-table scans will consume balance proportionally.

Results are returned as Newline-Delimited JSON (NDJSON), with one JSON object per line. Cost and scan metadata are provided in the response headers rather than the body, so agents can parse results with a simple line-by-line reader.

No — and you should avoid it. Two queries with opposite WHERE predicates on the same table (e.g. WHERE to_address = X and WHERE from_address = X) each trigger a full partition scan, doubling the bytes scanned and doubling your cost. Combine them into one query with an OR filter and use a CASE expression inside COUNT(DISTINCT ...) to split the aggregation by direction:

SELECT CASE WHEN to_address = '0xABC' THEN 'in' ELSE 'out' END AS dir,
       token_address,
       COUNT(*)                                                   AS tx_count,
       COUNT(DISTINCT CASE WHEN to_address = '0xABC'
                           THEN from_address
                           ELSE to_address END)                   AS counterparties
FROM   transfers
WHERE  (from_address = '0xABC' OR to_address = '0xABC')
  AND  block_timestamp >= `2026-03-01T00:00:00Z`
  AND  block_timestamp <  `2026-04-01T00:00:00Z`
GROUP BY dir, token_address
ORDER BY dir, tx_count DESC
LIMIT 16

One scan, one charge. In Python, split on the dir field after the query returns. This pattern reduces data scanned and cost in proportion to the number of queries merged.

Yes. Any time your code fires two queries against the same table with complementary filters (sender = X / recipient = X, event_type = 'deposit' / event_type = 'withdrawal', etc.) you are scanning the same data twice. The fix is always the same: merge the predicates with OR and use CASE or GROUP BY on the distinguishing field to separate the results server-side.

Funds sit in an escrow smart contract on Base. The agent's wallet is the sole authorised withdrawer — the operator cannot move your deposited USDC without your signature. The operator deducts query charges against your balance, with on-chain settlement happening hourly.

Every query response includes the exact bytes scanned and the charge applied in its headers. Agents using EIP-712 auth embed a per-query spending cap in their signed payload, so the server cannot charge more than the agent explicitly authorised for that request. Bearer-token users can audit charges via the transaction history endpoint and correlate them against response headers.