Buyer-specific proof packet · LangChain x402

Paid tool calls need a receipt before the payment.

The LangChain x402 thread has converged on the hard part: not merely paying a 402 challenge, but proving why an agent was allowed to pay at that moment.

This packet turns the discussion into a small implementation contract: a deterministic action_ref, a pre-payment SpendDecision, and a post-settlement receipt that ties tool input, policy, 402 challenge, and final payment evidence together.

Book A$690 readback Read markdown brief

Problem

Per-call x402 execution gives a settlement artifact, but a finance/security reviewer still needs the pre-execution justification: who approved the spend, under which policy, for which tool input, and with what max amount.

Contract

Generate action_ref = sha256(agent_id || tool_name || scope || timestamp_ms || challenge_hash) before payment. Carry that key through policy decision, x402 retry, and settlement receipt.

LangChain seam

Expose a SpendGovernor pre-tool hook that can run in simulation mode, fail closed, and persist a compact decision object without requiring a live wallet or paid call during tests.

Minimal receipt pair

{
  "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:..."
}

{
  "action_ref": "sha256:...",
  "phase": "post_settlement_outcome",
  "payment_status": "settled",
  "tx_hash": "0x...",
  "receipt_hash": "sha256:...",
  "tool_result_hash": "sha256:...",
  "completed_at": "2026-05-22T08:09:00Z"
}

If the decision is deny or needs_human, the same action_ref still gives auditability without moving funds.

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.

What not to do

Put API keys or wallet private material inside LangChain tool code.
Treat an on-chain tx hash as sufficient proof of authorization.
Let five bundle subcalls create five unrelated spend receipts.
Require paid Base/Solana settlement to run unit tests.
Hide deny/attenuate outcomes from callbacks and traces.

Outbound-ready note

Prepared for the open LangChain x402 discussion: keep execution and audit separate, add a deterministic action_ref, and make simulation mode a first-class path so maintainers can review behavior without moving funds.

LangChainx402SpendDecisionBase USDCaudit receiptno wallet spend