# ToolMint Package Trust

> npm/PyPI trust pack: registry facts + OSV vulns + typosquat neighbors in one call.

- Status: Live
- Price: $0.005 / call (x402 exact, USDC on Base eip155:8453, payTo 0xfbF7413bcB3a604936775C96FDbe0b0C9c9E37F5)
- Base URL: https://toolmint-pkg-trust.toolmint.workers.dev
- OpenAPI: https://toolmint.toolmint.workers.dev/tools/pkg-trust-check/openapi.json

## Routes

- `GET /check` $0.005: Single package trust check (eco + name)
- `GET /check/{eco}/{name}` $0.005: Single package trust check by path
- `GET /batch` $0.005: Batch package trust (eco + names)

## What question it answers

"Is this package name safe enough to install, or should a person look at it first?" It is aimed at coding agents that might install a made-up name ("slopsquatting") or a typo of a popular one.

## When to use it

- Before `npm install` or `pip install` of a name an agent produced.
- To screen a short list of dependencies in one call (`/batch`).

## When not to use it

- As a security audit. It is a heuristic, not Socket, Snyk or a full software-composition scan. It reads registry metadata and OSV only. It does not read the package code.
- To check the version you already have. OSV is queried for the **latest** version only; there is no `version` parameter yet.
- For private packages or other ecosystems (only `npm` and `pypi`).

## Example

```bash
curl -i "https://toolmint-pkg-trust.toolmint.workers.dev/check?eco=npm&name=lodash"
# 402 + PAYMENT-REQUIRED header. Pay with an x402 client and repeat with PAYMENT-SIGNATURE.
```

Response after payment (trimmed; the values for lodash are from the package folder's sample file, the rest of the shape is from the Worker code):

```json
{
  "tool": "pkg-trust-check",
  "version": "0.1.0",
  "ecosystem": "npm",
  "name": "lodash",
  "disclaimer": "Heuristic only - not a substitute for Socket/Snyk/enterprise SCA. Free public registry + OSV inputs. No fabricated data.",
  "licensing": { "npm": "...", "pypi": "...", "osv": "..." },
  "sources": [
    "https://registry.npmjs.org/lodash",
    "https://api.npmjs.org/downloads/point/last-month/lodash",
    "https://api.osv.dev/v1/query"
  ],
  "fetchedAt": "2026-10-31T17:00:00.000Z",
  "trustScore": 80,
  "exists": true,
  "latest": "4.18.1",
  "lastPublish": "2026-04-01T21:01:20.458Z",
  "description": "Lodash modular utilities.",
  "deprecated": null,
  "license": "MIT",
  "maintainers": ["jdalton"],
  "downloadHint": "636183624 downloads last-month",
  "typoNeighbors": [],
  "vulns": [],
  "verdict": "allow",
  "reasons": ["exists on registry; no red flags in cheap checks"],
  "registryError": null,
  "osvError": null
}
```

`verdict` meanings: `allow` = no red flags in the cheap checks; `review` = a person should look (vulnerabilities, deprecated, very new or old, close to a popular name, or an upstream lookup failed); `block` = a `MAL-` malware advisory, or a missing package whose name is within 2 edits of a popular one. `vulns` shows at most 10 entries and no total.

## Data sources and licence

registry.npmjs.org and api.npmjs.org (npm registry metadata and download counts, subject to npm's terms), pypi.org (PyPI JSON API), api.osv.dev (OSV.dev vulnerability data, open). Package licences vary and are reported as found. Check each source's terms if you redistribute.

## Freshness and limits

- Results are cached up to 6 hours per package in memory on one server instance. A cache hit returns the stored object, so `fetchedAt` shows the original fetch time. Registry failures are not cached.
- Typosquat check compares against a built-in list of 30 popular npm and 20 popular PyPI names, distance 1 or 2. It will miss typos of any other package.
- `downloadHint` is npm only.
- `/batch` checks packages one after another; large batches are slower.
- If it runs out, paid calls fail and are not charged.