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.
- package/LICENSE +21 -0
- package/README.md +227 -2
- package/SPEC.md +264 -0
- package/bin/callx402.js +257 -0
- package/core/config.js +104 -0
- package/core/envelope.js +80 -0
- package/core/index.js +364 -0
- package/core/pipeline.js +371 -0
- package/core/remote.js +242 -0
- package/core/subsystems.js +136 -0
- package/dist/callx402-1.0.0.tgz +0 -0
- package/docs/ACTION_LANGUAGE.md +23 -0
- package/docs/MCP_IDENTITY.md +27 -0
- package/docs/README.md +315 -0
- package/docs/action-reference.md +247 -0
- package/docs/cli-help-verified-2026-10-06.txt +39 -0
- package/docs/logo.png +0 -0
- package/docs/problem-map.md +65 -0
- package/docs/troubleshooting/cx402-402afterfail-001-402-after-failed-settle.md +143 -0
- package/docs/troubleshooting/cx402-agentcap-001-agent-spending.md +114 -0
- package/docs/troubleshooting/cx402-eip3009-001-authorization-checklist.md +124 -0
- package/docs/troubleshooting/cx402-paidnores-001-paid-no-result.md +97 -0
- package/docs/troubleshooting/cx402-safretry-001-retry-after-payment.md +106 -0
- package/docs/troubleshooting/cx402-settlepend-001-settlement-pending.md +92 -0
- package/docs/troubleshooting/cx402-solanafail-001-solana-settlement.md +119 -0
- package/docs/troubleshooting/cx402-verset-001-verify-ok-settle-fails.md +101 -0
- package/docs/visuals/01-action-map.png +0 -0
- package/docs/visuals/02-diagnose.png +0 -0
- package/docs/visuals/03-resolve.png +0 -0
- package/docs/visuals/04-route.png +0 -0
- package/docs/visuals/05-preflight.png +0 -0
- package/docs/visuals/06-inspect.png +0 -0
- package/docs/visuals/07-status.png +0 -0
- package/docs/visuals/08-architecture.svg +49 -0
- package/docs/visuals/MANIFEST.md +40 -0
- package/docs/visuals/raw/01-help.out +39 -0
- package/docs/visuals/raw/02-diagnose.out +2 -0
- package/docs/visuals/raw/03-resolve.out +4 -0
- package/docs/visuals/raw/04-route.out +2 -0
- package/docs/visuals/raw/05-preflight.out +2 -0
- package/docs/visuals/raw/06-inspect.out +23 -0
- package/docs/visuals/raw/07-status.out +16 -0
- package/docs/visuals/render_terminal.py +149 -0
- package/docs/what-is-callx402.md +251 -0
- package/integrations/README.md +62 -0
- package/integrations/core.py +329 -0
- package/integrations/crewai/callx402_crewai.py +109 -0
- package/integrations/facilitator/settle-guard.js +99 -0
- package/integrations/langchain/callx402_tools.py +180 -0
- package/integrations/mcp-clients/README.md +121 -0
- package/integrations/n8n/callx402-incident-guard.json +1 -0
- package/mcp/README.md +63 -0
- package/mcp/index.js +239 -0
- package/package.json +39 -4
- package/scripts/drift-check.js +202 -0
- package/sdk/js/index.js +207 -0
- package/sdk/python/README.md +67 -0
- package/sdk/python/callx402/__init__.py +317 -0
- package/sdk/python/callx402/cli.py +193 -0
- package/sdk/python/pyproject.toml +30 -0
- package/sdk/python/setup.py +56 -0
- package/server/index.js +520 -0
- package/server/openapi.yaml +537 -0
- package/server.json +1 -0
- package/test/cli-dispatch.test.js +248 -0
- package/test/helpers.js +103 -0
- package/test/integrity.test.js +43 -0
- package/test/intent-pipeline.test.js +205 -0
- package/test/remote.test.js +166 -0
- package/test/safety.test.js +234 -0
- package/test/sdk.test.js +198 -0
- package/test/server.test.js +190 -0
- 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
|