databroker

# Mossforge DataBroker

Pay-per-call UK data and utility API, gated by [x402](https://x402.org) 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](https://databroker.mossforge.dev) ·
  [llms.txt](https://databroker.mossforge.dev/llms.txt) ·
  [openapi.yaml](https://databroker.mossforge.dev/openapi.yaml)

## Quick start

```bash
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`](https://www.npmjs.com/package/@coinbase/x402-fetch)
(TypeScript), [`x402`](https://pypi.org/project/x402/) (Python),
[`x402-go`](https://github.com/coinbase/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:

```json
{
  "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:

```bash
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/`](./mcp-server) for signer options (self-custodied key or Coinbase CDP)
and security notes.

### Agent skills

Three OpenClaw skills in [`skills/`](./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/`](./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

| Route                          | Description                                                                                                       |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `GET /v1/health`               | Uptime check                                                                                                      |
| `GET /v1/discover`             | All enabled datasets, current prices, provenance                                                                  |
| `GET /v1/{dataset}/{key}/meta` | Cache freshness for cached datasets; kind/standard/determinism info for utilities. Never returns the data payload |

### Cached datasets

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

| Dataset            | Route                              | Price  | Description                                                                                                                                                                                             |
| ------------------ | ---------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DVSA MOT history   | `GET /v1/dvsa-mot/{registration}`  | $0.005 | Full MOT test history for a UK vehicle — vehicle details, pass/fail summary, mileage, individual test records with defects. Cached 30 days; first-ever lookup for a plate triggers a live fetch (2-4 s) |
| DVSA MOT analytics | `GET /v1/dvsa-mot-analytics/{key}` | $0.02  | Aggregated MOT statistics by vehicle segment — pass rates, top defects, mileage percentiles, clocking rates, fuel mix, colour distribution. Refreshed daily from the full DVSA bulk dataset             |

Analytics keys are colon-delimited and family-specific:

| Family      | Key format                          | Example                  | Returns                                                                         |
| ----------- | ----------------------------------- | ------------------------ | ------------------------------------------------------------------------------- |
| reliability | `reliability:<make>`                | `reliability:ford`       | Pass rates by age and mileage band, first-time pass rate, dangerous defect rate |
| mileage     | `mileage:<make>:<band_or_year>`     | `mileage:ford:5-8yr`     | Average annual mileage, percentile distribution, odometer clocking rate         |
| parc        | `parc:<make>:<fuel>:<band_or_year>` | `parc:ford:diesel:5-8yr` | Fleet population counts and recent testing activity                             |
| fuelmix     | `fuelmix:<year>`                    | `fuelmix:2019`           | Fuel type distribution for a registration year                                  |
| colour      | `colour:<make>:<year>`              | `colour:ford:2019`       | Top colours for a make/year                                                     |
| temporal    | `temporal`                          | `temporal`               | UK-wide test volume, pass rate, expiry density by month                         |

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.

| Dataset           | Key                                                                    | Returns                                                                                                         |
| ----------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `util-vin`        | 17-char VIN                                                            | Structure validation, NA check digit, WMI region/manufacturer, model year candidates (ISO 3779/3780, FMVSS 565) |
| `util-uk-plate`   | UK registration plate                                                  | Format era, area code, age identifier, registration period (DVLA formats)                                       |
| `util-mot-due`    | `YYYY-MM-DD` first-registration date                                   | First MOT due date, now-due flag, 40-year historic exemption (GB MOT rules)                                     |
| `util-tyre-size`  | e.g. `205/55R16 91V` (encoded)                                         | Dimensions, overall diameter, load index → kg, speed rating → km/h (ETRTO)                                      |
| `util-iban`       | IBAN                                                                   | Per-country length + MOD 97-10 validity, country/BBAN parse (ISO 13616)                                         |
| `util-isin`       | ISIN                                                                   | Validity, country prefix, NSIN, Luhn check digit (ISO 6166)                                                     |
| `util-cusip`      | CUSIP                                                                  | Validity, issuer/issue split, mod-10 with `*` `@` `#` (ANSI X9.6)                                               |
| `util-sedol`      | SEDOL                                                                  | Validity, weighted mod-10 check digit (LSE)                                                                     |
| `util-lei`        | LEI                                                                    | Validity, MOD 97-10 check digits (ISO 17442)                                                                    |
| `util-card`       | Card number                                                            | Luhn validity + n