permitverdict-mcp

MCP server for Permit Verdict. Eleven tools, six 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 and Kraken. (Binance is configured but returns 451 to the host's region, so it is reported unavailable rather than silently counted — three venues we can reach beats four we cannot.) 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 six 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

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