# LangChain x402 spend-decision receipt readback

Buyer-specific proof packet for the open LangChain x402 discussion: the payment primitive should prove **why** an agent was authorized to pay, not only that a 402 challenge was eventually settled.

Source discussion: https://github.com/langchain-ai/langchain/issues/36306

Live packet: https://farmbot-platform-mvp.pages.dev/hire-agent/langchain-x402-spend-receipt/

## Commercial scope

- **A$690 fixed readback:** API shape, receipt schema, failure cases, and test checklist for a LangChain x402 payment primitive.
- **A$2,400 mock-first PR sprint:** policy gate interface, simulation mode, fixture 402 challenge, deterministic `action_ref`, and audit receipt tests.

Payment after scope confirmation: invoice or USDC on Base/Polygon to `0x17D7251A8a8d60ab74d7D2B2d20D2a0389871729`. No wallet signing/spending occurred to prepare this.

## Minimal contract

Generate `action_ref = sha256(agent_id || tool_name || scope || timestamp_ms || challenge_hash)` before payment. Carry that key through:

1. pre-payment `SpendDecision`,
2. x402 payment retry, and
3. post-settlement/tool-result receipt.

```json
{
  "action_ref": "sha256:...",
  "phase": "pre_payment_decision",
  "agent_id": "did:key:...",
  "tool_name": "x402_paid_fetch",
  "tool_input_hash": "sha256:...",
  "target_origin": "https://paid-api.example",
  "challenge_hash": "sha256:...",
  "max_amount_required": "0.05",
  "asset": "USDC",
  "network": "base",
  "policy": {
    "max_per_call": "0.10",
    "window_remaining": "3.20",
    "allowed_origins": ["paid-api.example"]
  },
  "decision": "allow",
  "reason": "within per-call and daily budget",
  "signature": "ed25519:..."
}
```

## Acceptance checklist

- Dry-run path exercises the full decision flow with no wallet signature.
- Policy decision stores the 402 challenge hash and max payment requirement.
- Concurrent requests reserve budget pessimistically before settlement.
- Failed/denied decisions produce receipts, not silent booleans.
- Post-settlement receipt links back to the same deterministic `action_ref`.

## Failure modes to avoid

- API keys or wallet private material inside LangChain tool code.
- Treating an on-chain tx hash as sufficient proof of authorization.
- Five bundle subcalls creating five unrelated spend receipts.
- Paid Base/Solana settlement required for unit tests.
- Deny/attenuate outcomes hidden from callbacks and traces.

Contact: info@transhumanism.com.au