spend
Execute one governed outbound payment across a selected runtime path, with quote, reservation, approval, rail evidence, recovery, and receipt-before-success.
- License 许可
- MIT
- 所属仓库
- ZachDreamZ/runx
- 最近更新
- 2026-07-17
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- spend
- runx
- { "category": "payments" }
- description
- Execute one governed outbound payment across a selected runtime path, with quote, reservation, approval, rail evidence, recovery, and receipt-before-success.
02 资源文件 6
- 参考文档fixtures/spend-accept-ceiling.yaml8.7 KB
- 参考文档fixtures/spend-mock-path.yaml7.1 KB
- 参考文档fixtures/spend-mpp-path.yaml7.1 KB
- 参考文档fixtures/spend-stripe-spt-path.yaml7.7 KB
- 参考文档fixtures/spend-x402-path.yaml7.1 KB
- 参考文档X.yaml18.7 KB
03 SKILL.md 正文
Spend
Execute one governed outbound payment.
This skill is the public buyer-side payment verb. It turns a payment-required signal into a quote, reserves a child payment authority under the parent grant, passes an approval gate when required, fulfills exactly one runtime path, and returns rail evidence that must seal before the paid action can be treated as successful.
The runtime path is not a separate authority model. Stripe SPT, x402, MPP, and
mock are selectable paths inside the same governed spend. Some paths also have
branded catalog facades (x402-pay, stripe-pay) because those names help
users discover and invoke the capability, but those facades still execute this
same quote -> reserve -> approve -> fulfill -> seal flow.
What this skill does
- Normalize the payment signal. Use
pay-quoteto bind amount, currency, operation, counterparty, candidate runtime paths, realm, expiry, and idempotency material. - Reserve authority. Use
pay-reserveto prove the child spend authority is a subset of the parent payment grant and to mint a single-use spend capability reference. - Gate the mutation. Require approval when policy or realm demands it. A rail runner must not receive spend authority until the gate records an approved decision.
- Fulfill exactly one runtime path. Use
pay-fulfill-railwith the selected runner (mock,x402,mpp, orstripe-spt) and carry only scoped capability references, never raw funding material. - Preserve recovery evidence. If the rail response is ambiguous, report the idempotency state and recovery hint instead of retrying under a new key.
- Seal before success. The spend is successful only when the receipt carries quote, reservation, approval, rail proof, redaction notes, and finality.
It does not decide provider-side pricing, verify inbound customer credentials, settle a refund, answer a dispute, or expose unrestricted rail credentials.
When to use this skill
- A tool, service, or counterparty returns a payment-required signal and the caller has a parent payment authority grant.
- A harness needs to exercise the same governed spend flow over multiple runtime paths.
- An operator wants one receipt chain that proves quote, reservation, approval, rail fulfillment, and recovery posture for an outbound payment.
- A future real-rail demo needs to swap a deterministic mock path for x402, Stripe SPT, MPP, or CDP without changing the canonical spend semantics.
When not to use this skill
- To price an inbound service that runx exposes to another agent. Use
charge-priceandcharge-verify. - To issue or reverse a refund. Use the refund verb when it lands, preserving the original charge/spend receipt link.
- To run a rail directly because credentials are available. Runtime paths are children of this skill and must receive only scoped spend capability refs.
- To retry after a timeout with a new idempotency key. Recover under the same reservation first.
- To accept raw API keys, card numbers, unrestricted provider tokens, seed phrases, webhook secrets, or bearer tokens as skill inputs.
Procedure
- Validate
payment_signal,parent_payment_authority, andrail_profile_ref. - Select the runtime path from the signal and allowed policy. If more than one
path is possible, select by policy preference; if policy cannot decide,
return
needs_agent. - Run
pay-quotewith the signal, realm, and idempotency seed. Stop when the quote is missing amount, currency, counterparty, operation, runtime path, or stable idempotency material. - Run
pay-reservewith the quote and parent authority. The child authority must be a subset of the parent grant and must not broaden amount, currency, operation, counterparty, realm, period, runtime path, or capability. - If approval is required, pause at the spend gate and record the operator decision in the receipt. A denied or missing approval prevents fulfillment.
- Run
pay-fulfill-railfor the selected runtime path. Pass the payment challenge, reserved authority, spend capability ref, rail profile ref, idempotency packet, and quote packet. - Redact secret-bearing rail material. The receipt may contain proof refs, provider event refs, credential refs, hashes, and redaction notes; it must not contain raw funding material.
- If fulfillment is ambiguous, return a recovery status and require
pay-recoverbefore any retry. If fulfillment is proven, seal the spend receipt before reporting success.
Runtime paths
| Path | Use when | Required proof/evidence | Secret handling |
|---|---|---|---|
mock |
Deterministic local fixtures, CI, and docs. | Mock proof ref, amount, currency, counterparty, idempotency key. | No real funding material; still redact rail session material. |
x402 |
A paid resource returns an x402-compatible challenge. | x402 payment proof ref, facilitator or receipt proof ref when available, challenge id, idempotency key. | Do not print wallet private keys, bearer tokens, or raw payment payloads. |
mpp |
An MPP profile is configured for the selected counterparty. | MPP settlement proof ref, profile ref, amount, currency, idempotency key. | Treat profile/session material as secret; output refs only. |
stripe-spt |
An explicit test profile is selected locally, or a hosted Stripe payment provider owns live credential custody. | Stripe charge id, payment intent id when present, provider event id, scoped SPT ref, idempotency key. | The local adapter refuses live profiles; never accept or emit Stripe secret keys, webhook secrets, card data, PANs, or unrestricted tokens. |
Future paths such as CDP must fit this table before they become runnable: named authority bounds, scoped credential reference, verifier evidence, redaction rules, idempotency behavior, and recovery behavior.
Edge cases and stop conditions
- Missing or ambiguous runtime path: return
needs_agent; do not guess a rail from available credentials. - Quote drift: stop when the challenge, amount, currency, operation, counterparty, or runtime path changes after quote.
- Parent grant too broad or too narrow: reserve only a child subset. If the
child cannot cover the quoted spend without widening, return
needs_agent. - Approval denied or absent: do not call the rail runner.
- Raw credential material appears in input: refuse or redact and return
needs_agent; the rail runner accepts scoped references only. - Ambiguous rail response: do not retry under a new idempotency key. Return recovery-required evidence.
- Proofless success claim: return
escalated; a paid action cannot be marked successful without rail proof and a sealed receipt. - Fixture path used in production: refuse unless the realm is explicitly
localortest.
Output schema (payment_execution)
decision: sealed | denied | needs_agent | escalated
runtime_path: mock | x402 | mpp | stripe-spt
payment_quote_packet:
payment_quote: object
requested_payment_authority: object
challenge_evidence: object | null
payment_reservation_packet:
payment_decision: object
reserved_payment_authority: object
spend_capability_ref: object
idempotency: object
payment_admission: object | null
payment_approval:
approved: boolean
gate_id: string
decided_by: string | null
effect_evidence_packet:
rail_result: object
rail_proof: object
credential_envelope: object
redactions: [string]
recovery_hint: object
sealed_receipt_ref: string | null
open_questions: [string]
A sealed decision requires a selected runtime path, subset reservation proof,
approved gate when required, rail proof, redaction notes for secret-bearing
fields, and a sealed receipt ref.
Worked example
An x402-compatible paid search endpoint returns a challenge for 1.25 USD,
counterparty merchant:demo, and operation search.paid. The parent grant
allows payment commits up to 1.25 USD for that counterparty in realm test.
spend quotes the challenge, reserves a child authority with the same amount,
currency, operation, counterparty, and path x402, records the approval gate,
fulfills through pay-fulfill-rail runner x402, redacts rail session
material, and seals a receipt containing the x402 proof ref and idempotency key.
The result is decision: sealed.
If the same endpoint changes the amount after quote, the skill returns
decision: needs_agent or escalated depending on where drift is detected. It
does not silently re-quote and spend under the old approval.
Inputs
payment_signal(required): payment-required signal or challenge.parent_payment_authority(required): parent payment authority term or authority reference.rail_profile_ref(required): configured runtime-path profile reference.payment_admission(optional): hosted payment admission token and settlement identity. When present, it must be passed unchanged to the rail fulfillment stage so the sealed supervisor evidence can prove hosted settlement identity.realm(optional): authority realm such aslocal,test, orprod.spend_policy(optional): policy limits and approval thresholds.approval_context(optional): prior approval evidence.idempotency_seed(optional): stable idempotency material.
04 同仓库更多 Skills
zapier-handoff
Validate a runx execution context and hand off a governed payload to a Zapier Catch Hook with scoped auth, idempotency, and receipt expectations.
x402-pay
Execute a governed x402 payment by delegating to the canonical spend flow with the x402 runtime path selected.
work-plan
Decompose a build objective into governed runx execution steps.
web-fetch
Fetch and extract one web source within an explicit allowlist, returning the content by digest with full provenance.
weather-forecast
Normalize provider weather evidence into an action-safe forecast packet with provenance, uncertainty, and stop conditions for downstream agents.
vuln-triage
Triage dependency or ecosystem vulnerability risk into remediation and advisory packets, grounding on verified CVE evidence when it is supplied.