Earn virtual USD — session summary contributions

When your agent runs out of virtual balance, every PAYMENT_REQUIRED (402) response includes an earn_credits_via_session_summary block. Explain this option to the user before asking them to sign an on-chain x402 payment.

What this is

Trade a PII-free summary of a 411data session for instant virtual USD credit (not on-chain USDC). Max 10 submissions per UTC day per agent. Credits apply immediately when accepted — no staff approval.

`credit_tier` (you choose)	Credit
`signal_low`	$0.05
`signal_standard`	$0.10
`signal_high`	$0.20
`signal_exceptional`	$0.30

Daily credit cap: $3.00 from this program.

Flow (user must review first)

Draft the JSON body (see below) from the current session only.
POST /api/v1/contributions/session-summary/preview — show the user the display object and projected credited_usd. Fix issues if ready is false.
Wait for explicit user confirmation (or edits, then re-preview).
POST /api/v1/contributions/session-summary with the same body plus preview_token from step 2.

Never submit in the same turn as preview without user confirmation.

Required fields

Field	Rules
`summary`	400–8 000 chars, ≥80 words, ≥3 sentences; third person; no PII
`task_intent`	snake_case tag
`outcome`	`success` \| `partial_success` \| `failed` \| `abandoned`
`tools_used`	≥2 distinct 411data tools or `/api/v1/...` paths
`api_friction`	≥1 structured item (route, error kind, detail)
`suggested_improvement`	80–2 000 chars; concrete doc/product fix
`credit_tier`	one of the four tiers above — pick honestly
`credit_rationale`	60–800 chars; why that tier fits
`client_request_id`	new UUID per submission attempt

Forbidden: messages, conversation, user quotes, emails, phones, street addresses, wallet keys, bearer tokens.

Resubmitting the same chat with more context

Use a new client_request_id.
Rewrite the full summary from scratch — do not append or quote a prior submission to 411data.
Do not write “as previously submitted” or paste earlier summary text.

When to tell the user

On any code: PAYMENT_REQUIRED or insufficient virtual balance:

State current virtual_balance_usd and route price.
Offer x402 settle (wallet) as today.
Offer session summary credits using this recipe — often preferable when the session had real friction worth reporting.

Deploy with SESSION_FEEDBACK_ENABLED=1 after python3 db/deploy_sql.py ships X007_session_feedback. Operator notes: docs/_plans/session_feedback_credits_2026-05-24.md.