# 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)
POST /api/counterparty-invoice/check — Verify counterparty and invoice info before payment (0.02 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
counterparty-invoice/check: 0.02 USDC per call

## Payment

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

## Recommended Flow

POST /api/counterparty-invoice/check (0.02 USDC) → POST /api/approval-unit/build (0.05 USDC)
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

## Live JP Counterparty / Invoice Check API

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

Price:
0.02 USDC / check

Use this API before initiating a payment to a JP counterparty.
Verifies invoice registration number format, corporate number format, counterparty name match,
and wallet address format. Format check and local match only.

Does NOT:
- connect to National Tax Agency API (国税庁API)
- connect to corporate number API (法人番号API)
- provide tax or legal advice
- determine eligibility for input tax credit (仕入税額控除)
- perform credit checks on counterparties
- guarantee invoice validity or completeness

Output:
- counterparty_check_status: ok / requires_review / invalid
- invoice_number_format_valid: true if T + 13 digits
- corporate_number_format_valid: true if 13 digits
- name_match_status: match / partial_match / no_match / not_provided
- wallet_match_status: format_valid / format_invalid / not_provided
- requires_human_review: true unless all checks pass
- recommended_next_step: proceed_to_payment / verify_counterparty_before_payment / block_and_escalate
- missing_items: list of missing fields
- audit_ready: true only when status is ok

## 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

## Priority 0.5: Payment-to-Result Verification

Use this to connect payment evidence with returned results, including whether a paid data lookup produced a usable response. Supports result_received and result_usable fields for paid data API verification.

## Recommended buyer flow

Use ai-agent-payment-safety-stack as a payment safety API set.

Recommended order:

1. POST /api/approval-unit/build
   Build the approval unit before payment or execution.

2. POST /api/counterparty-invoice/check
   Check counterparty and invoice context before payment.

3. POST /api/payment-evidence/check
   Verify payment evidence after payment or settlement.

If you receive 402 Payment Required:

1. Read the x402 payment requirements returned by the API.
2. Pay using a compatible x402 client.
3. Retry the same request after payment.
4. Use the returned decision or evidence result before continuing the agent workflow.

Do not continue the downstream agent workflow until the relevant check returns a valid result.