Introduction

WelcomeServices map

Guides

AcceptSpend

Legal

SecurityPrivacyTerms
PreviousOverviewNextWallets
BlogPrivacyTerms

Pay

Primary Spend is POST /spend/pay-url against any payable HTTPS URL. Secondary is POST /pay for Rill resources and handle transfers. Both require a wallet key.

Same flow in MCP: rill_pay

Auth

Send a wallet key on every call. Prefer Authorization: Bearer rill_vw_*. The x-rill-vw-key header is also accepted. Send Idempotency-Key on mutating pays so retries are safe.

Authorization: Bearer rill_vw_*

Featured endpoints

Pay any MPP or x402 URL

POST /spend/pay-url

This is the primary Spend path. Rill probes the URL, completes the open-rail 402 challenge under the VW policy, and debits prepaid balance. The paid platform does not need to know about Rill. Prefer this for external APIs and hosted /r/{id} gates that speak MPP or x402.

ParameterTypeRequiredDescription
urlstringyesHTTPS URL of the paid resource or gate
methodstringnoHTTP method forwarded to the target. Defaults to GET. POST endpoints (for example a JSON x402 route) must pass method POST plus body.
directory_idstringnoDirectory profile id. Resolves pay_url and catalog probe_method when url is omitted.
prefer_railauto|mpp|x402noWhen the gate offers both rails: auto (default) uses Base/x402 first; mpp forces Tempo; x402 forces Base only
max_amountnumbernoUSD ceiling for this pay (decimal dollars)
max_amount_centsnumbernoInteger cents ceiling; overrides max_amount when set
headersobjectnoExtra request headers forwarded to the target
bodystring|objectnoRequest body for methods such as POST or PUT

Request body

body
{
  "url": "https://signals.example.com/api/paid",
  "method": "POST",
  "body": { "company": "acme" },
  "prefer_rail": "x402",
  "max_amount_cents": 50
}

What to save

Open-rail (mpp/x402): save attempt_id, rail, receipt_id (alias of the upstream payment-receipt), tx_hash, and the unlocked body/headers. Ledger Accept gates also return a Rill receipt_id for POST /access/verify. body_truncated is true when the unlock body was cut at 8KB. Errors include request_id. Allowance or max-transaction failures mean mint a higher budget or wait for period reset.

  • Send Idempotency-Key on the request headers for safe retries. A replay returns the stored unlock body when we saved it.
  • Default method is GET. A POST-only 402 needs method POST and a JSON body. When the directory row has body_hint, copy that shape and substitute your own values.
  • List prior open-rail spends with GET /spend/attempts.

Background ledger pay or transfer

POST /pay

Background Network rail for in-Rill resource pays and FQDN transfers. Resource pays credit seller ledger balance and return a receipt. Transfers settle on the Rill ledger. For any external HTTPS MPP/x402 endpoint, use pay-url instead.

ParameterTypeRequiredDescription
resource_idstringnoPriced resource id or short id (omit amount for resource pays)
tostringnoDestination handle or agent FQDN for a transfer
destinationstringnoAlias of to
amountnumbernoUSD amount; required for transfers, omit for resource pays
metadataobjectnoOpaque metadata stored with the pay

Transfer body

body
{
  "to": "research.acme.userill.com",
  "amount": 1.5
}

What to save

Save receipt_id. Unlock gates with X-Rill-Receipt, Payment-Receipt, or PAYMENT-RESPONSE, or call POST /access/verify. Resolve destinations with GET /handles/resolve/:destination before ledger transfers.

  • Seed unlock: ledger-pay resource_id SEED23, then GET /demo/echo with X-Rill-Receipt.
  • Send Idempotency-Key on every pay.

All endpoints

  • POST/spend/pay-urlOpen-rail pay any MPP/x402 URL (Idempotency-Key recommended)
  • GET/spend/attemptsList open-rail spends (VW key)
  • POST/payBackground ledger: resource pay or P2P transfer (Idempotency-Key)

Usage notes

  • Prefer POST /spend/pay-url (or MCP rill_pay_url) for third-party 402s and hosted Accept gates.
  • Every response includes request_id in the body and X-Request-Id.
  • MCP twins: rill_pay_url and rill_pay.