Introduction

WelcomeServices map

Guides

AcceptSpend

Legal

SecurityPrivacyTerms
PreviousVerify receiptNextPay (ledger)
BlogPrivacyTerms

Pay any MPP or x402 URL

Complete a Spend against any HTTPS URL that challenges with MPP or x402 under the wallet’s budget.

Same flow over HTTP: POST /spend/pay-url

Tool

rill_pay_url

This is the primary Spend path. Prefer a known Accept link (seed_gate / seller gate_url), then rill_discover. Rill fulfills the 402 and returns the upstream unlock body/headers. Optional directory_id looks up catalog probe_status / probe_method / body_hint when the URL fails. When body_hint is set, pass body with your own values. Do not send the hint as a paid call unless those values are what you intend to buy.

Auth

Wallet key required (rill_vw_* via session, RILL_VW_KEY, or vw_key). Missing key returns a clear error.

Parameters

ParameterTypeRequiredDescription
urlstringnoHTTPS URL of the paid resource or gate (or pass directory_id)
directory_idstringnoDirectory profile id from rill_discover, resolves pay_url and preferred method
methodstringnoHTTP method when probing; defaults to catalog probe_method or GET
max_amountnumbernoUSD ceiling for this pay (decimal dollars)
max_amount_centsnumbernoInteger cents ceiling; overrides max_amount when set
prefer_railauto|mpp|x402noWhen the gate offers both rails: auto (default) uses Base/x402 first; mpp forces Tempo; x402 forces Base only
headersobjectnoExtra request headers forwarded to the target
bodystring|objectnoRequest body for methods such as POST. When the directory row has body_hint, copy that shape and substitute your own values.
idempotency_keystringnoSafe retries; auto-generated when omitted
vw_keystringnoOverrides the session wallet key

Usage notes

  • Save attempt_id, rail, receipt_id (open-rail alias of the upstream payment-receipt / tx_hash), and the unlocked body. body_truncated is true when the body was cut at 8KB.
  • If suggest_payment_ready_list is true, call rill_discover and retry with a verified gate.
  • Allowance or max-transaction errors mean create a wallet with a higher budget or wait for period reset.
  • Secondary path for in-Rill resources or handle transfers: rill_pay.
  • Same flow over HTTP: POST /spend/pay-url.