tech.vauban/pay-mcp

Check a merchant's proven service history (an x402 STARK-receipt history document, e.g. https://demo.pay.vauban.tech/x402/v1/history). Fetches history_url, validates the document, and verifies a sample of entries: L1 = structure + per-entry invariants + JCS canonicalization; L2 = each sampled settlement transaction is read from Starknet Sepolia and must be SUCCEEDED (a visible entry must carry a value transfer or a recognized receipt event). Four verdicts, NEVER conflated: - PROVEN_SAMPLE: document valid, sampled entries verify at the announced level. - REFUTED: an element contradicts itself or the chain -- the response names it. - NO_RECORD: no proven history at this URL. Indeterminate, NOT negative. - UNREACHABLE: transport failure; says nothing about the merchant. An RPC failure during L2 degrades the level to L1 and says so; it never becomes REFUTED. Full STARK re-verification (L3) is not run here; the response carries the public docker command.

JCS (RFC 8785) canonicalize a JSON object then compute its SHA-256 hash. Returns base64-encoded canonical bytes and the hex digest.

Make a payment on Starknet Sepolia testnet. Call it with no arguments to get a real, sponsored settlement: we fund the testnet payment, so you need no wallet, no account and no STRK. Returns the transaction hash of YOUR payment plus a Voyager link, and you can read it back from any Sepolia RPC you trust. Pass amount_wei (a decimal string in STRK-wei) to choose the amount, within the published cap. The payee is fixed by the sponsor, so this is a funded demo and not a faucet. If you would rather pay from your own account, set PAY_MCP_SEPOLIA_ACCOUNT_ADDRESS + PAY_MCP_SEPOLIA_PRIVATE_KEY and this tool switches to your signer ; in that mode it emits a receipt hash through the PaymentDemoEmitter contract, which moves NO value and is not proof of a settled payment.

Fetch a resource gated behind x402 and complete the payment flow to obtain it -- the x402 CLIENT walk, which none of the other tools here perform. GET url: if it answers 200 directly, the resource was free (outcome no_payment_required -- not a failure, x402 gates specific endpoints, not the whole internet). If it answers 402, parses the PAYMENT-REQUIRED manifest, downloads a STARK proof from proof_url (defaulted to the published demo proof only when url's host is demo.pay.vauban.tech; REQUIRED for any other host -- never guessed), gunzips it in memory, and POSTs it back to url. PROOF SOURCE: the proof submitted is the one the merchant PRE-GENERATED and published. A 'paid' outcome carries proof.honesty stating what the resulting 200 establishes (a real STARK verification, really bound to the settlement) and its scope (the proof and the settlement are the merchant's published ones, not this agent's). Four outcomes, never conflated: no_payment_required (free), paid (200 after proof -- content + receipt + manifest + honesty label), refused (402 again after the proof was submitted -- the server's own reason, verbatim: a result, not a crash), unreachable (transport failure or an unrecognized HTTP status -- says nothing about the merchant). A missing proof_url on a non-demo host that requires payment returns a plain input error instead, since no request was ever sent to guess at. STANDARD x402 v2 (since 0.7.0): if the 402 carries the x402 foundation's PaymentRequired document (standard base64 of JSON, x402Version 2) with an exact offer on a Starknet network, this tool pays it the standard way instead: the configured Starknet account signs a SNIP-9 authorization for exactly that transfer, the merchant's facilitator settles it and pays the gas, and the same GET is retried with PAYMENT-SIGNATURE. A 'paid' outcome then carries standard{scheme, network, payTo, amount, asset, payer, feePayer}, the facilitator's receipt (transaction, network, payer) and an honesty note: value mo…

Pay an x402 resource on the SHIELDED rail (scheme vauban-shielded-strk20). Starknet Sepolia only: an offer on any other network is refused as unpayable (network_not_supported). It reads the offer, builds the X-VAUBAN-SHIELDED-SETTLEMENT header (vzk20-v2: pool coordinates plus a COMMITMENT), sends the STARK proof named by proof_path as the POST body, and returns the receipt from PAYMENT-RESPONSE. THE PROOF: proof_path names a proof file you already hold, READ FROM YOUR DISK AND SENT to url as given. It is read only inside the directory named by PAY_MCP_SHIELDED_PROOF_DIR (no default: unset, nothing is read, code proof_dir_unset), relative to it or absolute inside it, never through a symbolic link (proof_path_symlink) or a '..' component (proof_path_traversal), never outside it (proof_path_outside_dir), and only when the file has the form of a proof (proof_form_invalid); each refusal comes before any request. The offer says which proof it wants (extra.proof); an offer that asks for another form is refused before any upload (proof_form_mismatch). THE WITNESS: the witness that opens the commitment is yours. Pass it and this tool checks locally that it opens the commitment, that it is strictly under the published ceiling, and that neither of its numbers appears in the receipt served back. It is never sent, never returned and never logged; only the commitment travels. Or pass amount_commitment alone and the witness never reaches this tool at all. Scope: through the pool, the payer can stay out of the payment transaction when another account submits it; the payer's deposit into the pool is a public transaction of its own. THE PURCHASE SALT: when the offer announces a private receipt (extra.privateReceipt), PAY_MCP_WITNESS_DIR names a directory and payer_pseudonym is given, this tool draws one fresh random salt for this purchase, keeps it there in a 0600 file (purchase_salt_kept_at), and sends only a value derived from it: the salt itself never leaves this process. It also…

Create a DelegationGrant authorization object. Builds the grant with canon_version 'x402-jcs-v1.0.0', JCS-hashes it and returns the grant hash.

Check a receipt. Three modes, chosen by the arguments given: 1. Hash mode: receipt + expected_hash. Canonicalizes the receipt (JCS, RFC 8785), hashes it with SHA-256 and says whether the digest equals expected_hash. Nothing else about the receipt is checked. 2. Note-receipt mode: receipt alone, whose variant is 'payment-committed-note-v1'. Recomputes note_receipt_hash from the ten cells in note_cells and checks that the fields repeating a cell agree with it. It says only that the receipt is consistent with itself: not that a proof was verified, not that the pool note exists on chain, and nothing about the amount, which no cell carries. 3. Chain mode: tx_hash. Asks the node at STARKNET_RPC_URL which chain it serves (starknet_chainId): Starknet mainnet or Starknet Sepolia, named in network and chain_id with the matching Voyager link; any other chain is refused (status unknown_network) and nothing is read. Then reads the transaction and reports one of two things, checked in this order: on Sepolia only, a PaymentDemoEmitter receipt-hash emission, which moves no value (the receipt rebuilt from the event and its JCS hash), or a STRK Transfer event other than the fee payment (receipt_type starknet-transfer: execution status, block number, amount_wei, sender, recipient; who paid it is not established). A reverted transaction returns verified: false. A transaction that SUCCEEDED but carries neither returns verified: null with status not_a_recognised_payment: it exists and succeeded, and this tool does not read its form, which says nothing against it. A transaction the node does not see, or a read that fails, returns verified: null, never a verdict. Give either receipt (with or without expected_hash) or tx_hash, not both.