# Agent Approval Unit Builder API

## Name
Agent Approval Unit Builder v0.1

## Description
Converts AI-generated findings, patches, payment requests, deployment proposals, memory writes, tool execution requests, or decision-support outputs into minimal human decision contracts (Approval Units).

Core concept: Approval Unit = Human Decision Contract

v0.1 is build-only. No approval execution, blockchain transactions, or payments.

## Endpoints

POST /api/approval-unit/build    — Build a human decision contract (0.05 USDC)
POST /api/remediation/verify     — Verify AI remediation before approval (free)
POST /api/payment-evidence/check — Verify payment evidence and audit readiness (0.03 USDC)

## Additional Resources

OpenAPI Docs: https://ai-agent-payment-safety-stack.onrender.com/docs
OpenAPI JSON: https://ai-agent-payment-safety-stack.onrender.com/openapi.json
Health Check: https://ai-agent-payment-safety-stack.onrender.com/health
x402 Discovery: https://ai-agent-payment-safety-stack.onrender.com/.well-known/x402

## Pricing

approval-unit/build:    0.05 USDC per call
remediation/verify:     Free
payment-evidence/check: 0.03 USDC per call

## Payment

x402 scheme on Base (eip155:8453)
USDC payments to 0x60c402878EfcEcAe5733A88075328Aa2320C39BE

## Recommended Flow

POST /api/remediation/verify (free) → POST /api/approval-unit/build (0.05 USDC)
payment execution → POST /api/payment-evidence/check (0.03 USDC) → store evidence

## Use Cases

- Security patch approval
- Payment request approval
- Deployment proposal approval
- Memory write approval
- Tool execution approval
- Post-payment evidence verification (JP compliance, x402/JPYC/USDC)

## Live JP Payment Evidence Guard API

Endpoint:
https://ai-agent-payment-safety-stack.onrender.com/api/payment-evidence/check

Price:
0.03 USDC / check

Use this API after completing a payment via x402, JPYC, or USDC, and after receiving the service response.
Verifies that the payment and service response correspond, and classifies audit readiness.

Does NOT:
- execute payments
- act as a facilitator
- make legal or tax decisions
- guarantee output correctness
- store confidential content

Output:
- payment_evidence_status: ok / incomplete / mismatch / requires_review
- payment_response_matched: true if payment and response correspond
- service_response_received: true if service responded
- missing_items: list of missing evidence fields
- mismatch_items: list of mismatched fields
- audit_ready: true if evidence is complete and matched
- requires_human_review: true if human review is needed
- recommended_next_step: store_evidence / collect_missing_evidence / review_mismatch / escalate_to_human

## Direct AtoA Usage

Use this service when an AI agent needs to:
- verify an AI-generated remediation before human approval
- convert an AI-generated proposal into a human-approvable decision unit
- preserve the boundary between verification, approval, and execution
- prevent approval from being interpreted as unrestricted execution

Do not use this service to:
- deploy to production
- execute payments directly
- approve actions automatically
- replace human review in high-risk workflows

Primary endpoints:
- POST /api/remediation/verify
- POST /api/approval-unit/build

Payment:
- /api/approval-unit/build requires x402 payment: 0.05 USDC
- /api/remediation/verify is free

## Example Payloads

### 1. Incomplete Remediation Example

This example shows a remediation that needs additional verification before approval.

POST /api/remediation/verify

Example request (missing security_retest_results):
{
  "remediation_id": "remediation_001",
  "source_type": "security_patch",
  "finding_id": "finding_001",
  "remediation_type": "security_patch",
  "title": "SQL injection fix for user API",
  "finding_summary": "SQL injection vulnerability detected in user API endpoint.",
  "remediation_summary": "Replace raw SQL interpolation with parameterized query.",
  "affected_files": ["api/user.py"],
  "severity": "critical",
  "risk_level": "high",
  "evidence_ids": ["codeql_001"],
  "test_results": ["unit_passed"],
  "rollback_available": true,
  "production_deploy_requested": false
}

Expected result:
- decision: require_security_retest
- approval_unit_ready: false
- verification_status: incomplete
- next_step: add security_retest_results and regression_test_results before approval unit generation

### 2. Approval-ready Remediation Example

This example shows a complete remediation that is ready for approval unit generation.

POST /api/remediation/verify

Example request (complete with all test results):
{
  "remediation_id": "remediation_001",
  "source_type": "security_patch",
  "finding_id": "finding_001",
  "remediation_type": "security_patch",
  "title": "SQL injection fix for user API",
  "finding_summary": "SQL injection vulnerability detected in user API endpoint.",
  "remediation_summary": "Replace raw SQL interpolation with parameterized query.",
  "affected_files": ["api/user.py"],
  "severity": "critical",
  "risk_level": "high",
  "evidence_ids": ["codeql_001"],
  "test_results": ["unit_passed"],
  "security_retest_results": ["security_retest_passed"],
  "regression_test_results": ["regression_passed"],
  "staging_tested": true,
  "rollback_available": true,
  "production_deploy_requested": false
}

Expected result:
- decision: route_to_approval_unit_builder
- approval_unit_ready: true
- recommended_human_action: approve_staging_only
- blocked_next_steps includes deploy_to_production

### 3. Approval Unit Build Example

Use this after successful remediation verification to convert the verified proposal into a human decision contract.

POST /api/approval-unit/build (x402 payment required: 0.05 USDC)

Example request:
{
  "source_type": "security_patch",
  "approval_unit_type": "security_patch_approval",
  "title": "Approve SQL injection fix for staging",
  "summary": "Patch replaces raw SQL interpolation with parameterized query.",
  "risk_level": "high",
  "evidence_ids": ["codeql_001"],
  "test_results": ["unit_passed"],
  "rollback_available": true,
  "blocked_actions_until_approval": ["merge_to_staging", "deploy_to_production"],
  "recommended_decision": "approve_staging_only"
}

Expected result (after x402 payment):
- approval_question
- approval_unit_hash
- recommended_human_action
- allowed_actions limited to staging scope
- still_blocked_actions includes deploy_to_production