WorkProof

WorkProof is a proof-of-delivery and output verification layer for OKX.AI Agent Service Providers.

It checks whether an ASP deliverable satisfies the buyer's task brief before payment release, review, or reputation update.

PASS / NEEDS_REVISION / FAIL

OKX.AI Genesis Hackathon Fit

• Category: Software Utility
• Service mode: A2MCP for repeatable verification, A2A for deep or subjective reviews
• Core value: fewer disputes, stronger reputation signals, and safer escrow release
• Demo target: verify a weak research deliverable, request revisions, then pass the improved version

Hackathon notes:

• Campaign: OKX.AI Genesis Hackathon.
• Build goal: create an Agent Service Provider that solves a clear real-world use case.
• Submission flow: list the ASP on OKX.AI, post a short X walkthrough with #OKXAI, then submit the project form by July 27, 2026.
• Hackathon page: https://www.hackquest.io/hackathons/OKXAI-Genesis-Hackathon
• A2MCP guide: https://web3.okx.com/onchainos/dev-docs/okxai/howtomcp

Problem

Autonomous agents can buy work, but they still need a trusted way to know whether the work was actually delivered. Without verification, bad outputs can get paid, good ASPs lack proof, and marketplaces inherit avoidable disputes.

MVP Tools

verify_deliverable

Generic verification entry point for CSVs, research reports, listings, and simple code deliverables.

verify_research_report

Checks required sections, URL-style citations, and overconfident unsupported claims.

verify_lead_list

Checks row count, duplicates, required fields, contact email format, and category relevance.

verify_code_delivery

Checks required files, build/test command metadata, and sandbox attestation without executing untrusted code on the host.

Architecture

Buyer Agent / ASP
  -> WorkProof MCP/API
  -> Task Brief Parser
  -> Acceptance Criteria Extractor
  -> Verification Router
  -> Specialized Verifiers
  -> Evidence Store
  -> Scoring Engine
  -> Proof Report

Hackathon Demo

1. Buyer hires a research ASP.
2. ASP delivers a report with missing citations.
3. WorkProof returns NEEDS_REVISION.
4. ASP submits improved report.
5. WorkProof returns PASS.
6. Buyer releases payment and stores the proof hash.

Repository Contents

• spec.md - full product and technical specification
• README.md - project overview and hackathon framing
• app/ - FastAPI service implementation
• tests/ - API tests
• Dockerfile - production container
• okx-ai-listing.md - marketplace listing draft
• DEMO_SCRIPT.md - 90-second walkthrough script

Run Locally

Recommended with uv:

uv run uvicorn app.main:app --reload

Plain Python fallback:

python -m pip install -e ".[dev]"
python -m uvicorn app.main:app --reload

Then open:

• API docs: http://127.0.0.1:8000/docs
• MCP-style manifest: http://127.0.0.1:8000/mcp
• Demo payloads: http://127.0.0.1:8000/demo

Test

Recommended with uv:

uv run --extra dev pytest

Plain Python fallback:

python -m pytest

Production Notes

• Start as a free A2MCP endpoint for fastest OKX.AI review, then add x402 payment middleware after the demo flow is approved.
• Set WORKPROOF_API_KEY before exposing private or paid endpoints.
• Deploy behind HTTPS before OKX.AI registration.
• Use WORKPROOF_DATA_DIR for persistent SQLite report storage.
• Code verification does not execute arbitrary code on the host; connect a disposable sandbox worker before enabling live repo execution.

Deploy To Railway

1. Push this repo to GitHub.
2. In Railway, create a new project from the GitHub repo.
3. Let Railway build from the included Dockerfile.
4. Leave WORKPROOF_API_KEY empty for the hackathon review endpoint.
5. Add these optional variables:

WORKPROOF_ENV=production
WORKPROOF_DATA_DIR=/app/data
WORKPROOF_CORS_ORIGINS=*

6. Generate a public Railway domain.
7. Check the deployed service:

curl -i https://your-railway-domain/health
curl -i https://your-railway-domain/mcp

For OKX.AI listing, use the deployed HTTPS /tools/... endpoints as a free A2MCP service.

Contributor

• eosadolor382@gmail.com
• @Ikpia

Status

Production-shaped MVP: API, tool endpoints, deterministic verifiers, persistence, tests, Dockerfile, listing copy, and demo script are implemented.