{ "markdown": "# Mossforge DataBroker\n\nPay-per-call UK data and utility API, gated by [x402](https://x402.org) micropayments on Base\nmainnet. No API keys, no accounts, no subscriptions — send a signed USDC payment with your HTTP\nrequest and get an answer back in the same response cycle.\n\n- **Base URL:** `https://api.databroker.mossforge.dev`\n- **Network:** Base mainnet (`eip155:8453`)\n- **Payment token:** USDC\n- **Protocol:** x402, `exact` scheme\n- **Landing / docs:** [databroker.mossforge.dev](https://databroker.mossforge.dev) ·\n [llms.txt](https://databroker.mossforge.dev/llms.txt) ·\n [openapi.yaml](https://databroker.mossforge.dev/openapi.yaml)\n\n## Quick start\n\n```bash\ncurl https://api.databroker.mossforge.dev/v1/discover\n```\n\n`/v1/discover` is free and returns every enabled dataset with its current price, description,\nand provenance (`kind`, implemented `standard`, `deterministic`, `data_source`). Prices are\nconfigured server-side and can change — always trust the live `402` challenge over anything\nwritten in this README.\n\nRequesting any paid route without payment returns `HTTP 402` with the exact amount, recipient,\nand network in a `PAYMENT-REQUIRED` header. Sign an EIP-3009 USDC transfer authorization, retry\nwith a `PAYMENT-SIGNATURE` header, and the API verifies, settles on-chain, and returns the data\nwith a `PAYMENT-RESPONSE` receipt. **A 402 means no funds have moved — you only pay on a 200.**\n\nx402 client libraries: [`@x402/fetch`](https://www.npmjs.com/package/@x402/fetch)\n(TypeScript), [`x402`](https://pypi.org/project/x402/) (Python),\n[`x402-go`](https://github.com/coinbase/x402-go) (Go).\n\n## Use it from an agent\n\n### MCP server\n\n`@mossforge/databroker-mcp` gives any MCP client (Claude Desktop, Claude Code, Cursor)\npay-per-call access to everything below, with x402 payment handled for it. No build step:\n\n```json\n{\n \"mcpServers\": {\n \"databroker\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@mossforge/databroker-mcp\"],\n \"env\": {\n \"DATABROKER_BASE_URL\": \"https://api.databroker.mossforge.dev\",\n \"DATABROKER_WALLET_KEY\": \"0x...\",\n \"DATABROKER_MAX_USDC\": \"0.50\"\n }\n }\n }\n}\n```\n\nOr for Claude Code:\n\n```bash\nclaude mcp add --transport stdio \\\n --env DATABROKER_BASE_URL=https://api.databroker.mossforge.dev \\\n --env DATABROKER_WALLET_KEY=0x... \\\n databroker -- npx -y @mossforge/databroker-mcp\n```\n\n**Payment is never automatic.** `databroker_fetch` and `databroker_batch_create` return a\nprice quote first and spend nothing until called again with `confirm: true`\nenforced in the server, not left to the model's judgement. Every paid call is additionally\ncapped by `DATABROKER_MAX_USDC`; anything priced above the cap is declined before payment.\nSee [`mcp-server/`](./mcp-server) for signer options (self-custodied key or Coinbase CDP)\nand security notes.\n\n### Agent skills\n\nThree OpenClaw skills in [`skills/`](./skills), scoped by tier - `mossforge-mot-history`\n(single vehicle), `mossforge-mot-analytics` (fleet statistics), `mossforge-data-utilities`\n(24 identifier/geo/reference endpoints).\n\n### Direct HTTP\n\nWorked examples in [`examples/`](./examples) for Python and TypeScript, both as a plain\nfetch and as an agent tool definition.\n\n## Endpoints\n\nAll paid routes follow the same shape: `GET /v1/{dataset_id}/{key}`. Keys are URL-decoded\nserver-side, so percent-encode anything containing `/`, spaces, or `+`\n(e.g. `205/55R16 91V` → `/v1/util-tyre-size/205%2F55R16%2091V`).\n\n### Free routes\n\n| Route | Description |\n| ------------------------------ | ----------------------------------------------------------------------------------------------------------------- |\n| `GET /v1/health` | Uptime check |\n| `GET /v1/discover` | All enabled datasets, current prices, provenance |\n| `GET /v1/{dataset}/{key}/meta` | Cache freshness for cached datasets; kind/standard/determinism info for utilities. Never returns the data payload |\n\n### Cached datasets\n\nStored datasets backed by ingestion pipelines, with full freshness semantics (`ttl_seconds`,\n`stale`, free `/meta` checks).\n\n| Dataset | Route | Price | Description |\n| ------------------ | ---------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 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) |\n| 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 |\n\nAnalytics keys are colon-delimited and family-specific:\n\n| Family | Key format | Example | Returns |\n| ----------- | ----------------------------------- | ------------------------ | ------------------------------------------------------------------------------- |\n| reliability | `reliability:` | `reliability:ford` | Pass rates by age and mileage band, first-time pass rate, dangerous defect rate |\n| mileage | `mileage::` | `mileage:ford:5-8yr` | Average annual mileage, percentile distribution, odometer clocking rate |\n| parc | `parc:::` | `parc:ford:diesel:5-8yr` | Fleet population counts and recent testing activity |\n| fuelmix | `fuelmix:` | `fuelmix:2019` | Fuel type distribution for a registration year |\n| colour | `colour::` | `colour:ford:2019` | Top colours for a make/year |\n| temporal | `temporal` | `temporal` | UK-wide test volume, pass rate, expiry density by month |\n\nAge bands: `0-3yr`, `3-5yr`, `5-8yr`, `8-12yr`, `12yr+`. Fuels: `petrol`, `diesel`, `electric`,\n`hybrid`, `other`. Derived rates are suppressed to `null` (with `lowSample: true`) when the\nunderlying sample is below `minN`, so small segments never yield misleadingly precise numbers.\n\n### Computed utilities — $0.001 per call\n\nPure deterministic functions exposed as paid endpoints. The same key always returns the same\nanswer, forever — responses carry `deterministic: true`, so cache them client-side indefinitely.\nEvery response names the standard it implements. Malformed keys are rejected with a free `400`\nbefore payment; for validators, `valid: false` is a legitimate _paid_ answer — you pay for the\nverdict, not for the verdict being yes.\n\n| Dataset | Key | Returns |\n| ----------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |\n| `util-vin` | 17-char VIN | Structure validation, NA check digit, WMI region/manufacturer, model year candidates (ISO 3779/3780, FMVSS 565) |\n| `util-uk-plate` | UK registration plate | Format era, area code, age identifier, registration period (DVLA formats) |\n| `util-mot-due` | `YYYY-MM-DD` first-registration date | First MOT due date, now-due flag, 40-year historic exemption (GB MOT rules) |\n| `util-tyre-size` | e.g. `205/55R16 91V` (encoded) | Dimensions, overall diameter, load index → kg, speed rating → km/h (ETRTO) |\n| `util-iban` | IBAN | Per-country length + MOD 97-10 validity, country/BBAN parse (ISO 13616) |\n| `util-isin` | ISIN | Validity, country prefix, NSIN, Luhn check digit (ISO 6166) |\n| `util-cusip` | CUSIP | Validity, issuer/issue split, mod-10 with `*` `@` `#` (ANSI X9.6) |\n| `util-sedol` | SEDOL | Validity, weighted mod-10 check digit (LSE) |\n| `util-lei` | LEI | Validity, MOD 97-10 check digits (ISO 17442) |\n| `util-card` | Card number | Luhn validity + network detection by public prefix rules — structural only, not a BIN lookup (ISO/IEC 7812) |\n| `util-aba-rtn` | 9-digit routing number | Validity, 3-7-1 weighted mod-10 (ABA) |\n| `util-gtin` | GTIN-8/12/13/14, or `compute:` | Validity + type; compute mode returns check digit and full code (GS1) |\n| `util-isbn` | ISBN-10 or ISBN-13 | Validity + bidirectional 10↔13 conversion (ISO 2108) |\n| `util-issn` | 8-char ISSN | Validity, weighted mod-11 check character (ISO 3297) |\n| `util-container` | e.g. `MSKU3068821` | Owner code, category, serial, check digit (ISO 6346) |\n| `util-imo` | 7-digit IMO number | Validity, weighted check digit (IMO scheme) |\n| `util-checkdigit` | `::` | Verify → valid; compute → check digit + full value |\n| `util-geo` | `distance:lat1,lon1,lat2,lon2` or `destination:lat,lon,bearing,km` | Great-circle km/mi/nm + bearing, or destination point (haversine) |\n| `util-geohash` | `encode:lat,lon[,precision]` or `decode:` | Geohash string, or centre + bounding box |\n\n### Bundled reference lookups — $0.002 per call\n\nLookups against static reference-data snapshots shipped with the service, refreshed on a\ncadence. Responses carry `deterministic: false`, `ttl_seconds` matching the refresh cadence,\nand `data_generated_at` naming the snapshot date; `/v1/discover` names the upstream `data_source`.\n\n| Dataset | Key | Returns | Refresh |\n| --------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------ | --------- |\n| `util-oui` | MAC or OUI prefix (`00:00:5E`) | Vendor name/country (IEEE OUI registry); flags locally-administered/multicast addresses | ~30 days |\n| `util-airport` | `LHR`, `EGLL`, `iata:LHR`, `icao:EGLL` | Name, coordinates, elevation, country, municipality, scheduled service (OurAirports) | ~30 days |\n| `util-tz` | `zone:Europe/London[:2026-01-15]` or `country:GB` | UTC offset at a moment, DST status, abbreviation; or country zone list (IANA tzdb + runtime ICU) | ~90 days |\n| `util-currency` | `GBP` or `826` | Name, minor units, using entities, withdrawn-code history (ISO 4217) | ~90 days |\n| `util-locode` | `GBLON` or `GB:LON` | Place name, subdivision, function classifiers, coordinates (UNECE Rec 16) | ~180 days |\n\n## Response envelope\n\nEvery successful paid response shares one envelope:\n\n```json\n{\n \"dataset\": \"util-iban\",\n \"key\": \"GB82WEST12345698765432\",\n \"data\": { \"...endpoint-specific...\" },\n \"fetched_at\": \"2026-07-05T12:00:00.000Z\",\n \"fetch_status\": \"ok\",\n \"source\": \"ISO 13616 / ISO 7064 MOD 97-10\",\n \"ttl_seconds\": 315360000,\n \"stale\": false,\n \"deterministic\": true\n}\n```\n\nFor cached datasets, `ttl_seconds`/`stale` reflect real cache state and `source` names the\nupstream. For computed utilities, `ttl_seconds` is a 10-year sentinel (the answer never\nexpires) and `source` names the standard. For bundled utilities, `source` names the snapshot's\ndata source. The `deterministic` field appears on utility responses only.\n\n## Errors\n\nErrors return a structured body with a stable machine-readable `code` — branch on `code`, never\non `message` text:\n\n```json\n{\n \"error\": {\n \"code\": \"INGEST_IN_PROGRESS\",\n \"message\": \"…\",\n \"retryable\": true,\n \"retry_after_seconds\": 3,\n \"docs_url\": \"…\"\n }\n}\n```\n\n| Code | Status | Retryable | Meaning |\n| --------------------------- | ------ | --------- | ------------------------------------------------------------------- |\n| `PAYMENT_INVALID` | 402 | yes | Re-sign from a fresh 402 challenge and retry |\n| `PAYMENT_SETTLEMENT_FAILED` | 402 | yes | On-chain settlement failed; retry |\n| `UNKNOWN_DATASET` | 404 | no | Not a recognised dataset — see `/v1/discover` |\n| `ENTITY_NOT_FOUND` | 404 | no | Final result: no record exists (e.g. no MOT history for that plate) |\n| `INGEST_IN_PROGRESS` | 503 | yes | Live fetch in flight — wait `retry_after_seconds` |\n| `BUCKET_NOT_SEEDED` | 404 | yes | Analytics pipeline hasn't populated this segment yet |\n\nUtility routes additionally return a plain `400` for malformed keys **before any payment is\ntaken** — the message states the expected key format. Fix the key and retry; no funds have moved.\n\n## Notes for agent developers\n\n- Call `/v1/discover` before constructing a payment — prices can change without a redeploy.\n- Use the free `/meta` route to check cache freshness before paying twice for the same cached\n lookup. Computed utility results never need a re-check: cache them forever.\n- `ENTITY_NOT_FOUND` and `valid: false` are final answers, not failures. Don't retry them.\n- There is no authentication and no provisioning — a funded Base wallet is the only prerequisite.\n- Agent-readable docs: [`/llms.txt`](https://databroker.mossforge.dev/llms.txt). OpenClaw skills\n for the MOT history, MOT analytics, and utilities tiers live alongside this repo.\n\n## Contact\n\n[support@mossforge.dev](mailto:support@mossforge.dev) · Built by [Mossforge](https://mossforge.dev) ·\nPowered by [x402](https://x402.org) on [Base](https://base.org)\n", "bytes": 16609, "sha": "b9f44d9e34dbd0367d6fc9d206fde56e1526595e44931134a9c3354650fc3851", "repo_slug": "mossforge/databroker", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_dev_mossforge_databroker_2c745b93/readme" }