callx402 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +227 -2
  3. package/SPEC.md +264 -0
  4. package/bin/callx402.js +257 -0
  5. package/core/config.js +104 -0
  6. package/core/envelope.js +80 -0
  7. package/core/index.js +364 -0
  8. package/core/pipeline.js +371 -0
  9. package/core/remote.js +242 -0
  10. package/core/subsystems.js +136 -0
  11. package/dist/callx402-1.0.0.tgz +0 -0
  12. package/docs/ACTION_LANGUAGE.md +23 -0
  13. package/docs/MCP_IDENTITY.md +27 -0
  14. package/docs/README.md +315 -0
  15. package/docs/action-reference.md +247 -0
  16. package/docs/cli-help-verified-2026-10-06.txt +39 -0
  17. package/docs/logo.png +0 -0
  18. package/docs/problem-map.md +65 -0
  19. package/docs/troubleshooting/cx402-402afterfail-001-402-after-failed-settle.md +143 -0
  20. package/docs/troubleshooting/cx402-agentcap-001-agent-spending.md +114 -0
  21. package/docs/troubleshooting/cx402-eip3009-001-authorization-checklist.md +124 -0
  22. package/docs/troubleshooting/cx402-paidnores-001-paid-no-result.md +97 -0
  23. package/docs/troubleshooting/cx402-safretry-001-retry-after-payment.md +106 -0
  24. package/docs/troubleshooting/cx402-settlepend-001-settlement-pending.md +92 -0
  25. package/docs/troubleshooting/cx402-solanafail-001-solana-settlement.md +119 -0
  26. package/docs/troubleshooting/cx402-verset-001-verify-ok-settle-fails.md +101 -0
  27. package/docs/visuals/01-action-map.png +0 -0
  28. package/docs/visuals/02-diagnose.png +0 -0
  29. package/docs/visuals/03-resolve.png +0 -0
  30. package/docs/visuals/04-route.png +0 -0
  31. package/docs/visuals/05-preflight.png +0 -0
  32. package/docs/visuals/06-inspect.png +0 -0
  33. package/docs/visuals/07-status.png +0 -0
  34. package/docs/visuals/08-architecture.svg +49 -0
  35. package/docs/visuals/MANIFEST.md +40 -0
  36. package/docs/visuals/raw/01-help.out +39 -0
  37. package/docs/visuals/raw/02-diagnose.out +2 -0
  38. package/docs/visuals/raw/03-resolve.out +4 -0
  39. package/docs/visuals/raw/04-route.out +2 -0
  40. package/docs/visuals/raw/05-preflight.out +2 -0
  41. package/docs/visuals/raw/06-inspect.out +23 -0
  42. package/docs/visuals/raw/07-status.out +16 -0
  43. package/docs/visuals/render_terminal.py +149 -0
  44. package/docs/what-is-callx402.md +251 -0
  45. package/integrations/README.md +62 -0
  46. package/integrations/core.py +329 -0
  47. package/integrations/crewai/callx402_crewai.py +109 -0
  48. package/integrations/facilitator/settle-guard.js +99 -0
  49. package/integrations/langchain/callx402_tools.py +180 -0
  50. package/integrations/mcp-clients/README.md +121 -0
  51. package/integrations/n8n/callx402-incident-guard.json +1 -0
  52. package/mcp/README.md +63 -0
  53. package/mcp/index.js +239 -0
  54. package/package.json +39 -4
  55. package/scripts/drift-check.js +202 -0
  56. package/sdk/js/index.js +207 -0
  57. package/sdk/python/README.md +67 -0
  58. package/sdk/python/callx402/__init__.py +317 -0
  59. package/sdk/python/callx402/cli.py +193 -0
  60. package/sdk/python/pyproject.toml +30 -0
  61. package/sdk/python/setup.py +56 -0
  62. package/server/index.js +520 -0
  63. package/server/openapi.yaml +537 -0
  64. package/server.json +1 -0
  65. package/test/cli-dispatch.test.js +248 -0
  66. package/test/helpers.js +103 -0
  67. package/test/integrity.test.js +43 -0
  68. package/test/intent-pipeline.test.js +205 -0
  69. package/test/remote.test.js +166 -0
  70. package/test/safety.test.js +234 -0
  71. package/test/sdk.test.js +198 -0
  72. package/test/server.test.js +190 -0
  73. package/test/subsystems.test.js +118 -0
@@ -0,0 +1,124 @@
1
+ ---
2
+ id: CX402-EIP3009-001
3
+ title: "EIP-3009 authorization rejected at verify: the field-level checklist"
4
+ category: eip3009
5
+ severity: high
6
+ economic_risk: "Malformed authorizations fail closed at verify (no funds move), but each wrong field costs a debugging cycle; 'fixing' nonce reuse by minting a fresh authorization can double-pay."
7
+ search_phrases: ["x402 EIP-3009 invalid signature", "x402 token_name_mismatch", "x402 authorization_valid_before", "x402 nonce_already_used"]
8
+ reading_minutes: 4
9
+ sources: ["https://github.com/x402-foundation/x402/issues/961", "https://github.com/hummusonrails/x402-facilitator/blob/HEAD/README.md", "https://github.com/x402-foundation/x402/raw/refs/heads/main/contracts/evm/audits/cantina_x402_may2026.pdf"]
10
+ related: ["CX402-VERSET-001", "CX402-SAFFRETRY-001"]
11
+ updated: 2026-10-06
12
+ ---
13
+
14
+ # EIP-3009 authorization rejected at verify: the field-level checklist
15
+
16
+ ## THE PROBLEM
17
+
18
+ `/verify` rejects your authorization and the reason reads like alphabet soup:
19
+ `invalid_exact_evm_payload_signature`, `invalid_exact_evm_token_name_mismatch`,
20
+ `invalid_exact_evm_payload_authorization_valid_before`,
21
+ `invalid_exact_evm_nonce_already_used`. The signature is real — your wallet
22
+ signed it — but the facilitator will not accept it.
23
+
24
+ ## WHY IT HAPPENS
25
+
26
+ EIP-3009 authorizations are exact-match instruments. Every field must match
27
+ what the token contract expects, and the failure modes are field-specific:
28
+
29
+ **EIP-712 domain.** The `name` and `version` must match the token's on-chain
30
+ EIP-712 domain. For USDC the domain is `name: "USD Coin"`, `version: "2"` —
31
+ not `"USDC"`. Signing with the wrong domain produces a signature that
32
+ recovers to the wrong address, which surfaces as an invalid signature. This
33
+ is the single most common "my signature is valid but the facilitator rejects
34
+ it" cause, called out independently across facilitator docs and integrations
35
+ ([x402-foundation/x402#961](https://github.com/x402-foundation/x402/issues/961)).
36
+
37
+ **Validity window.** `validAfter` and `validBefore` are unix timestamps, both
38
+ required. Quote at T, sign, submit after `validBefore` — a slow agent, a
39
+ queued retry, clock skew — and verify rejects it as expired. Re-signing the
40
+ same expired payload never succeeds.
41
+
42
+ **Nonce.** Each authorization carries a unique 32-byte nonce; reuse is
43
+ rejected on-chain and at verify. Replay is structurally blocked, which is a
44
+ security property — until your retry logic fights it.
45
+
46
+ **Amount, recipient, encoding.** `authorization.value` must exactly equal the
47
+ quoted `amount`; `authorization.to` must equal `payTo`; `amount` is a string
48
+ in atomic units; the asset address is lowercase hex.
49
+
50
+ **Type ordering.** The Cantina audit of the batch-settlement contracts found
51
+ EIP-712 type strings built with struct types in the wrong order, violating
52
+ the alphabetical-ordering rule — standard wallets (ethers, viem, MetaMask,
53
+ hardware) sort alphabetically and sign a different digest than the contract
54
+ expects
55
+ ([cantina_x402_may2026.pdf](https://github.com/x402-foundation/x402/raw/refs/heads/main/contracts/evm/audits/cantina_x402_may2026.pdf),
56
+ finding 3.1.1).
57
+
58
+ ## DO NOT DO THIS
59
+
60
+ Do not re-sign with the same parameters hoping it passes. If the domain is
61
+ wrong, every signature you produce is wrong — the fix is the domain, not the
62
+ signing.
63
+
64
+ Do not "fix" `nonce_already_used` by minting a fresh authorization for the
65
+ same intent without checking whether the first one settled. That converts a
66
+ replay rejection into a double payment.
67
+
68
+ Do not reconstruct the quote client-side. Feed the server's returned terms
69
+ straight into the signer; a reconstructed quote that differs by one field
70
+ fails `value_mismatch` or `recipient_mismatch`.
71
+
72
+ ## THE SAFE FIX
73
+
74
+ Walk the checklist in order — the first failure you find is almost always the
75
+ cause:
76
+
77
+ 1. **Domain:** `name` and `version` match the token's actual on-chain EIP-712
78
+ domain. For USDC: `"USD Coin"` / `"2"`. Never guess; read the contract.
79
+ 2. **Type ordering:** EIP-712 struct types alphabetical. If wallet signatures
80
+ and contract expectations disagree, this is the seam.
81
+ 3. **Window:** `validAfter` <= now <= `validBefore`, with margin for
82
+ submission latency. If expired, sign fresh — never reuse.
83
+ 4. **Nonce:** fresh 32-byte nonce per authorization. Never re-send a signed
84
+ payload.
85
+ 5. **Value and recipient:** `value` == quoted `amount` exactly (string,
86
+ atomic units); `to` == `payTo`; asset address lowercase hex.
87
+ 6. **Quote fidelity:** sign the server's returned quote verbatim.
88
+
89
+ ## VERIFY
90
+
91
+ `/verify` returns `isValid: true` for the corrected payload. Then confirm
92
+ `/settle` succeeds — verify is read-only and proves nothing about payment.
93
+ Regression-test each checklist item: wrong domain, expired window, reused
94
+ nonce, mismatched value, one at a time.
95
+
96
+ ## Using Callx402 for this condition
97
+
98
+ For a verify rejection, the applicable action is `diagnose`. Give it a
99
+ target and the failure evidence — the rejected payload, the /verify
100
+ response, and the facilitator's reason string — and it runs deterministic
101
+ stage classifiers over what you supplied: it pins the rejection to the
102
+ verify stage and surfaces the facilitator's reason verbatim, so you stop
103
+ guessing whether the failure is transport, payload, or verification.
104
+
105
+ What it does not do matters here. It performs no field-level signature
106
+ analysis: it cannot tell you whether the EIP-712 domain, the validity
107
+ window, the nonce, or the value field is the wrong one. That narrowing is
108
+ what the checklist above is for, and `diagnose` is not a substitute for
109
+ it. It also refuses to act on its own finding — no re-signing, no fresh
110
+ authorization, no retry of the payload. Stage classification over supplied
111
+ evidence is covered by the test suite; field-level EIP-3009 diagnosis is
112
+ not an implemented capability.
113
+
114
+ ## SOURCES AND VERIFICATION SCOPE
115
+
116
+ - Protocol claims (EIP-3009 exact-match fields, domain name/version for
117
+ USDC, nonce uniqueness, validity-window semantics) verified against the
118
+ x402 spec, the facilitator docs, and the Cantina audit finding 3.1.1,
119
+ all linked in the front matter, current as of 2026-10-06.
120
+ - callx402 claims cite the current implementation: the doctor subsystem
121
+ classifies failures from supplied evidence only
122
+ (`lib/mcp/doctor.js`); no EIP-3009 field-level classifier exists in the
123
+ diagnose path, which is stated as a limitation rather than a capability.
124
+ - Problem and fix content verified independently of callx402.
@@ -0,0 +1,97 @@
1
+ ---
2
+ id: CX402-PAIDNORES-001
3
+ title: "x402 paid but the tool didn't execute: the lost-result problem"
4
+ category: paid-no-result
5
+ severity: critical
6
+ economic_risk: "Payment settles but the result never arrives; buyer has no recourse artifact. Blind retry risks double payment AND double execution."
7
+ search_phrases: ["x402 paid but no response", "x402 payment settled but no response", "x402 paid but tool didn't execute", "x402 did it deliver", "x402 lost result after payment"]
8
+ reading_minutes: 4
9
+ sources: ["https://github.com/x402-foundation/x402/issues/1195", "https://github.com/x402-foundation/x402 (v2 spec, section 6.1)"]
10
+ related: ["CX402-SAFFRETRY-001", "CX402-SETTLEPEND-001"]
11
+ updated: 2026-10-06
12
+ ---
13
+
14
+ # x402 paid but the tool didn't execute: the lost-result problem
15
+
16
+ ## THE PROBLEM
17
+
18
+ The payment settled — you can see it on chain. But the tool never executed, or
19
+ it executed and the response never came back. You paid for a result you don't
20
+ have, and nothing in the protocol proves what happened after the money moved.
21
+
22
+ ## WHY IT HAPPENS
23
+
24
+ The x402 payment lifecycle has an ordering the spec defines but can't enforce
25
+ for you: verify → resource executes → settle → respond (spec §6.1). Two crash
26
+ windows fall out of that ordering:
27
+
28
+ 1. **Settle succeeds, response is lost.** Network drop, proxy timeout, server
29
+ crash after settlement — the client paid for a result it never received.
30
+ 2. **The ecosystem has no delivery proof layer.** As the most-discussed issue
31
+ in the x402 tracker puts it: "x402 solves how agents pay... None of these
32
+ layers prove delivery" — escrow, reputation, and orchestration systems all
33
+ need to answer "did the agent actually deliver what was paid for," and
34
+ right now each either skips the check or trusts self-reporting
35
+ ([x402-foundation/x402#1195](https://github.com/x402-foundation/x402/issues/1195),
36
+ 103 comments).
37
+
38
+ So the protocol gets your money to the seller reliably, and then goes quiet
39
+ about whether you got anything back.
40
+
41
+ ## DO NOT DO THIS
42
+
43
+ Do not re-pay and re-execute blindly. This is the double-jeopardy state: a
44
+ fresh payment risks double payment, and a fresh execution risks double
45
+ execution (the first one may have run — you just never saw the result). Both
46
+ failure modes from one retry.
47
+
48
+ Do not accept "the transaction confirmed" as proof of delivery. On-chain
49
+ settlement proves payment, not execution. They are different planes; conflating
50
+ them is how paid-no-result becomes undetectable.
51
+
52
+ ## THE SAFE FIX
53
+
54
+ 1. **Separate the planes.** Ask three distinct questions: did payment settle?
55
+ (check the chain) — did execution happen? (check the server's records, or
56
+ ask) — did delivery happen? (do you hold the result?). Most "paid but
57
+ nothing happened" incidents are a delivery failure, not an execution
58
+ failure — and re-execution is the wrong fix for a delivery failure.
59
+ 2. **Request the settlement receipt.** The spec's `PAYMENT-RESPONSE` carries
60
+ the transaction hash. Keep it: it's your proof of payment, and it's what
61
+ lets you or the seller reconcile without paying again.
62
+ 3. **If execution is unproven, ask before re-executing.** Contact the resource
63
+ operator with the settlement hash and ask whether execution occurred. Only
64
+ re-execute when execution is proven not to have happened — or when the
65
+ operation is provably idempotent.
66
+ 4. **For agents:** never auto-retry a paid-no-result. Park the operation for
67
+ human review or evidence-gated recovery. An agent that retries paid
68
+ operations on its own is a double-spend machine.
69
+
70
+ ## VERIFY
71
+
72
+ Resolved when you can answer all three planes from evidence: payment settled
73
+ (tx hash, confirmed), execution state known (executed / not executed, from the
74
+ operator or logs), delivery confirmed (result in hand). If any plane is still
75
+ UNKNOWN, the incident is open — do not close it by retrying.
76
+
77
+ ## Using Callx402 for this condition
78
+
79
+ The three-plane check in the SAFE FIX section maps to a three-step sequence. Start with `evidence`:
80
+
81
+ ```
82
+ callx402 evidence <operationId>
83
+ ```
84
+
85
+ It accepts an operation id (and optionally `--dir` to point at a different ledger store). It evaluates the operation ledger's recorded events: the latest per-plane states (payment, execution, delivery), the protocols involved, and an event trail. It returns those states, the trail, and a plain statement of basis — including "no events recorded for this operation," stated plainly rather than hidden.
86
+
87
+ The follow-on sequence: `explain <operationId>` classifies the recorded state — NO_BASIS, INCOMPLETE (any UNKNOWN plane means do not retry, do not repay), KNOWN_SAFE, RECOVERY_CANDIDATE, or PARTIAL — and a RECOVERY_CANDIDATE verdict points you to `recover <operationId>`, which returns the read-only safe-recovery verdict described in the companion retry article.
88
+
89
+ What the sequence deliberately refuses to do: all three steps are read-only. None of them re-executes the tool, re-settles the payment, or triggers a retry. `recover` states its verdict and stops there.
90
+
91
+ Tested: yes. The veyline command suite covers evidence reporting (including the honest no-basis case), explain assessments, and the read-only recover decisions.
92
+
93
+ Limitation: everything here answers from the ledger's recorded events. If the operation was never recorded — or the execution record lives only with the resource operator — `evidence` reports no basis, and the remaining steps can only tell you what is missing, not fill it in.
94
+
95
+ ## SOURCES / VERIFICATION SCOPE
96
+
97
+ Protocol claims cite the x402 v2 spec and the issue tracker link in the frontmatter, independently of callx402. Callx402 claims above were checked against the source tree (`core/veyline.js`, `bin/callx402.js`) and the veyline command test suite (`test/veyline-commands.test.js`) as of 2026-10-06. The tool was not exercised live against a mainnet facilitator for this article.
@@ -0,0 +1,106 @@
1
+ ---
2
+ id: CX402-SAFFRETRY-001
3
+ title: "x402 retry after payment: when it's safe and when it double-pays"
4
+ category: safe-retry
5
+ severity: critical
6
+ economic_risk: "Retrying after an ambiguous failure can double-charge the buyer; not retrying can abandon a paid result. Both directions cost money."
7
+ search_phrases: ["x402 retry after payment", "x402 safe retry", "x402 duplicate payment retry", "x402 timeout after paying", "x402 AuthorizationUsed retry"]
8
+ reading_minutes: 4
9
+ sources: ["https://github.com/x402-foundation/x402/issues/452", "https://github.com/x402-foundation/x402/issues/831"]
10
+ related: ["CX402-SETTLEPEND-001", "CX402-DUPPAY-001"]
11
+ updated: 2026-10-06
12
+ ---
13
+
14
+ # x402 retry after payment: when it's safe and when it double-pays
15
+
16
+ ## THE PROBLEM
17
+
18
+ Your request timed out after payment was prepared or sent. Or `/settle`
19
+ returned an error you can't interpret. The payment may have gone through; it
20
+ may not have. Every instinct says "just try again" — and that instinct is
21
+ exactly what causes duplicate payments in x402.
22
+
23
+ ## WHY IT HAPPENS
24
+
25
+ Two protocol facts combine into this trap:
26
+
27
+ 1. **Duplicate submissions are ambiguous.** The x402 spec doesn't define how
28
+ facilitators handle the same payload submitted twice. In practice, retrying
29
+ the same EIP-3009 authorization after a transient failure can trigger an
30
+ `AuthorizationUsed` revert in the token contract, surfaced as
31
+ `success: false` — which is indistinguishable from a genuine failure
32
+ ([x402-foundation/x402#452](https://github.com/x402-foundation/x402/issues/452)).
33
+ You can't tell "already settled, stop" from "actually failed, try again."
34
+
35
+ 2. **Timeouts don't mean failures.** x402 integrations commonly run behind
36
+ edge networks, serverless functions, and proxies with strict timeouts. A
37
+ timeout after the payment was sent tells you nothing about whether the
38
+ facilitator processed it
39
+ ([x402-foundation/x402#831](https://github.com/x402-foundation/x402/issues/831)).
40
+ The issue text is blunt: without guidance, "clients may retry in unsafe
41
+ ways, potentially leading to duplicate payments."
42
+
43
+ So the retry decision is being made with systematically incomplete information,
44
+ and both wrong answers cost money: retry into a double-pay, or don't retry and
45
+ abandon a result you already paid for.
46
+
47
+ ## DO NOT DO THIS
48
+
49
+ Do not blindly re-sign and resubmit after any ambiguous failure — timeout,
50
+ `settlement_pending`, `AuthorizationUsed`, or an opaque `invalid_payload`.
51
+ Each fresh signature is a fresh authorization to move funds. If the first one
52
+ settled, you've now paid twice.
53
+
54
+ Do not assume an error response means "no money moved." In async settlement,
55
+ error responses describe the facilitator's knowledge, not the chain's state.
56
+
57
+ ## THE SAFE FIX
58
+
59
+ Retry is safe only when one of these is true:
60
+
61
+ 1. **You can prove the first attempt is dead.** For `settlement_pending`, the
62
+ spec requires the broadcast hash — check it on chain. Only re-sign after
63
+ the original is provably failed or dropped.
64
+ 2. **The failure is pre-broadcast.** If `/verify` rejected the payload
65
+ (invalid signature, insufficient balance, malformed), nothing went on
66
+ chain. Fix the payload and submit — but reuse the same idempotency key if
67
+ your client supports one, so a delayed duplicate is deduped.
68
+ 3. **You have an idempotency mechanism.** If your integration keys retries by
69
+ the EIP-3009 nonce (proposed upstream in #452), a duplicate submission
70
+ resolves to "already settled" instead of a second charge. Until the
71
+ ecosystem standardizes this, implement it client-side: one nonce per
72
+ intent, never mint a second authorization for the same intent while the
73
+ first is unresolved.
74
+
75
+ The decision tree is: **evidence first, signature second.** Never sign before
76
+ you've checked what the first signature did.
77
+
78
+ ## VERIFY
79
+
80
+ Reconcile exactly one on-chain transfer per intent: one transaction hash,
81
+ correct recipient, correct amount, confirmed. If your retry produced a second
82
+ confirmed transfer for the same intent, the retry logic is unsafe — fix it
83
+ before it runs in production again. Log every retry decision with the evidence
84
+ that justified it; "we retried because the timeout expired" is not evidence.
85
+
86
+ ## Using Callx402 for this condition
87
+
88
+ The evidence-first decision tree above is what the `recover` action implements. It never initiates anything; it only evaluates:
89
+
90
+ ```
91
+ callx402 recover <operationId> --identity <id>
92
+ ```
93
+
94
+ It accepts an operation id, plus an operation identity: `--identity` directly, or `--evidence` JSON carrying the tool name, payer, and payment-authorization fingerprint (it builds the identity from those fields when `--identity` is absent). It evaluates the recorded history against that identity and returns a recovery state — RECOVERABLE, SAFE_RETRY, or anything else, which defaults to HUMAN_REVIEW.
95
+
96
+ It returns the decision with its reasoning and a terminal assessment, ending with the explicit line "Read-only: nothing charged, nothing executed."
97
+
98
+ What it deliberately refuses to do: it never charges, never executes, and never retries on your behalf. When the settlement state behind the operation is UNKNOWN, the recovery path refuses outright — an explicit retry after an unknown settlement could double-spend, so the pipeline demands manual settlement resolution first (the `resolve` action in the companion settlement article) and offers no bypass.
99
+
100
+ Tested: yes. The veyline command suite covers RECOVERABLE and SAFE_RETRY decisions, the identity-from-evidence fallback, the unknown-identity refusal path, and the disabled-subsystem refusal (exit 3).
101
+
102
+ Limitation: it reasons from recorded evidence only. If the operation was never recorded in the ledger, there is no basis for a verdict, and it says so instead of inventing one.
103
+
104
+ ## SOURCES / VERIFICATION SCOPE
105
+
106
+ Protocol claims cite the x402 issue tracker links in the frontmatter, independently of callx402. Callx402 claims above were checked against the source tree (`core/veyline.js`, `bin/callx402.js`) and the veyline command test suite (`test/veyline-commands.test.js`) as of 2026-10-06. The tool was not exercised live against a mainnet facilitator for this article.
@@ -0,0 +1,92 @@
1
+ ---
2
+ id: CX402-SETTLEPEND-001
3
+ title: "x402 settlement_pending: what it means and why retrying can double-pay"
4
+ category: settlement-pending
5
+ severity: critical
6
+ economic_risk: "Blind retry after settlement_pending signs a second authorization; two on-chain transfers for one intent."
7
+ search_phrases: ["x402 settlement_pending", "x402 settlement pending what to do", "x402 settle retry pending", "x402 broadcast but not confirmed"]
8
+ reading_minutes: 4
9
+ sources: ["https://github.com/x402-foundation/x402 (v2 spec, section 9)", "https://github.com/hummusonrails/x402-facilitator/blob/HEAD/README.md", "https://github.com/x402-foundation/x402/issues/452"]
10
+ related: ["CX402-SAFFRETRY-001", "CX402-DUPPAY-001"]
11
+ updated: 2026-10-06
12
+ ---
13
+
14
+ # x402 `settlement_pending`: what it means and why retrying can double-pay
15
+
16
+ ## THE PROBLEM
17
+
18
+ Your `/settle` call returned `success: false` with `errorReason: "settlement_pending"`.
19
+ The payment isn't confirmed, but it isn't failed either. You're staring at an
20
+ ambiguous state: did the money move or not?
21
+
22
+ ## WHY IT HAPPENS
23
+
24
+ In the x402 v2 spec (§9), `settlement_pending` means exactly this: "the settlement
25
+ transaction was broadcast but its confirmation could not be established." The
26
+ facilitator put your transaction on chain, but couldn't confirm it made it into
27
+ a block — RPC timeout, congestion, or the facilitator gave up waiting.
28
+
29
+ Critically, the spec marks this code **non-terminal**: the transaction may still
30
+ confirm on chain after the facilitator stopped watching. A `SettleResponse`
31
+ carrying this code MUST include the broadcast transaction hash and network, so
32
+ you can reconcile on chain before deciding anything.
33
+
34
+ This is the fundamental ambiguity of async settlement: "I don't know yet" is a
35
+ valid, expected state, not an error in the usual sense.
36
+
37
+ ## DO NOT DO THIS
38
+
39
+ Do not treat `settlement_pending` as failure and sign a fresh authorization.
40
+ This is the single most expensive mistake in this state: your first transaction
41
+ may confirm minutes later, and now you've authorized two transfers for one
42
+ intent. Double payment, no error message, no warning.
43
+
44
+ Also do not hammer `/settle` with the same payload in a tight loop. The x402
45
+ issue tracker documents that duplicate submissions can surface as
46
+ `AuthorizationUsed` reverts, which look like genuine failures — so now you have
47
+ two indistinguishable problems instead of one
48
+ ([x402-foundation/x402#452](https://github.com/x402-foundation/x402/issues/452))..
49
+
50
+ ## THE SAFE FIX
51
+
52
+ 1. **Extract the broadcast hash** from the `SettleResponse` (`transaction` and
53
+ `network` fields — the spec requires them on this code).
54
+ 2. **Reconcile on chain first.** Look up the transaction hash on a block
55
+ explorer or via RPC for the reported network. Three outcomes:
56
+ - **Confirmed:** settlement happened. Record it, move on. Do not retry.
57
+ - **Failed/dropped:** the transaction provably did not go through. Now —
58
+ and only now — is it safe to sign a fresh authorization.
59
+ - **Still unconfirmed:** wait and re-check. Set a deadline (e.g., 10 minutes
60
+ past broadcast); only sign again after the deadline with no confirmation.
61
+ 3. **Never sign a second authorization for the same intent** while the first
62
+ hash is still potentially live.
63
+
64
+ ## VERIFY
65
+
66
+ The issue is resolved when exactly one of these is true: the original broadcast
67
+ hash shows a confirmed on-chain transfer to the correct recipient for the
68
+ correct amount — or a replacement authorization was signed only after the
69
+ original was proven dead, and the replacement confirmed. Check your ledger:
70
+ one intent, one transfer. If you see two, the retry was unsafe.
71
+
72
+ ## Using Callx402 for this condition
73
+
74
+ The `resolve` action runs the same reconciliation logic from one place. Feed it the evidence bundle you gathered above:
75
+
76
+ ```
77
+ callx402 resolve --evidence '{"txHash":"0x...","network":"base","chainState":"pending"}'
78
+ ```
79
+
80
+ It accepts a JSON string (or `@file`) describing what you know: typically the broadcast transaction hash, the network, the on-chain state you observed, and any facilitator responses. It evaluates the bundle through the settlement resolver, which deterministically maps it to one of six certainty states — DEFINITELY_PAID, DEFINITELY_NOT_PAID, AUTHORIZED_NOT_SETTLED, SETTLEMENT_PENDING, CONFLICT, UNKNOWN — and attaches a retry policy, a confidence level, and the basis for the verdict.
81
+
82
+ It returns a disposition statement, the settlement state, the transaction hash, and the full resolution record. When the evidence is too thin to decide, the state is UNKNOWN and the command exits 5 rather than guessing.
83
+
84
+ What it deliberately refuses to do: the resolver is read-only analysis. It never queries the chain itself, never signs, never retries, and never repays. An UNKNOWN state stays UNKNOWN unless an operator records an explicit, auditable override — it will not silently become a repay.
85
+
86
+ Tested: yes. Dispatch tests cover the UNKNOWN path (exit 5) and the disabled-subsystem refusal (exit 3).
87
+
88
+ Limitation: the verdict is only as good as the evidence you supply. It organizes what you found; it does not do the chain lookup for you, and it cannot improve on a hash you never reconciled.
89
+
90
+ ## SOURCES / VERIFICATION SCOPE
91
+
92
+ Protocol claims cite the x402 v2 spec and the issue tracker links in the frontmatter, independently of callx402. Callx402 claims above were checked against the source tree (`core/index.js`, `core/subsystems.js`, `bin/callx402.js`, the settlement resolver) and the dispatch test suite (`test/cli-dispatch.test.js`) as of 2026-10-06. The tool was not exercised live against a mainnet facilitator for this article.
@@ -0,0 +1,119 @@
1
+ ---
2
+ id: CX402-SOLANAFAIL-001
3
+ title: "x402 settlement on Solana: blockhash expiry, phantom pending, and Token-2022"
4
+ category: solana-settlement
5
+ severity: high
6
+ economic_risk: "Authorizations expire mid-operation on Solana's ~90s blockhash window; terminal on-chain failures misreported as pending cause infinite reconciliation loops; Token-2022 mints break classic-SPL settlement code."
7
+ search_phrases: ["x402 solana settlement failed", "x402 solana blockhash expired", "x402 settlement_pending solana", "x402 token-2022 settlement"]
8
+ reading_minutes: 4
9
+ sources: ["https://github.com/x402-foundation/x402/issues/646", "https://github.com/x402-foundation/x402/issues/3644", "https://github.com/nirholas/three.ws/commit/624e1a6"]
10
+ related: ["CX402-SETTLEPEND-001", "CX402-SAFFRETRY-001"]
11
+ updated: 2026-10-06
12
+ ---
13
+
14
+ # x402 settlement on Solana: blockhash expiry, phantom pending, and Token-2022
15
+
16
+ ## THE PROBLEM
17
+
18
+ x402 settlement on Solana fails in ways EVM experience does not prepare you
19
+ for. Three distinct ones: payments die after a minute or two no matter what
20
+ timeout you configure; a transaction the chain already killed comes back
21
+ labeled `settlement_pending`; and settlement code that works fine for USDC
22
+ builds transactions that cannot execute against Token-2022 mints.
23
+
24
+ ## WHY IT HAPPENS
25
+
26
+ **1. Blockhash expiry is a hard wall.** Solana transactions reference a recent
27
+ blockhash valid for roughly 80–90 seconds. As
28
+ [x402-foundation/x402#646](https://github.com/x402-foundation/x402/issues/646)
29
+ documents, `maxTimeoutSeconds` cannot be enforced on Solana past that window —
30
+ production settlements fail after 1–2 minutes regardless of configured
31
+ timeout. Long-running operations (AI inference, data processing) cannot use
32
+ the standard flow: the authorization's blockhash dies before settlement is
33
+ attempted.
34
+
35
+ **2. Terminal failures wear a pending mask.** In Go SDK v2.27.0, the exact-SVM
36
+ settlement path reported a confirmed on-chain execution failure as
37
+ `settlement_pending`. The issue is blunt: "This transaction is not pending:
38
+ the chain confirmed that instruction 2 failed" — an SPL `OwnerMismatch` on
39
+ devnet, terminal, reported as pending, causing "callers to retry
40
+ reconciliation for a terminal transaction"
41
+ ([x402-foundation/x402#3644](https://github.com/x402-foundation/x402/issues/3644)).
42
+ On Solana, `settlement_pending` from an affected SDK version means less than
43
+ it says.
44
+
45
+ **3. Token-2022 is not classic SPL.** Settlement code that assumes the classic
46
+ token program builds a transaction that cannot execute against a Token-2022
47
+ mint: the derived source ATA does not exist and the instruction targets a
48
+ program that does not own the mint. A real production fix for exactly this
49
+ ([three.ws@624e1a6](https://github.com/nirholas/three.ws/commit/624e1a6)).
50
+ USDC is classic SPL; assuming every mint behaves like USDC is the bug.
51
+
52
+ ## DO NOT DO THIS
53
+
54
+ Do not treat Solana `settlement_pending` as "wait longer" without checking
55
+ the chain — on affected SDK versions it may be a terminal failure in disguise,
56
+ and waiting just burns your reconciliation budget.
57
+
58
+ Do not retry a failed Solana settle with the same transaction. The blockhash
59
+ is expired; the retry is dead on arrival. Build fresh.
60
+
61
+ Do not assume mint behavior from the token symbol. Check which token program
62
+ owns the mint before constructing the transfer.
63
+
64
+ ## THE SAFE FIX
65
+
66
+ 1. **Fit inside the blockhash window.** Pre-simulate the settlement
67
+ transaction, then submit promptly. For operations longer than ~60 seconds,
68
+ restructure the flow: settle first, or split authorization from the long
69
+ operation so the blockhash is fresh at submit time.
70
+ 2. **On `settlement_pending`, look the signature up immediately** on an
71
+ explorer or RPC. If the chain shows a failed instruction, the transaction
72
+ is terminal — stop reconciling and treat it as failed, not pending.
73
+ 3. **Check the token program before building the transfer.** Query the mint's
74
+ owner program: classic SPL Token vs Token-2022. Derive associated token
75
+ accounts against the correct program id.
76
+ 4. **Pin and audit your SDK version.** If you run the Go SDK's exact-SVM
77
+ path, confirm you are past the v2.27.0 misreporting fix before trusting
78
+ `settlement_pending` at all.
79
+
80
+ ## VERIFY
81
+
82
+ Settlements confirm on-chain inside the blockhash window; a terminally failed
83
+ transaction is classified terminal (never "pending"); Token-2022 mints
84
+ settle end to end on devnet before mainnet. Re-run the #3644 repro (SPL
85
+ `OwnerMismatch`) and confirm your stack reports failure, not pending.
86
+
87
+ ## Using Callx402 for this condition
88
+
89
+ The condition above is exactly what `resolve` is for on Solana: it takes
90
+ the broadcast signature and the chain state you looked up yourself and
91
+ judges which of them to believe. Supply the facilitator's response and
92
+ your own RPC or explorer result as separate evidence items; the resolver
93
+ applies a fixed precedence where on-chain state is ground truth for
94
+ whether money moved. A facilitator that reports pending while the chain
95
+ shows a failed instruction resolves as a terminal failure or a conflict —
96
+ never as an instruction to keep waiting. This is unexercised against live
97
+ Solana RPC in this build; the resolver works from the chain state you
98
+ hand it, not from a call it makes itself.
99
+
100
+ It does not build Solana transactions, refresh expired blockhashes, or
101
+ correct a Token-2022 program mismatch; those stay manual. It will not
102
+ retry or repay on your behalf — on evidence it cannot decide it returns
103
+ UNKNOWN and stays fail-closed, a behavior the test suite covers. For the
104
+ #3644 pattern, the practical use is feeding the facilitator's
105
+ `settlement_pending` alongside the explorer's failed-instruction record
106
+ and letting the classifier weigh the two instead of trusting the label.
107
+
108
+ ## SOURCES AND VERIFICATION SCOPE
109
+
110
+ - The blockhash window limit, the terminal-failure-reported-as-pending bug
111
+ (Go SDK v2.27.0, SPL `OwnerMismatch` on devnet), and the Token-2022 mint
112
+ fix are cited from the x402-foundation issues and the three.ws commit
113
+ linked in the front matter, current as of 2026-10-06.
114
+ - callx402 claims cite the current implementation: the resolver's
115
+ on-chain-as-ground-truth precedence from
116
+ `lib/settlement-resolver.js`, and its fail-closed UNKNOWN behavior from
117
+ the test suite; live Solana RPC reconciliation is noted as unexercised
118
+ because the resolver is mocks/local-only in this build.
119
+ - Problem and fix content verified independently of callx402.
@@ -0,0 +1,101 @@
1
+ ---
2
+ id: CX402-VERSET-001
3
+ title: "x402 verify works but settle fails: the trust gap between the two calls"
4
+ category: facilitator-settle
5
+ severity: high
6
+ economic_risk: "Verify-passing authorizations can be invalid at settle time (funds moved, nonce reused); sellers who act on verify alone do unpaid work. Opaque settle errors also stall integrations."
7
+ search_phrases: ["x402 verify works settle fails", "x402 invalid_payload settle", "x402 verify then settle", "x402 settle 400 invalid_payload"]
8
+ reading_minutes: 4
9
+ sources: ["https://github.com/x402-foundation/x402/issues/961", "https://github.com/x402-foundation/x402/issues/447", "https://dev.to/mkmkkkkk/x402-payment-timeouts-why-your-agent-loses-money-and-how-to-fix-it-fgk"]
10
+ related: ["CX402-SETTLEPEND-001", "CX402-SAFFRETRY-001"]
11
+ updated: 2026-10-06
12
+ ---
13
+
14
+ # x402 verify works but settle fails: the trust gap between the two calls
15
+
16
+ ## THE PROBLEM
17
+
18
+ `/verify` returns success. You proceed — and `/settle` fails, sometimes with an
19
+ opaque `{"errorReason":"invalid_payload"}` and a 400 that tells you nothing
20
+ about what went wrong. Or worse: you're a seller, you did the work after
21
+ verify passed, and settlement never completes.
22
+
23
+ ## WHY IT HAPPENS
24
+
25
+ `/verify` and `/settle` answer different questions at different times, and the
26
+ world can change between them:
27
+
28
+ 1. **Verify checks the authorization; settle moves the money.** An EIP-3009
29
+ authorization that is valid at verify time can be invalid at settle time:
30
+ the buyer withdrew funds between the calls, submitted the same authorization
31
+ to two sellers at once, or reused a nonce. Circle's payments team raised
32
+ exactly this double-spend pattern upstream
33
+ ([x402-foundation/x402#447](https://github.com/x402-foundation/x402/issues/447)).
34
+ Verify is a point-in-time opinion, not a guarantee.
35
+
36
+ 2. **Settle has undocumented requirements.** In one documented case, verify
37
+ passed but settle rejected every attempt with `invalid_payload`. Root cause,
38
+ found only after days of debugging: the token `name` field had to be
39
+ `"USD Coin"`, not `"USDC"`, and amounts had a $0.001 minimum — neither
40
+ requirement in the spec
41
+ ([x402-foundation/x402#961](https://github.com/x402-foundation/x402/issues/961)).
42
+
43
+ So "verify passed" means "this looked fine a moment ago," and settle failures
44
+ range from adversarial (double-spend) to bureaucratic (a string field).
45
+
46
+ ## DO NOT DO THIS
47
+
48
+ **Sellers: do not perform work or deliver goods on the strength of `/verify`
49
+ alone.** The verify-then-serve pattern is the double-spend vector: by the time
50
+ you settle, the authorization may be worthless, and you've already done the
51
+ work. This isn't theoretical — it's the exact pattern in #447.
52
+
53
+ **Builders: do not loop verify→settle retries** hoping the opaque error
54
+ resolves itself. If settle rejects the payload, re-verifying the same payload
55
+ changes nothing and burns time.
56
+
57
+ ## THE SAFE FIX
58
+
59
+ 1. **Read the settle error literally.** `invalid_payload` at settle with a
60
+ passing verify means the payload violates a settle-time rule. Check: exact
61
+ token `name` string (`"USD Coin"`), amount minimums, network/asset match
62
+ against the 402 requirements, and EIP-3009 field formatting (validAfter /
63
+ validBefore windows, nonce encoding).
64
+ 2. **Diff your payload against the 402 challenge**, field by field. The most
65
+ common settle-only rejections are mismatches the verify step doesn't check.
66
+ 3. **Sellers: settle before serving, or serve only what you'd give away.**
67
+ If your flow must do work before settlement completes, cap the exposure
68
+ per request and treat verify as advisory.
69
+ 4. **Log both responses with timestamps.** When the gap between verify and
70
+ settle is large, suspect state change (funds moved) rather than payload bugs.
71
+
72
+ ## VERIFY
73
+
74
+ The issue is resolved when `/settle` returns success for a payload that
75
+ `/verify` accepted, with the differences between the two calls understood and
76
+ documented in your integration. For sellers: the fix is verified when no work
77
+ is performed before settlement is confirmed — test with an authorization that
78
+ you deliberately invalidate between verify and settle, and confirm your system
79
+ refuses to serve.
80
+
81
+ ## Using Callx402 for this condition
82
+
83
+ The verify-then-settle diff described in the SAFE FIX section is what the `diagnose` action performs over supplied evidence:
84
+
85
+ ```
86
+ callx402 diagnose --evidence '{"verifyResponse":{...},"settleResponse":{...}}'
87
+ ```
88
+
89
+ It accepts a JSON evidence bundle (or `@file`, or `--target`): here, both the `/verify` and `/settle` responses, with timestamps if you have them. It evaluates the bundle through the x402 doctor, which runs its failure classifiers deterministically over what you supplied and reports what failed and why — a payload mismatch the verify step does not check, a settle-time rule violation, or a state change between the two calls.
90
+
91
+ It returns the doctor's report: what failed, per-stage findings, and an explanation. Exit 0 on a completed diagnosis.
92
+
93
+ What it deliberately refuses to do: it takes no action on the facilitator — no re-verification, no resubmission, no retry of anything. Malformed evidence is rejected as a usage error rather than diagnosed, and a disabled subsystem produces an honest unavailable envelope instead of a guess.
94
+
95
+ Tested: yes. Dispatch tests cover the enabled path (real doctor report with per-stage findings), the disabled-subsystem refusal, and the `doctor` alias.
96
+
97
+ Limitation: classification is only as good as what you hand it. It does not call the facilitator, does not check the chain, and cannot discover a settle-time rule that is not visible in the responses you supplied.
98
+
99
+ ## SOURCES / VERIFICATION SCOPE
100
+
101
+ Protocol claims cite the x402 issue tracker and the dev.to case study in the frontmatter, independently of callx402. Callx402 claims above were checked against the source tree (`core/index.js`, `bin/callx402.js`) and the dispatch test suite (`test/cli-dispatch.test.js`) as of 2026-10-06. The tool was not exercised live against a mainnet facilitator for this article.
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file