# zkVerify

**Trustless blockchain verification over x402 with Merkle proofs + ECDSA signing**

[![Live on Railway](https://img.shields.io/badge/Live-Railway-green)](https://zkverify-production.up.railway.app)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)

## Why?

When an AI agent pays for blockchain data via x402, how does it know the data is authentic? **It doesn't.** 99% of x402 transactions are at risk (arXiv, July 2026 — 31 vulnerabilities found).

zkVerify solves this: every API response includes a **Merkle proof + ECDSA signature**. The agent can verify independently — zero trust required.

## Endpoints

| Endpoint | Price | Returns |
|----------|-------|---------|
| `GET /verify/balance/:address?chain=base` | $0.02 | Account balance + Merkle proof + signature |
| `GET /verify/contract/:address?chain=base` | $0.02 | Contract code hash + signature |
| `GET /health` | Free | Service status + signer address |
| `GET /.well-known/x402` | Free | x402 discovery (Bazaar) |

## Supported Chains

- **Base** (L2 — fallback to eth_getBalance)
- **Ethereum** (L1 — full eth_getProof / EIP-1186)
- **Polygon**

## How It Works

1. Agent sends `GET /verify/balance/0xABC...?chain=ethereum`
2. zkVerify returns HTTP 402 Payment Required
3. Agent pays $0.02 USDC on Base via x402
4. zkVerify:
   a. Fetches `eth_getProof` from RPC
   b. Verifies Merkle Patricia Proof against stateRoot
   c. Signs the result with ECDSA
   d. Returns: `{ balance, blockNumber, stateRoot, merkleProof, signature }`
5. Agent verifies:
   a. Signature (recoverAddress)
   b. Merkle proof locally (optional)
   c. stateRoot against block header (optional)
6. Agent now has **100% verified** on-chain data — no trust needed

## Quick Start

### For AI Agents (via x402)

```bash
curl https://zkverify-production.up.railway.app/verify/balance/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?chain=ethereum
# Returns: balance, Merkle proof (9 nodes), ECDSA signature, verified: true
```

### SDK (Client-side verification)

```typescript
import { fullVerify } from "zkverify";

const result = await fetch("https://zkverify-production.up.railway.app/verify/balance/0xABC...?chain=ethereum").then(r => r.json());
console.log(result.fullyVerified); // true = verified 100%
```

## MCP Server

zkVerify includes an MCP server with 3 tools for Claude/Cursor:

```json
{
  "mcpServers": {
    "zkverify": {
      "command": "npx",
      "args": ["-y", "zkverify-mcp"],
      "env": {
        "ZKVERIFY_URL": "https://zkverify-production.up.railway.app"
      }
    }
  }
}
```

## Architecture

- **Merkle Patricia Proof**: EIP-1186 `eth_getProof` from Ethereum L1
- **ECDSA Signing**: Every response signed with secp256k1
- **x402 Payment**: $0.02 USDC on Base
- **Zero Trust**: Agent needs no trusted oracle — just math

## Costs

- $0 startup cost
- Free RPC (PublicNode, Alchemy free tier)
- x402 facilitator: free for first 1,000 transactions/day
- Margin: 99% (after $0.001 facilitator fee)

## Patent (Pending)

**Title**: "System and method for providing cryptographically verifiable API responses using Merkle proofs and ECDSA signatures over HTTP payment protocols"

See [`patent/USPTO_PROVISIONAL.md`](patent/USPTO_PROVISIONAL.md)

## ZK Circuit (Level 2)

A simplified circom circuit (~202 constraints) proves that verification was performed correctly without revealing proof data.

See [`circuits/zkverify.circom`](circuits/zkverify.circom)

## License

MIT — free to use, modify, and distribute. Attribution appreciated.

## Links

- **Live**: https://zkverify-production.up.railway.app
- **GitHub**: https://github.com/zkarchitect/zkverify
- **Health**: https://zkverify-production.up.railway.app/health
- **Discovery**: https://zkverify-production.up.railway.app/.well-known/x402

---

Built with ZKForge — the first x402 service providing cryptographically verifiable blockchain data.