AiPay Protocol

Verifier-backed USDC escrow for AI agents. Signed work terms, on-chain deposits, evidence hashes, and settlement by payer acceptance or a deterministic verifier.

Live product: https://aipay.work
Documentation: https://aipay.work/docs
Whitepaper: https://aipay.work/whitepaper
Contact: hello@aipay.work

What this repo contains

AiPay is a narrow payment primitive for agent work that can be verified.

A payee signs an EIP-712 order package. A payer verifies that package and locks USDC on Polygon. The payee submits delivery evidence. Funds move when the payer accepts the work or when an allowlisted verifier signs a deterministic verdict.

V1 is intentionally scoped. It does not claim subjective arbitration, gas sponsorship, a permissionless production verifier marketplace, external audit coverage, or custody of user funds.

Who should read what

Audience	Start here	Why
Payers / buyers	https://aipay.work/demo	See what gets locked, what counts as delivery, and when funds release.
Developers	https://aipay.work/developers	SDK, MCP Safe Mode, API keys, and integration checklist.
Partners / diligence	https://aipay.work/whitepaper	Trust boundaries, verifier model, V1 claims, and V1 non-claims.
Users comparing options	https://aipay.work/compare	Difference between manual escrow, marketplace escrow, x402-style payments, and AiPay.

Production V1

Item	Value
Network	Polygon PoS mainnet
Escrow contract	0xe60264...5940
USDC	0x3c499c542cef5e3811e1192ce70d8cc03d5c3359
Operator	0xfdCee9...6800
Production verifier	http_status:v1
TypeScript SDK	@aipayagnet/sdk@1.0.2
Python SDK	aipay-protocol==1.0.3
MCP package	@aipayagnet/mcp@0.1.0

Full deployment references are published in the docs: https://aipay.work/docs

Core flow

Payee signs order package
        ↓
Payer verifies signature and deposits USDC
        ↓
Payee submits result evidence
        ↓
Payer accepts OR verifier signs verdict
        ↓
Protocol releases, refunds, or splits funds according to signed terms

Protocol objects

Object	Purpose
Order	Signed commercial terms: payer, payee, amount, token, deadline, task hash, verifier, config hash.
Evidence	Content-addressed input and output bundles. The chain stores hashes, not large files.
Verifier	A named deterministic rule plus config hash. Production V1 ships http_status:v1.
Verdict	Domain-bound EIP-712 attestation signed by an allowlisted verifier operator.

Repository structure

.
├── contracts/              # Solidity contracts and Foundry tests
│   ├── src/                # AiPayProtocol, interfaces, mocks
│   ├── test/               # Protocol, E2E, guard, invariant tests
│   └── foundry.toml
├── frontend/               # Next.js public site, docs, dashboard, admin routes
├── packages/
│   ├── sdk-ts/             # TypeScript SDK: @aipayagnet/sdk
│   ├── sdk-py/             # Python SDK: aipay-protocol
│   ├── mcp/                # MCP server: @aipayagnet/mcp
│   ├── operator/           # Verifier/operator daemon
│   ├── relay/              # Relay helpers
│   └── cli/                # CLI package scaffold
├── verifiers/              # Deterministic verifier examples
│   ├── http_status/
│   ├── file_hash/
│   ├── json_schema/
│   ├── junit/
│   └── semgrep/
├── docs/                   # API reference, whitepaper, evidence docs
├── scripts/                # Deploy/build/export helpers
├── test/                   # Root safety tests
└── .env.example            # Placeholder-only environment template

Quick start

TypeScript SDK

npm install @aipayagnet/sdk ethers

import { AiPayPublicApi, prepareOrder } from "@aipayagnet/sdk";

const order = prepareOrder({
  payer: "0xPayer...",
  payee: "0xPayee...",
  amount: "1000000", // 1 USDC, 6 decimals
  verifier: "http_status:v1",
  evidenceUri: "https://example.com/health",
});

// Verify the package locally before approve + deposit.

Python SDK

pip install aipay-protocol

MCP Safe Mode server

npx -y @aipayagnet/mcp

The MCP package is safe by default. It prepares orders, typed digests, signature checks, and transaction previews. It does not silently broadcast real USDC transactions.

Development

Prerequisites

• Node.js 22+
• npm workspaces
• Foundry (forge, cast, anvil) for contract work
• Python 3.11+ for verifier scripts and Python SDK checks

Install

npm install

Core checks

# Frontend safety tests
npm run test:frontend-safety

# Frontend production build
cd frontend && npm run build

# Build SDK + MCP and run MCP smoke test
cd ..
npm --workspace @aipayagnet/sdk run build
npm --workspace @aipayagnet/mcp run build
npm --workspace @aipayagnet/mcp run smoke

Contracts

cd contracts
forge install
forge build
forge test -vvv

contracts/lib/ is intentionally ignored in git. Reinstall Foundry dependencies locally before contract builds.

Security and secret handling

• Real .env, .env.local, private keys, API keys, build output, caches, and local agent state are ignored.
• .env.example contains placeholders only.
• Example scripts read private keys from local environment variables and never hardcode them.
• Public EVM addresses and transaction hashes are not secrets. Private keys and API keys are.

Before publishing changes, run a secret scan such as:

git diff --cached --name-only | xargs grep -nE 'gh[pousr]_|github_pat_|BEGIN .*PRIVATE KEY|0x[a-fA-F0-9]{64}' || true

Review each finding manually.

Status

Production V1 is live on Polygon mainnet with the published website, docs, Evidence API, Indexer API, TypeScript SDK, Python SDK, MCP Safe Mode server, and http_status:v1 verifier path.

License

MIT. See LICENSE.