x402 query API

The index answers HTTP requests. A free endpoint returns previews; the paid endpoint returns full chunks after an x402 payment. Agents need USDG on Robinhood Chain (chain 4663) and no ETH: the payment is a signature.

Free preview

GET /api/search?q=your+question

{ "hits": [ { "dataset", "title", "owner", "chunk", "score", "snippet" } ] }

Paid query

Call GET /api/x402/query?q=… (or POST with { "query": "…" }). Without a payment the API answers 402:

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:4663",
    "maxAmountRequired": "10000",          // 0.01 USDG, 6 decimals
    "asset": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
    "payTo": "0x406A19Cf933866e7087c4d4973D330F5350282e5",
    "maxTimeoutSeconds": 604800,
    "extra": { "name": "Global Dollar", "version": "1", "settlement": "batched", "minValidSeconds": 21600 }
  }]
}

Sign an EIP-712 TransferWithAuthorization on the USDG domain (name Global Dollar, version 1, chain 4663, verifying contract USDG) from your address to payTo for at least the price, with validBefore at least six hours ahead and a random 32-byte nonce. Base64 the payload and retry with the X-PAYMENT header:

{
  "x402Version": 1, "scheme": "exact", "network": "eip155:4663",
  "payload": {
    "signature": "0x…",
    "authorization": { "from", "to", "value", "validAfter", "validBefore", "nonce" }
  }
}

The API checks the signature, the amount, the window, that the nonce is unused on chain and that your USDG balance covers this and your other queued authorizations. It then returns the chunks with an X-PAYMENT-RESPONSE header (settlement: queued).

Response

{
  "query": "…", "paid": "0.01", "payer": "0x…", "settlement": "queued",
  "chunks": [ { "dataset", "title", "heading", "chunk", "score", "owner", "node", "license", "text" } ],
  "split": { "owners": { "0x…": "units" }, "nodes": { "0x…": "units" }, "stake": "units" }
}

Settlement

The keeper submits queued authorizations in one settleBatch transaction to the payouts contract every 30 minutes. An authorization that fails on chain (moved funds, expired) is dropped and its split is reversed from the ledger. See accounting and claims.

Other endpoints