ddg-payment-rail-verify

Prove an agent's payment path still works end to end and keep proving it: a paid smoke test, a 402-envelope pre-flight, and a buyer-side trust probe of the seller you depend on. Use before going live, after changing a wallet or SDK, and as a weekly canary. Receipt verification is free.

Payment code rots quietly: an SDK bump changes the signature shape, a wallet rotation breaks the payTo, a seller's 402 envelope drifts off-spec. This workflow proves the rail works and then keeps proving it on a schedule.

Endpoints: POST /v1/tx-smoke-test ($0.01), POST /v1/402/preflight ($0.01), POST /v1/x402/trust-probe ($0.01), POST /v1/receipt-verify (free), all on https://agents.daedalusdevelopmentgroup.com.

External cost: $0.01 per call in USDC on Base via x402; receipt verification is free and the smoke test is free for the first 25 calls/day per identity. No account or API key is required; the paid path needs an x402-capable client (wallet signer).

Free tier: /v1/tx-smoke-test is a funnel route — the first 25 calls/day per X-Agent-Id are free, which makes it a zero-cost canary until you want the receipt-only paid path. Send X-DDG-Free-Tier: skip when you specifically need the paid 200 + PAYMENT-RESPONSE receipt.

Procedure

1. Paid smoke test — prove your client can complete a real settlement and get a receipt header back:

   bash

   curl -s -D out/smoke.headers -X POST https://agents.daedalusdevelopmentgroup.com/v1/tx-smoke-test \
     -H 'content-type: application/json' -H "X-Agent-Id: $DDG_AGENT_ID" \
     -H "X-PAYMENT: $SIGNED_X402_PAYMENT" -d '{"request_label":"canary"}' > out/smoke.json
   grep -i '^payment-response\|^payment-receipt' out/smoke.headers
   

   A settled call returns 200, Payment-Receipt: x402-… and a base64 PAYMENT-RESPONSE naming the transaction. Missing PAYMENT-RESPONSE means a strict buyer SDK will treat the payment as failed — fix that before go-live.
2. Verify the receipt (free, no payment): POST the receipt hash to /v1/receipt-verify and confirm it resolves to your payment.
3. Pre-flight any endpoint you are about to depend on — the preflight probes a URL's 402 envelope and verdicts it against v1/v2 + MPP shape rules:

   bash

   curl -s -X POST https://agents.daedalusdevelopmentgroup.com/v1/402/preflight \
     -H 'content-type: application/json' -H "X-Agent-Id: $DDG_AGENT_ID" \
     -d '{"url":"https://seller.example.com/paid-route"}' > out/preflight.json
   

   Read the verdict list: accepts[] present, network format, atomic amounts, payTo. A seller that fails preflight will burn your settlement attempts.
4. Trust-probe the seller — challenge health, latency, and on-chain settlement history (distinct payers, recent settle tx):

   bash

   curl -s -X POST https://agents.daedalusdevelopmentgroup.com/v1/x402/trust-probe \
     -H 'content-type: application/json' -H "X-Agent-Id: $DDG_AGENT_ID" \
     -d '{"url":"https://seller.example.com/paid-route"}' > out/trust.json
   

   A single-payer, zero-recent-settle endpoint is a settlement risk, not a bargain.
5. Schedule the canary — weekly (or after every wallet/SDK change): smoke test + receipt verify are the minimum; add preflight/trust-probe for each seller you pay.
6. On 402 — the smoke test is paid by design once the allowance is used: take x402.accepts[0] (network eip155:8453, asset USDC, atomic amount), sign, and retry the identical body. upgrade_path in the body repeats this.

Cost math

Cadence	Calls	Cost
Weekly canary, inside free allowance	1 smoke + 1 verify	$0.00
Weekly canary, paid	1 smoke + 1 verify	$0.01
Pre-flight 5 sellers weekly	5 preflight + 5 trust-probe	$0.10

Failure handling

• 402 with payment_rejected → read payment_rejected.reason: settlement_failed means no funds moved, settlement_pending means a tx is in flight and the identical retry reconciles instead of re-charging. Never retry a changed body against a pending settlement.
• 409 payment_identity_mismatch → the settled payment belongs to another identity; retry with the paying identity, or pay again from the new one.
• 409 spend_limit_exceeded → your X-DDG-Max-Spend-USD header is below the route price; raise it deliberately rather than removing it.

Not for

• Not a substitute for reconciling your own on-chain payments; it verifies the rail and the receipts, not your accounting.
• Not for buyers who cannot sign x402 payments at all — use the free receipt-verify and preflight routes first to establish what you need.

Example

Ask: "Our settlement failed twice last week. Prove the rail works and set up something that would have caught it."

Before: payments tested by hand before launch, then untested for months; the first sign of breakage is a failed purchase in production.

After: a weekly canary that settles $0.01, verifies the receipt for free and alerts on any change in the 402 envelope or receipt headers — plus preflight and trust-probe verdicts for every seller the agent pays.

Version

1.0.0 — initial workflow bundle: smoke test + receipt verification + 402 preflight

• buyer-side trust probe with scheduling, free-tier awareness and settlement-state handling.