Proof-of-Use Trust Graph

PUTG is a CLI for creating signed, verifiable proof-of-use receipts from safe OpenAPI documentation checks.

The idea is simple:

Before an agent relies on an API, it should be able to ask: what was actually checked, when was it checked, what evidence was recorded, and can the result still be verified?

PUTG v0.1 is a small first step toward that. It does not try to rank the web yet. It creates a structured, signed receipt that an agent or human can inspect before trusting an API integration path.

Why This Exists

AI agents increasingly read API documentation, choose tools, and act on behalf of users. Today, they often trust documentation because it is easy to find or easy to parse.

That is weak.

A PUTG receipt records:

• which OpenAPI document was checked
• whether it parsed as supported OpenAPI
• which operations were considered unsafe or unsupported for probing
• whether optional safe GET probes were run
• which local agent key signed the result
• whether the receipt still verifies unchanged

A valid receipt does not prove that an API is production-safe. It proves that this limited check happened, produced this structured result, and has not been modified after signing.

Quick Start

Install dependencies and build the CLI:

npm install
npm run build

Generate a local signing key:

npm run dev -- keygen

Create a receipt from an OpenAPI file:

npm run dev -- eval openapi examples/openapi/basic.yaml --out putg-receipt.json

Verify the receipt:

npm run dev -- verify putg-receipt.json

Run conservative public GET probes only when you explicitly want live endpoint checks:

npm run dev -- eval openapi examples/openapi/basic.yaml --probe --out putg-receipt.json

What An Agent Should Read

After creating and verifying a receipt, an agent should inspect:

• overall.recommendation
• overall.risk_flags
• observations
• judgments
• proof

Example workflow:

putg eval openapi <openapi-url> --out receipt.json
putg verify receipt.json

If verification fails, the receipt should not be trusted. If the receipt contains warnings or unsupported observations, the agent should ask the user before relying on the API for important actions.

OpenClaw users can also use the included skill at skills/putg-api-preflight/SKILL.md. It teaches an agent when to run PUTG, how to verify the receipt, and why live probes require explicit user approval.

See docs/openclaw.md for the thin OpenClaw integration guide.

v0.1 Scope

PUTG v0.1 supports:

• OpenAPI 3.0 and 3.1 JSON/YAML checks
• local files and HTTPS OpenAPI URLs
• Ed25519 key generation
• signed receipt creation
• receipt verification
• optional --probe for conservative public GET checks
• JSON output for automation
• a thin OpenClaw skill for API preflight checks

PUTG v0.1 does not support:

• authenticated API probing
• POST, PUT, PATCH, or DELETE probing
• automatic external $ref fetching
• website-signed interaction receipts
• reputation aggregation
• global ranking

Safety Defaults

PUTG is intentionally conservative.

• By default, it does not call API endpoints.
• Endpoint probes run only with --probe.
• --probe cannot be combined with --no-network.
• Only filtered public GET operations are considered for probing.
• Private, loopback, link-local, non-HTTPS, unsafe redirect, and suspicious path targets are blocked.
• Remote OpenAPI loads and endpoint probes use pinned public address checks.
• Response bodies are not stored; receipts record hashes and metadata.
• Probe response bodies are capped.
• External $ref documents are not fetched by default.

When in doubt, v0.1 skips rather than probes.

Commands

putg keygen [--out <file>]
putg eval openapi <url-or-file> [--out <file>] [--key <file>] [--probe] [--no-network] [--base-url <url>] [--max-endpoints <number>] [--timeout-ms <number>] [--json]
putg verify <receipt-file> [--json]

During local development, prefix commands with npm run dev --:

npm run dev -- eval openapi examples/openapi/basic.yaml --json

After building, run the compiled CLI:

node dist/index.js eval openapi examples/openapi/basic.yaml --out putg-receipt.json

Exit Codes

• 0: Receipt successfully created or verified, and no critical tool error occurred.
• 1: Tool error: no usable receipt was created.
• 2: Receipt created, but the evaluated resource failed critical checks.
• 3: Verification failed.

npm Package Readiness

The package is prepared for npm distribution:

• bin.putg points to the compiled CLI at dist/index.js
• files limits the package to runtime files, examples, schemas, docs, README, and license
• prepack builds before packing
• prepublishOnly runs tests, typecheck, and build before publishing
• the OpenClaw skill is included in the package under skills/
• CI checks tests, typecheck, build, and npm pack --dry-run

Check the package locally:

npm pack --dry-run

Project Direction

The long-term PUTG vision is a decentralized reputation layer for the agentic web: signed task receipts, resource manifests, claim-level evaluations, trust lenses, append-only logs, and privacy-preserving evidence.

The protocol should standardize evidence, not values. Different agents and communities can apply different trust lenses over the same observations.

See docs/vision.md for the broader direction.

License

MIT