Databroker MCP Server

Mossforge DataBroker

Pay-per-call UK data and utility API, gated by x402 micropayments on Base mainnet. No API keys, no accounts, no subscriptions — send a signed USDC payment with your HTTP request and get an answer back in the same response cycle.

• Base URL: https://api.databroker.mossforge.dev
• Network: Base mainnet (eip155:8453)
• Payment token: USDC
• Protocol: x402, exact scheme
• Landing / docs: databroker.mossforge.dev · llms.txt · openapi.yaml

Quick start

curl https://api.databroker.mossforge.dev/v1/discover

/v1/discover is free and returns every enabled dataset with its current price, description, and provenance (kind, implemented standard, deterministic, data_source). Prices are configured server-side and can change — always trust the live 402 challenge over anything written in this README.

Requesting any paid route without payment returns HTTP 402 with the exact amount, recipient, and network in a PAYMENT-REQUIRED header. Sign an EIP-3009 USDC transfer authorization, retry with a PAYMENT-SIGNATURE header, and the API verifies, settles on-chain, and returns the data with a PAYMENT-RESPONSE receipt. A 402 means no funds have moved — you only pay on a 200.

x402 client libraries: @coinbase/x402-fetch (TypeScript), x402 (Python), x402-go (Go).

Use it from an agent

MCP server

@mossforge/databroker-mcp gives any MCP client (Claude Desktop, Claude Code, Cursor) pay-per-call access to everything below, with x402 payment handled for it. No build step:

{
  "mcpServers": {
    "databroker": {
      "command": "npx",
      "args": ["-y", "@mossforge/databroker-mcp"],
      "env": {
        "DATABROKER_BASE_URL": "https://api.databroker.mossforge.dev",
        "DATABROKER_WALLET_KEY": "0x...",
        "DATABROKER_MAX_USDC": "0.50"
      }
    }
  }
}

Or for Claude Code:

claude mcp add --transport stdio \
  --env DATABROKER_BASE_URL=https://api.databroker.mossforge.dev \
  --env DATABROKER_WALLET_KEY=0x... \
  databroker -- npx -y @mossforge/databroker-mcp

Payment is never automatic. databroker_fetch and databroker_batch_create return a price quote first and spend nothing until called again with confirm: true enforced in the server, not left to the model's judgement. Every paid call is additionally capped by DATABROKER_MAX_USDC; anything priced above the cap is declined before payment. See mcp-server/ for signer options (self-custodied key or Coinbase CDP) and security notes.

Agent skills

Three OpenClaw skills in skills/, scoped by tier - mossforge-mot-history (single vehicle), mossforge-mot-analytics (fleet statistics), mossforge-data-utilities (24 identifier/geo/reference endpoints).

Direct HTTP

Worked examples in examples/ for Python and TypeScript, both as a plain fetch and as an agent tool definition.

Endpoints

All paid routes follow the same shape: GET /v1/{dataset_id}/{key}. Keys are URL-decoded server-side, so percent-encode anything containing /, spaces, or + (e.g. 205/55R16 91V → /v1/util-tyre-size/205%2F55R16%2091V).

Free routes

Cached datasets

Stored datasets backed by ingestion pipelines, with full freshness semantics (ttl_seconds, stale, free /meta checks).

Analytics keys are colon-delimited and family-specific:

Age bands: 0-3yr, 3-5yr, 5-8yr, 8-12yr, 12yr+. Fuels: petrol, diesel, electric, hybrid, other. Derived rates are suppressed to null (with lowSample: true) when the underlying sample is below minN, so small segments never yield misleadingly precise numbers.

Computed utilities — $0.001 per call

Pure deterministic functions exposed as paid endpoints. The same key always returns the same answer, forever — responses carry deterministic: true, so cache them client-side indefinitely. Every response names the standard it implements. Malformed keys are rejected with a free 400 before payment; for validators, valid: false is a legitimate paid answer — you pay for the verdict, not for the verdict being yes.

Bundled reference lookups — $0.002 per call

Lookups against static reference-data snapshots shipped with the service, refreshed on a cadence. Responses carry deterministic: false, ttl_seconds matching the refresh cadence, and data_generated_at naming the snapshot date; /v1/discover names the upstream data_source.

Response envelope

Every successful paid response shares one envelope:

{
  "dataset": "util-iban",
  "key": "GB82WEST12345698765432",
  "data": { "...endpoint-specific..." },
  "fetched_at": "2026-07-05T12:00:00.000Z",
  "fetch_status": "ok",
  "source": "ISO 13616 / ISO 7064 MOD 97-10",
  "ttl_seconds": 315360000,
  "stale": false,
  "deterministic": true
}

For cached datasets, ttl_seconds/stale reflect real cache state and source names the upstream. For computed utilities, ttl_seconds is a 10-year sentinel (the answer never expires) and source names the standard. For bundled utilities, source names the snapshot's data source. The deterministic field appears on utility responses only.

Errors

Errors return a structured body with a stable machine-readable code — branch on code, never on message text:

{
  "error": {
    "code": "INGEST_IN_PROGRESS",
    "message": "…",
    "retryable": true,
    "retry_after_seconds": 3,
    "docs_url": "…"
  }
}

Utility routes additionally return a plain 400 for malformed keys before any payment is taken — the message states the expected key format. Fix the key and retry; no funds have moved.

Notes for agent developers

• Call /v1/discover before constructing a payment — prices can change without a redeploy.
• Use the free /meta route to check cache freshness before paying twice for the same cached lookup. Computed utility results never need a re-check: cache them forever.
• ENTITY_NOT_FOUND and valid: false are final answers, not failures. Don't retry them.
• There is no authentication and no provisioning — a funded Base wallet is the only prerequisite.
• Agent-readable docs: /llms.txt. OpenClaw skills for the MOT history, MOT analytics, and utilities tiers live alongside this repo.

Contact

support@mossforge.dev · Built by Mossforge · Powered by x402 on Base