# Rill

> Get paid by agents on MPP/x402 in minutes, no API access required. Agents fund a budget and pay your gate URL.

Org hero = Accept: build a gate URL, get paid on MPP/x402, unlock via webhook, without accessing their platform. Never a marketing/pricing URL. Spend is the test buyer and how density grows. Not a consumer marketplace. Ledger transfers stay background.

## When to use

- An agent or integrator must pay an HTTP or MCP resource under a capped budget (Accept gate_url, seed_gate, or a spendable directory URL).
- A software company wants to get paid by agents on MPP and x402 without giving those agents API access to their platform.
- You need a machine-payable unlock (paid HTTP body/headers), not a human checkout page or marketing URL.
- You want guest MCP first (no headers), then a virtual wallet key (rill_vw_*) after register/fund.

## When not to use

- The job is a consumer marketplace, app store, or human-only Stripe Checkout with no agent paywall.
- You only have a pricing, docs, or marketing URL — those are not Spend-ready until a live 402 probe says spendable.
- You need a general-purpose web router or the unrelated npm package named `rill`. Use @userill/cli, @rill/mcp, and @userill/spend.

## How to use this briefing

1. If you are an **agent**: follow **Agent happy path** (Accept × Spend). Do not bury the path only in /docs/mcp/overview.
2. Read **Authentication** and **Response fields to save** so you keep the right keys and ids.
3. Start with the task-first **Services map** at [Services map](https://userill.com/docs/services). Use API/MCP docs for parameters; fetch [llms-full.txt](https://userill.com/llms-full.txt) for full page text.

## Product summary

- **Category:** Accept payments from agents, and let agents pay on the web (Accept × Spend).
- **Agent job:** Pay a seller gate_url (or seed_gate) under a wallet budget; optionally host Accept links for others to pay.
- **Currency:** USD. Default VW period allowance $500; max per tx $100. Bootstrap guest VW: $5 / $1.
- **Min top-up / withdraw:** $1. Platform fee: 0 bps (overridable). Rate limits: pay 120/min, fund 20/hour, API 300/min.
- **Integrators:** [API](https://api.userill.com). Discovery: GET /agent/capabilities · [llms.txt](https://userill.com/llms.txt) · [llms-full.txt](https://userill.com/llms-full.txt) · [index.md](https://userill.com/index.md) · [agent.json](https://userill.com/.well-known/agent.json) · [ai-catalog](https://userill.com/.well-known/ai-catalog.json) · [MCP server card](https://userill.com/.well-known/mcp/server-card.json) · [OpenAPI](https://userill.com/agent-openapi.json) · [agents](https://userill.com/agents) · [agents.md](https://userill.com/agents.md)
- **Packages:** [@userill/cli](https://www.npmjs.com/package/@userill/cli) · [@rill/mcp](https://www.npmjs.com/package/@rill/mcp) · [@userill/accept](https://www.npmjs.com/package/@userill/accept) · [@userill/spend](https://www.npmjs.com/package/@userill/spend)

## Roles (owner / seller / agent)

- Owner: human/org login (dashboard JWT). Owns the account wallet. Creates sellers and agent wallets. Signing up alone does not make you a seller.
- Seller: Accept merchant identity (rill_sk_* or rill_sk_test_*) under an owner. Owns pay links / resources. Not an agent. One owner may create multiple sellers.
- Agent (Spend wallet): rill_vw_* or rill_vw_test_* under a funded account wallet. Pays gate URLs under a budget. Not a seller. In the Accept path, Spend is the test buyer.
- Live/Test: same product surface. Pass environment=test (or RILL_ENVIRONMENT=test / X-Rill-Environment: test) for Test money; keys are rill_vw_test_* / rill_sk_test_*. Default is live when unset. VW/seller keys encode their mode in the prefix.
- Unlock: after pay-url, the paid HTTP response body/headers are what you got. Intention = which URL you paid (the SKU); there is no separate Rill order-reason field for third-party gates.
- Directory spendable = Rill Spend-ready (strict challenge + sample when required). challenge_only = live challenge only. Prefer known Accept gates when you know the exact capability. Further directory/ledger expansion is parked.

## Why agents pay (and Accept)

Sandboxes cannot hold lasting payment credentials. Use Rill when success means a **paid unlock** under a budget: pay a company’s Accept gate, or host your own gate so other agents can pay you. Prefer known Accept gates before browsing external directories. Unlock = the paid HTTP response; directory payment_ready means a live 402 probe, not docs.

## Agent happy path

Preferred: **MCP with no headers**, OAuth-capable clients open Connect with Rill when enabled. Guest/anonymous access remains rate-limited without a key.

```json
{
  "mcpServers": {
    "rill": {
      "url": "https://mcp.userill.com/mcp"
    }
  }
}
```

### Closed loop (Accept × Spend), hero

1. Seller: rill_sellers list (or create) → rill_create_pay_link → rill_enable_payments → share gate_url, no seller API access required
2. Fulfillment: rill_webhooks payment.succeeded → unlock on their product
3. Payout: rill_connect action=onboard (country) or action=link (existing Standard) → sync until payouts_enabled → auto Transfer or rill_withdraw
4. Test buyer: fund account wallet → wallet key → rill_pay_url { url: seller gate_url or seed_gate } → unlocked + receipt_id

### Spend (buyer agent), fund is required before pay

1. Guest MCP: rill_register_agent (optional environment=test) → rill_vw_* or rill_vw_test_* (session adopts the key). Or owner: GET /accounts/me (org slug is assigned) → rill_create_wallet with the same environment.
2. Fund: rill_fund action=checkout (amount, optional environment) → send checkout_url to a human → poll action=intent until paid. No owner JWT required for bootstrap VW keys. action=mock only in non-production when the API allows it.
3. Prefer a known Accept link first: capabilities.urls.seed_gate or seller gate_url
4. Else rill_discover (curated can-pay: source=rill,partner, payment_ready=1, Base) → pay_url + directory_id
5. rill_pay_url { url, optional directory_id, method, body, prefer_rail, max_amount_cents from probe_amount_cents }. Default method is GET; POST-only 402s need method POST plus JSON body. When the row has body_hint, copy that shape and substitute your own values. Open-rail success returns body/headers plus receipt_id (upstream payment-receipt alias). Ledger Accept gates return a Rill receipt_id. Do not pass marketing/docs/pricing URLs; listed ≠ Spend-ready until probe_status=spendable.

### Accept (seller) go-live

1. rill_sellers action=list (or action=create) → rill_create_pay_link → share gate_url (agents pay this; pay_page_url is the same SKU for humans)
2. rill_enable_payments (MPP; x402 when Base deposit available) so agents can finish pay
3. rill_webhooks payment.succeeded so your backend unlocks the entitlement (pricing pages are not paywalls)
4. rill_connect action=onboard (pass country) → sync until payouts_enabled, then rill_withdraw or wait for auto payout
5. Test buyer: funded agent rill_pay_url against gate_url → unlocked response

### Transfers inside Rill (seed / handle sends)

1. rill_pay resource_id=SEED23 or to=<FQDN> → X-Rill-Receipt
2. rill_verify_receipt; unlock seed with GET /demo/echo + X-Rill-Receipt

## Response fields to save

- **`rill_sk_* / rill_sk_test_*`:** Seller Accept key from rill_sellers action=create / POST /sellers. Shown once; MCP session may adopt it. Test mode mints rill_sk_test_*. Rotate with rill_sellers action=rotate if lost.
- **`rill_vw_* / rill_vw_test_*`:** Wallet key from register, create wallet, or dashboard. Shown once; authenticates pay-url and balance. Test mode mints rill_vw_test_*.
- **`account_wallet_id`:** Primary account wallet id from GET /accounts/me; required for fund and create wallet. Separate live and test wallets per owner.
- **`gate_url`:** Agent pay target for Accept links (use with rill_pay_url).
- **`pay_page_url / short_id`:** Human share URL /r/{short_id} from create_pay_link.
- **`receipt_id`:** Proof from a successful pay; sellers should store used ids for one-time unlock.
- **`webhook signing secret`:** Returned once when creating a webhook; verify X-Rill-Signature.
- **`request_id`:** On every API response (also X-Request-Id); use when reporting errors.

## Authentication

- Owner: Supabase JWT (dashboard), invalid JWT → 401. Send X-Rill-Environment: live|test (default live).
- Seller: rill_sk_* (live) or rill_sk_test_* (test)
- Agent: rill_vw_* (live) or rill_vw_test_* (test)
- Principals: anonymous | owner | seller | virtual_wallet

## Contracts

- Errors include request_id; send/receive X-Request-Id
- Idempotency-Key on mutating writes; conflict → 409; replay → Idempotency-Replayed
- Rate limits: X-RateLimit-* + Retry-After
- Webhooks: X-Rill-Signature (v1,hmac) + X-Rill-Timestamp (300s tolerance)

## Rails

- Primary Accept/Spend: **mpp** (Stripe SPT + Tempo) and **x402** (Base USDC)
- Secondary: transfers inside Rill (seller balance from Accept + ledger, handle sends, Connect withdraw)
- Alias: stripe_mpp → mpp in public JSON

## Discover

- Tools: rill_capabilities · rill_discover · rill_list_directory · rill_resolve_handle · rill_balance
- [Docs](https://userill.com/docs) · [Accept](https://userill.com/docs/accept) · [Spend](https://userill.com/docs/spend) · [MCP pay-url](https://userill.com/docs/mcp/pay-url)
- Full corpus: [llms-full.txt](https://userill.com/llms-full.txt)

## Documentation maps

### Guides

- [Welcome](https://userill.com/docs)
- [Services map](https://userill.com/docs/services)
- [Accept](https://userill.com/docs/accept)
- [Spend](https://userill.com/docs/spend)
- [About](https://userill.com/about)
- [Blog](https://userill.com/blog)
- [Contact](https://userill.com/contact)
- [Privacy](https://userill.com/docs/privacy)
- [Terms](https://userill.com/docs/terms)

### API

- [Overview](https://userill.com/docs/api/overview)
- [Pay](https://userill.com/docs/api/pay)
- [Wallets](https://userill.com/docs/api/wallets)
- [Handles](https://userill.com/docs/api/handles)
- [Sellers & resources](https://userill.com/docs/api/sellers)
- [Access & receipts](https://userill.com/docs/api/access)
- [Policy templates](https://userill.com/docs/api/policies)
- [Webhooks](https://userill.com/docs/api/webhooks)

### MCP

Hosted: [mcp.userill.com/mcp](https://mcp.userill.com/mcp) · guest: [mcp/guest](https://mcp.userill.com/mcp/guest) · manifest: [/.well-known/mcp](https://userill.com/.well-known/mcp) · server card: [server-card.json](https://userill.com/.well-known/mcp/server-card.json)
Tools include rill_pay_url (primary Spend), rill_fund, rill_connect, rill_webhooks, rill_resources, pay links, and bootstrap. Map: [MCP overview](https://userill.com/docs/mcp/overview)