Hashproof README

HashProof

Verifiable credentials with IPFS backup, on-chain registry, and pay-per-call API via x402.

What it is

HashProof is a credential issuance API. Organizations and Individuals (entities) issue verifiable credentials to people. Each credential is:

Stored as a JSON in the database and backed up on IPFS (Pinata)
Registered on-chain in the CredentialRegistry contract on Celo
Verifiable via a public URL: https://hashproof.dev/verify/:id

Two ways to pay: micropayment in USDC via x402 (Base or Celo) — no API keys, no subscriptions — or a prepaid API key for enterprise clients (no crypto needed). AI agents can call the API directly using a funded wallet.

Project structure

Code

backend/       Express API — credential issuance, verification, payments
frontend/      React app — landing page, credential verification, entity pages
contracts/     CredentialRegistry smart contract (Celo)
mcp/           MCP server (hashproof-mcp on npm) — use HashProof from any AI agent
skills/        Agent skill (npx skills add csacanam/hashproof)
docs/          Architecture and flow documentation

Deployed contracts

Network	Contract	Address
Celo mainnet	CredentialRegistry	`0x7a1B759A602Aba72a70f99Dffd0a386d7504ce9B`

Paid API endpoints

Endpoint	Price	Description
`POST /issueCredential`	$0.10 USDC	Issue one verifiable credential
`POST /entities/:id/verificationRequests`	$49 USDC	Submit a verification request

Payment is in USDC on Base or Celo via x402. The client signs an off-chain authorization — no gas required.

Free endpoints

Endpoint	Description
`GET /verify/:id`	Full 3-layer verification
`GET /templates/:ref/requirements`	Get required fields for a template
`POST /templates/:ref/preview`	Generate a preview PDF with watermark (no cost)
`GET /stats`	On-chain credential counters

For AI agents

HashProof is fully agent-usable — no account, no human onboarding. Three ways in:

MCP server, local or remote (listed on the official MCP registry as io.github.csacanam/hashproof):
bash
```
# local (stdio) — pays per credential with your own wallet via x402, or an API key
claude mcp add hashproof -- npx -y hashproof-mcp

# remote (Streamable HTTP) — nothing to install, API key required to issue
claude mcp add --transport http hashproof https://api.hashproof.dev/mcp
```
Tools: preview_template (free — iterate custom layouts), issue_credential ($0.10 via x402 or API key), verify_credential and get_template_requirements (free). The remote server has no wallet, so it can't do x402 — it needs Authorization: Bearer <api-key>. See mcp/README.md.
Agent skill: npx skills add csacanam/hashproof — or read it at hashproof.dev/skill.md.
Plain HTTP + x402: POST /issueCredential returns a 402 challenge any x402-v2 client can pay (USDC on Base or Celo). LLM index: hashproof.dev/llms.txt.

Agent identity metadata (ERC-8004 registration-v1): hashproof.dev/metadata.json.

Quick start

See backend/README.md and frontend/README.md for setup instructions. See docs/README.md for the full documentation index.