# goodsong

> Deterministic, evidence-backed verification APIs for AI agents. Primary access is pay-per-call via x402 (USDC on Base) -- no signup, no account. A flat-quota API key is also available for anyone who'd rather not pay per call. Every response returns a verdict (confirmed/contradicted/unknown) plus evidence -- never a guess.

## Products

### RealCite -- citation, URL, and legal case verification

POST https://goodsong.dev/verify/citation
Verify a citation: does it exist, is it retracted, and does the given title/authors/year/journal match the canonical record? Checked against Crossref (includes Retraction Watch data) and OpenAlex.
Body: {"doi": "10.1234/example.doi"} -- or {"title": "...", "authors": ["..."], "year": 2020, "journal": "..."}. doi and/or title required, rest optional.

POST https://goodsong.dev/verify/url
Verify a URL: does it resolve, what's the final status and redirect chain, is it archived on the Wayback Machine? Checked via direct fetch and the Internet Archive.
Body: {"url": "https://example.com/blog/some-article"} -- expected_content and expected_date are optional.

POST https://goodsong.dev/verify/case
Verify a legal case citation: does it exist, and does the given case name match the canonical record? Checked against CourtListener. Catches a fabricated case citation, including a real-looking citation number paired with an invented case name. Existence only -- does not check whether a case is still good law.
Body: {"citation": "576 U.S. 644"} -- case_name is optional, cross-checked when given.

### RealDep -- package and repo existence and safety verification

POST https://goodsong.dev/verify/package
Verify a package: does it exist, is it deprecated or yanked, and does it have known vulnerabilities? Checked against the npm/PyPI/crates.io registry plus OSV.dev advisories. Catches "slopsquatting" -- an agent trusting its own hallucinated package name into installing malware.
Body: {"ecosystem": "npm", "name": "left-pad"} -- ecosystem must be npm, pypi, or crates; version is optional (defaults to latest).

POST https://goodsong.dev/verify/repo
Verify a GitHub repo: does it exist, is it archived, is it disabled? Checked against the GitHub REST API. Catches an agent recommending or depending on an abandoned or hallucinated repo.
Body: {"owner": "expressjs", "repo": "express"}

### RealX402 -- is this x402 seller legit before you pay it

Dedicated page: https://goodsong.dev/x402-safety (same backend/quota as everything else here, just aimed at x402-specific discovery).

POST https://goodsong.dev/verify/seller
Verify an x402 seller: does it exist and respond with a well-formed 402 challenge, is its own declared input/output schema internally consistent, and is its payout address sanctioned? Checked live against the seller itself, a sanctions oracle, and on-chain wallet history (Base payTo addresses only); if the exact seller has a published Cairn (cairnwake.com) conformance report, its verdict is cited as supplementary evidence too -- a dated independent finding, not a live check. A pre-payment check for a marketplace with no real vetting of its own -- confirms the checkable things check out, not a guarantee of trustworthiness.
Body: {"resource_url": "https://api.example.com/paid-endpoint"} -- method is optional, defaults to POST (set to GET if that's what triggers the seller's 402).

## Auth

- x402 (primary): no key, no account. Send the request with no auth header; a 402 response carries the payment challenge (USDC on Base, $0.005/call -- $0.01 for /verify/case). An x402-aware client or agent framework settles it and retries automatically.
- API key (flat subscription, secondary): no free tier. Buy Solo ($15/mo, 5,000 calls) or Team ($49/mo, 25,000 calls) at https://goodsong.dev/#pricing -- a key is issued immediately at checkout, no separate signup step. Send it as `Authorization: Bearer <key>`. One key works across all products (shared call quota).

## Integration

- MCP server: `pip install verify-api-mcp` (source: https://github.com/mgdsn/verify-api-mcp, registry: io.github.mgdsn/verify-api-mcp). Exposes verify_citation, verify_url, verify_package, verify_repo, verify_case, and verify_seller as tools. Needs an API key (see Auth) -- x402 isn't usable here since most MCP clients have no wallet.
- OpenAPI spec: https://goodsong.dev/openapi.json (interactive docs at https://goodsong.dev/docs).

## Response contract

Every endpoint, across all products, returns the same shape:

{"verdict": "confirmed|contradicted|unknown", "checks": {...}, "canonical": {...}|null, "evidence": [{"source": "...", "url": "...", "retrieved_at": "ISO8601"}], "latency_ms": 0, "cost": {"amount": "...", "currency": "USDC"}}

"unknown" is a valid, honest answer, returned when a source itself is unreachable -- it is never charged.

This shape is deliberately machine-first: a bounded verdict enum (not free text), boolean checks (not prose), and the identical envelope across every endpoint -- parse it once, use it for all six tools.