permitverdict-mcp

MCP server for Permit Verdict. Nine tools, five of them free. The paid ones cost between one cent and two dollars per call and pay themselves, in USDC on Base, using the x402 protocol.

There is no API key, no account, and no signup. If you have a funded wallet, you have access.

What it sells

Settlement Oracle — did a crypto price event actually happen? Every verdict is resolved independently across Hyperliquid, Coinbase, Kraken and Binance. When the venues agree you get YES or NO at high confidence. When they disagree you get DISPUTED at low confidence, because a wick that prints on one exchange and not another is the single most common reason a market settles the wrong way, and a confident answer in that situation is worse than no answer.

Permit Intelligence — building-permit history, activity signals, and a decision-ready verdict for an address, drawn from official city open-data portals across seven US cities.

Install

{
  "mcpServers": {
    "permitverdict": {
      "command": "npx",
      "args": ["-y", "permitverdict-mcp"]
    }
  }
}

That works immediately, with no wallet. You get the five free tools.

To enable the paid tools, add a wallet:

{
  "mcpServers": {
    "permitverdict": {
      "command": "npx",
      "args": ["-y", "permitverdict-mcp"],
      "env": { "WALLET_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY" }
    }
  }
}

Fund it with a few dollars of USDC on Base. You do not need any ETH — gas is sponsored by the x402 facilitator, so only USDC is ever spent.

Tools

Tool	Price	What it does
wallet_status	free	Whether a wallet is configured, and its address
list_settlement_assets	free	Assets, venues, operators and modes the oracle supports
check_venue_health	free	Which venues are answering right now
decode_decision_id	free	Is this attestation genuine, and what does it claim?
list_jurisdictions	free	Cities covered by permit intelligence
check_permit_activity	free	Whether an address has recent permit activity
get_crypto_spot	$0.01	Cross-venue spot price, agreement and spread
verify_decision	$0.02	Does an attested settlement still hold today?
resolve_price_event	$0.05	Settlement verdict with per-venue evidence
attest_price_event	$0.25	The verdict plus a signed decision_id and every candle behind it
get_permit_verdict	$2.00	Full permit history and verdict for an address

Free tools first is deliberate. check_venue_health tells you how many independent venues are live before you spend anything, so you know whether the verdict you are about to buy will be corroborated by three sources or one.

Attestations, and why verifying one is cheap

attest_price_event returns a decision_id that is worth keeping. It is not a database key — everything needed to re-derive the answer is encoded inside it, and it is signed by the same wallet that received your payment. That has two consequences.

Anyone you show it to can check its origin for free with decode_decision_id. Forgery and after-the-fact editing are both detectable, and it costs nobody anything, because checking a signature is local arithmetic. You can also do it yourself with any EVM tooling: the signature covers the literal string formed by the id's first two dot-separated parts, and it should recover to 0xE11d7Ff8c7573b15F9F6F6d4961Afb4109d3ddA5.

What that free check does not tell you is whether the verdict is still correct. Exchanges revise candle history, and a venue that was unreachable when the record was issued may answer differently now. verify_decision re-resolves the same event against the venues today and returns CONFIRMED, CHANGED, or INDETERMINATE. It costs $0.02 rather than the $0.05 of a fresh resolution because you are not buying an answer, you are buying a check on someone else's — and if you are about to act on a settlement handed to you by a counterparty, that check is worth two cents.

CHANGED is the outcome that earns the fee.

touch vs close

resolve_price_event takes a mode, and getting it wrong is how settlements go bad.

touch counts any intrabar print, wicks included. close counts only candle closes. On the same window and the same threshold these routinely disagree. Most carefully written markets settle on closes; most casual bets mean touches. Pick the one your contract actually says.

Payment receipts

Every paid response carries a _payment block with the on-chain transaction that paid for it:

{
  "verdict": "YES",
  "confidence": "high",
  "_payment": {
    "paid": "$0.05",
    "payer": "0xFE5d…D108",
    "transaction": "0x88d3…7b1e",
    "explorer": "https://basescan.org/tx/0x88d3…7b1e",
    "network": "eip155:8453"
  }
}

If an agent spends money on a verdict it may later have to defend, it should be able to cite the transaction that bought it.

Security

Your private key stays on your machine. It is read once from the environment, used to derive a local signing account, and never logged or transmitted — the only thing that leaves is a signature over the specific payment the API asked for. This package makes no outbound requests other than to permitverdict.com and the x402 facilitator.

Use a dedicated wallet holding only what you intend to spend. Do not point this at a wallet that holds anything you would mind losing.

Development

npm install
npm test

The test suite starts the real binary and speaks MCP to it over stdio. That is on purpose: the failure mode worth catching is the one where every unit test passes and the process still cannot start.

License

MIT