Pieverse A2a

Safety Rules

• First request the resource without payment.
• If the response is not 402, return it directly. Do not inspect wallet state or authorize payment.
• If the response is 402, parse and show the payment details before paying.
• Always ask for explicit Yes/No confirmation before authorizing payment.
• Never guess missing challenge fields. A valid Pieverse challenge must include challengeId, recipient, amountBaseUnits, token, and chainId.
• For strict verification, tell the user the payment can be held and challenged if the delivered result is wrong.
• Do not retry a paid request manually with a new authorization unless the user confirms again. Duplicate non-idempotent merchant requests may cause multiple payments.

Payer Flow

Use plain HTTP commands for now. Do not create or run local helper scripts for this flow; the long-term home should be purr a2a pay.

Step 1: Probe the resource

curl -sS -i "https://merchant.example/api/data"

If the response is not 402, return the response directly. No payment is needed.

If the response is 402, parse the JSON body and extract paymentRequired. Show the details to the user:

This resource requires Pieverse A2A payment:
- amount: <amount> <symbol>
- base units: <amountBaseUnits>
- chain: <chainId>
- token: <token>
- recipient: <recipient>
- description: <description>

Proceed with payment? (Yes/No)

Step 2: Authorize and retry only after confirmation

If the user says Yes, call the platform payment authorization endpoint:

curl -sS -X POST "$WALLET_API_URL/v1/payments/authorize" \
  -H "Authorization: Bearer $WALLET_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "challengeId": "<paymentRequired.challengeId>",
    "to": "<paymentRequired.recipient>",
    "amountBaseUnits": "<paymentRequired.amountBaseUnits>",
    "token": "<paymentRequired.token>",
    "chainId": <paymentRequired.chainId>,
    "verification": "soft"
  }'

For strict mode, set "verification": "strict" only when the user explicitly asks for strict settlement.

The response contains data.paymentCredential.

Step 3: Retry the original request

Retry the same method, URL, body, and merchant headers as the original request, adding only the payment credential header:

curl -sS -i "https://merchant.example/api/data" \
  -H "X-Pieverse-Payment: <paymentCredential>"

For POST/PUT/PATCH requests, preserve the original request body and content headers. If the retry response is not 2xx, report both the payment credential and the merchant response. Do not assume settlement succeeded just because authorization completed.

Strict-Mode Challenge

If a strict-mode paid response is wrong, empty, or not what the user requested, the user can challenge the held payment during the hold window.

curl -sS -X POST "$WALLET_API_URL/v1/payments/<paymentCredential>/challenge" \
  -H "Authorization: Bearer $WALLET_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason":"bad_result","evidence":{"summary":"Describe what was wrong"}}'

Challenge only when the user explicitly says the delivered result is bad or asks to dispute the payment.

Common Failures

Purr CLI Feature Request

The eventual CLI shape should be:

purr a2a pay --url https://merchant.example/api/data [--method GET] [--verification soft]

Expected behavior:

1. Request the URL without payment.
2. Return immediately for non-402 responses.
3. For Pieverse 402 challenges, display amount, token, chain, recipient, and description.
4. Require explicit confirmation before authorizing.
5. Call platform /v1/payments/authorize.
6. Retry with X-Pieverse-Payment.
7. Return structured JSON containing the challenge summary, credential, and final merchant response.

Do not make purr a2a pay a generic x402 command. It should implement the Pieverse A2A body challenge flow first; generic x402 can remain separate.