API Reference

# 1. Register — get an API key and $0.10 free trial credit
curl -X POST https://microquery.dev/v1/register \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent"}'
# → { "id": "...", "api_key": "a3f1b2c9...", "balance": 100000 }

# 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

// Response 201 Created
{
  "id":          "acct_...",
  "api_key":     "abc123...",  // shown once — store securely
  "name":        "my-agent",
  "balance":     100000,       // 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 all example scripts"
  },
  "deposit_instructions": {
    "chain":              "Base",
    "token":              "USDC",
    "minimum_micro_usdc": 250000,
    "endpoint":           "POST /v1/deposit",
    "method":             "EIP-2612 permit: sign permit off-chain, send amount+deadline+v+r+s with Bearer auth",
    "docs_url":           "https://microquery.dev/docs.md#deposits"
  },
  "quickstart_url": "https://microquery.dev/v1/agent-quickstart"
}

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

Authorization: Bearer YOUR_API_KEY

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

# Current rate
GET /v1/pricing

// Response
{ "micro_usdc_per_gib": 150 }

// GET /v1/databases
{
  "databases": [
    {
      "name": "pubmed",
      "tables": [
        {
          "name": "baseline",
          "fields": ["MedlineCitation.PMID", "..."],
          "partitioning": {
            "key": "pub_year", "type": "int",
            "total_bytes": 137737797632,
            "updated_at": "2026-04-15T18:17:35Z"
          }
        }
      ]
    }
  ],
  "_hint": "Add ?partitions=true to include per-partition byte breakdown for each table."
}

import { ethers } from "ethers";

// Generate once, store the private key securely
const wallet = ethers.Wallet.createRandom();
console.log("address:     ", wallet.address);
console.log("private_key: ", wallet.privateKey);

// Load at startup
const wallet = new ethers.Wallet(process.env.AGENT_PRIVATE_KEY);

POST /v1/deposit
Authorization: Bearer YOUR_API_KEY

{
  "amount":   1000000,   // micro-USDC (minimum 250000 = 0.25 USDC)
  "deadline": 1234567890, // Unix timestamp
  "v": 27, "r": "0x...", "s": "0x..."
}

// Response:
{ "tx_hash": "0x...", "amount": 1000000, "balance": 1005000, "transaction_id": "..." }

POST /v1/deposit
X-PAYMENT: <base64url-encoded x402 JSON>
Content-Type: application/json

{}

// First deposit — 201 Created:
{ "api_key": "...", "balance_micro_usdc": 250000, "transaction": "0x...", "network": "base" }

// Top-up — 200 OK:
{ "balance_micro_usdc": 1000000, "transaction": "0x...", "network": "base" }

# POST without auth — returns HTTP 402 with the challenge
curl -s -X POST "https://microquery.dev/query?database=defi" \
  -H "Content-Type: text/plain" \
  --data "SELECT name, tvl FROM protocols ORDER BY tvl DESC LIMIT 5"

// 402 response:
{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact", "network": "base",
    "maxAmountRequired": "10000",
    "payTo": "0x5da586b29c3bb0f86cf820b9ac4331b289a6e50b",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "maxTimeoutSeconds": 60
  }]
}

import base64, json, secrets, time
from eth_account import Account
from eth_account.messages import encode_typed_data

amount    = int(challenge["accepts"][0]["maxAmountRequired"])
pay_to    = challenge["accepts"][0]["payTo"]
usdc_addr = challenge["accepts"][0]["asset"]

acct  = Account.from_key(PRIVATE_KEY)
nonce = "0x" + secrets.token_hex(32)
signed = acct.sign_message(encode_typed_data(full_message={
    "types": {
        "EIP712Domain": [
            {"name": "name", "type": "string"}, {"name": "version", "type": "string"},
            {"name": "chainId", "type": "uint256"}, {"name": "verifyingContract", "type": "address"},
        ],
        "TransferWithAuthorization": [
            {"name": "from", "type": "address"}, {"name": "to", "type": "address"},
            {"name": "value", "type": "uint256"}, {"name": "validAfter", "type": "uint256"},
            {"name": "validBefore", "type": "uint256"}, {"name": "nonce", "type": "bytes32"},
        ],
    },
    "domain": {"name": "USD Coin", "version": "2", "chainId": 8453, "verifyingContract": usdc_addr},
    "primaryType": "TransferWithAuthorization",
    "message": {
        "from": acct.address, "to": pay_to, "value": amount,
        "validAfter": 0, "validBefore": int(time.time()) + 300, "nonce": nonce,
    },
}))
payload = {
    "x402Version": 1, "scheme": "exact", "network": "base",
    "payload": {
        "signature": "0x" + signed.signature.hex(),
        "authorization": {
            "from": acct.address, "to": pay_to, "value": str(amount),
            "validAfter": "0", "validBefore": str(int(time.time()) + 300), "nonce": nonce,
        },
    },
}
x_payment = base64.urlsafe_b64encode(json.dumps(payload).encode()).decode().rstrip("=")

import requests
resp = requests.post(
    "https://microquery.dev/query?database=defi",
    headers={"Content-Type": "text/plain", "X-PAYMENT": x_payment},
    data="SELECT name, tvl FROM protocols ORDER BY tvl DESC LIMIT 5",
)
# resp.status_code == 200; NDJSON rows in resp.text
# resp.headers["X-Payment-Transaction"]  — on-chain tx hash
# resp.headers.get("X-Payment-Account-Key")  — api_key (first payment only)