Quick Start

Base URL: https://microquery.dev  ·  All amounts in micro-USDC (1 USDC = 1,000,000 micro-USDC).

# 1. Register — receive 5,000 micro-USDC free trial credit
curl -X POST https://microquery.dev/v1/register \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "wallet_addr": "0xYOUR_WALLET"}'
# → { "id": "...", "api_key": "...", "balance": 5000 }

# 2. Query
curl -G https://microquery.dev/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "database=nvd" \
  --data-urlencode "query=SELECT id, description FROM cve WHERE cvss_score > 9 LIMIT 5"
# → ndjson rows + X-Microquery-Cost-MicroUSDC and X-Microquery-Balance-MicroUSDC headers

Agent Quickstart

GET /v1/agent-quickstart — public, no authentication required.

Returns a self-contained JSON document designed to be injected directly into an agent's context. An agent that reads this response can register, run its first query, and deposit funds without consulting any external documentation.

curl https://microquery.dev/v1/agent-quickstart

The response includes: service, base_url, registration (endpoint + fields), authentication (Bearer and EIP-712), query (endpoint + parameters), first_query (ready-to-run SQL), pricing, deposit (chain + contract + steps), and datasets (each with example SQL).

Registration

POST /v1/register — public, no authentication required.

// Response 201 Created
{
  "id":          "acct_...",
  "api_key":     "abc123...",  // shown once — store securely
  "name":        "my-agent",
  "balance":     5000,         // free trial credit in micro-USDC
  "wallet_addr": "0x...",
  "first_query": {
    "database": "nvd",
    "sql":      "SELECT id, description FROM cve WHERE cvss_score > 9 LIMIT 3",
    "note":     "Trial balance covers ~1,600 typical queries"
  },
  "deposit_instructions": {
    "chain":              "Base",
    "token":              "USDC",
    "minimum_micro_usdc": 500000,
    "steps": ["1. Approve escrow...", "2. Deposit..."]
  },
  "quickstart_url": "https://microquery.dev/v1/agent-quickstart"
}

Authentication

Bearer token (API key)

Authorization: Bearer YOUR_API_KEY

EIP-712 signed authorization

Recommended for autonomous agents. Binds the authorization to a specific query and a per-query spending cap — the agent controls exactly how much it can be charged.

Authorization: EIP712 BASE64_ENCODED_PAYLOAD

// Payload (base64-encoded JSON)
{
  "consumer":   "0xYOUR_WALLET",
  "max_cost":   "5000",      // hard cap in micro-USDC
  "database":   "nvd",
  "query_hash": "0x...",     // SHA-256 of the query string
  "nonce":      1,
  "deadline":   1234567890,  // unix timestamp
  "signature":  "0x..."
}

Querying

GET /query or POST /query

Response is newline-delimited JSON (application/x-ndjson), one object per row.

Response headers

Status codes

Cost Estimation

GET /v1/estimate or POST /v1/estimate — authenticated, free (no charge deducted).

Returns the estimated maximum bytes that would be scanned and the corresponding cost, without executing the query. Useful for checking affordability or comparing query variants before committing.

Parameters

Example

curl -G https://microquery.dev/v1/estimate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "database=pubmed" \
  --data-urlencode "query=SELECT * FROM baseline WHERE MedlineCitation.Article.ArticleTitle ~ 'CRISPR'"

Response

{
  "database": "pubmed",
  "estimated_bytes_scanned": 53687091200,
  "estimated_cost_micro_usdc": 7500
}

The estimated_bytes_scanned value is a conservative upper bound from the Sneller query planner — actual scan size at execution time will be equal or lower.

Pricing

150 micro-USDC per GiB decompressed bytes scanned — approximately $0.15 / TB.

• Trial credit: 5,000 micro-USDC on every new account (no deposit needed)
• Minimum deposit: 500,000 micro-USDC (0.5 USDC)

# Current rate
GET /v1/pricing

// Response
{ "micro_usdc_per_gib": 150 }

Databases

GET /v1/databases returns available databases and table schemas.

Deposits

On-chain via escrow (recommended)

// 1. Approve the escrow contract
IERC20(USDC).approve(ESCROW_ADDRESS, amount);

// 2. Deposit — minimum 500,000 (0.5 USDC)
MicroqueryEscrow(ESCROW_ADDRESS).deposit(amount);

Contract address published at launch. Base USDC: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

Account Management

Linking a wallet

Ownership is verified via a challenge/response before the address is stored.

Step 1 — request a nonce:

POST /v1/wallet-challenge
{ "wallet_addr": "0xYOUR_WALLET" }

// Response:
{ "nonce": "a3f1c8...", "message": "microquery wallet verification\nnonce: a3f1c8...", "expires_in": 300 }

Step 2 — sign the message with eth_personalSign (MetaMask, signer.signMessage() in ethers.js, eth.sign() in web3.py), then submit:

POST /v1/accounts/{id}/link-wallet
{ "wallet_addr": "0xYOUR_WALLET", "nonce": "a3f1c8...", "signature": "0x..." }

The nonce expires after 5 minutes and is single-use.

Rate Limits