# Rill, full docs corpus --- Site: https://userill.com --- API: https://api.userill.com --- Briefing: https://userill.com/llms.txt --- Agent OpenAPI: https://userill.com/agent-openapi.json --- Agents corpus: https://userill.com/agents --- # Rill docs Source: https://userill.com/docs Companies get paid by agents. People fund a wallet. Agents pay a link and get the result back. If you sell: host a pay link, get paid in Stripe, unlock in your own product. If you buy: fund a wallet and let an agent pay those links under a budget. What is Rill? Rill is the payment rail between a company and an agent. You price your own product. Agents pay a link under a budget. It is not a marketplace. Do you need access to our API? No. Create a pay link, turn payments on, and share that link. Add a webhook when you want your product to unlock by itself. How do agents start? They read /llms.txt, connect MCP, wait for a person to fund, then pay a known link. People on this site should use Accept and Spend, not the agent files. What is a seller? The merchant under your login. It owns pay links and receives the money. Your login is the owner. An agent is a separate wallet that spends. What are Accept and Spend? Accept is how you get paid. Spend is how an agent pays you (or how you test your own link). Sending money to another Rill handle is optional and secondary. If I pay a directory URL, what do I get? Whatever that URL returns after a valid payment. You are buying that link, not “the company.” Only rows that can pay are safe. How does money move? A person funds a wallet with a card. An agent pay credits the seller. Connect Stripe to receive a payout, or move earnings back into your Rill wallet. Are pay pages indexed? No. Pay links stay out of search. The site, docs, and agent discovery files are what get indexed. Before I take live money? Use Test until money should be real. Open-rail agent pays are typically irreversible. Signing in, using the API, or connecting MCP means you agree to the Terms of use. How we handle account and payment data is in the Privacy policy. --- # Services map Source: https://userill.com/docs/services Website for people. API for integrators. MCP for agents. Same money underneath. Pick the surface for the job. The CLI covers a subset for local scripts. See what you can do: website=llms.txt; api=GET /agent/capabilities; mcp=rill_capabilities Fund a wallet: website=Home; api=POST …/fund-checkout; mcp=rill_fund Create an agent key: website=Home; api=POST /wallets; mcp=rill_create_wallet Pay a link: website=Spend; api=POST /spend/pay-url; mcp=rill_pay_url Create a pay link: website=Accept; api=POST /resources; mcp=rill_create_pay_link Get paid out: website=Accept; api=Connect + withdraw; mcp=rill_connect --- # Get paid by agents Source: https://userill.com/docs/accept Put a price on something your product already does. Agents pay a link. You get paid in Stripe. You keep the data. How your product unlocks Share the gate, not the pricing page: Create a pay link and copy the gate URL. That is what agents pay. A pricing page is not a paywall. A webhook tells your backend to fulfill: When a pay succeeds, Rill calls you with which product was bought and a receipt. You grant access in your own system, the same way you would after any other payment notification. Prove it with a test pay: Fund a wallet on Home, pay your own gate, and confirm the webhook fired. That is the rehearsal. It is not the product you sell. When you need more than a hosted link Hosted gate is enough for most teams: Share the link, listen for the webhook, fulfill on your side. No SDK. Protect a route in your own app only if you need to: The accept-echo example shows a webhook unlock you can copy. Use the Accept kit later if a route in your app must stay locked until a receipt is shown. Go live Copy your seller key: Open Accept. We create the seller for you. Save the key if we show it; it appears once. Create the pay link: Give it a name, a path your team recognizes, and a price. Copy the gate URL and keep it for agents and for your own test. Turn payments on: Turn on agent payments for that seller. Until this is on, agents cannot finish a pay. Add a webhook: Subscribe to successful pays so your backend can unlock. Skip this only if you will fulfill by hand. Pay it once yourself: Add funds on Home and pay the gate. You should see unlocked proof and, if you added a webhook, your own unlock. Connect Stripe to receive the money: New to Connect: create an Express account and pick your country (Cyprus is allowed if Stripe accepts it). Already on Stripe: link that existing account. Money from agent pays lands on Rill first, then Transfers to you. Test payouts run on their own. Live payouts start when your seller is enabled for them. Good to know You set the price. There is no platform fee today. A later fee would be a small withhold on payout, not a cut of your product. Payouts start after Stripe says you can receive them and the seller balance is at least $1. Test mode remits automatically. Live remits when we enable your seller. Agent pays use stablecoins. There is no card chargeback on that rail. If you need to refund, do it with the buyer out of band. Card disputes only apply to someone topping up a Rill wallet. Webhook and payout field names live on the API pages when you are ready to wire them. You set the price and you fulfill unlocks. Open-rail agent pays are typically irreversible. Card chargebacks apply to wallet top-ups, not to settled agent pays. See the --- # Pay as an agent Source: https://userill.com/docs/spend A person funds a wallet once. An agent spends from that budget and gets the paid result back in the same call. How agents call this MCP or the HTTP API is enough: Most agents use rill_pay_url or POST /spend/pay-url. You do not need an SDK. Optional typed client: Install @userill/spend if you want a small client around the same pay call. Field names and examples live on the Pay API page. Good to know A person funds. An agent spends. That split is the product. If a URL only accepts POST, send the method and body. A GET will fail. Retry with the same idempotency key; you get the stored result, not a second charge. Pays on the open web also need Rill’s Spend till funded. That is our side, not something you configure in the dashboard. A person who funds the wallet is responsible for agent spends, including an empty allowlist. Open-rail pays are typically irreversible. Directory listings are not a guarantee. See the --- # Security Source: https://userill.com/docs/security How Rill protects agent payments, wallets, and API access, and how to report issues. Rill lets you accept payments from agents and lets your agents pay on the web. This page summarizes access controls, money safeguards, and how to report vulnerabilities. The website, API, and MCP server are separate services. Accept and Spend settle through Stripe when connected. Transfers inside Rill support handle sends and Connect withdraw. Browser calls to /api/* are rewritten to the API (the API itself has no /api prefix). Pays on the web settle in Stripe. Transfers inside Rill settle on the Rill ledger. Receipts are re-verifiable; sellers should store used receipt_id values for one-time unlock. Pay pages under /r/ are not indexed. How we handle account and payment data, and the contract for using Rill, live on Email security@userill.com with a clear description, impact, and steps to reproduce. Give us reasonable time to investigate before public disclosure. Use security@ only for vulnerabilities. Privacy requests go to privacy@userill.com. Terms and contract questions go to legal@userill.com. Abuse reports go to abuse@userill.com. - Owner dashboard sessions use a signed owner token (invalid token → 401). - Seller Accept keys use rill_sk_* prefixes. - Agent wallets use rill_vw_* with period allowances and optional allowlists. - Mutating writes expect Idempotency-Key; responses include request_id / X-Request-Id. - Webhooks are signed with X-Rill-Signature and X-Rill-Timestamp. --- # REST API Source: https://userill.com/docs/api/overview Bare paths on the API host. Browser apps proxy /api/* to the same Nest routes. Production: https://api.userill.com, local: http://localhost:3001 GET /agent/capabilities returns auth modes, pay shapes, MCP URLs, trust ladder, and seed IDs. Also: /llms.txt, /llms-full.txt, /.well-known/agent.json, /agent-openapi.json. Every response includes request_id (body) and X-Request-Id. Errors: { ok:false, error:{code,message,details?}, request_id }. Send Idempotency-Key on mutating writes. Rate limits expose X-RateLimit-* + Retry-After. GET /health (liveness) · GET /ready (Supabase dependency probe, 503 when not ready). --- # Pay Source: https://userill.com/docs/api/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. 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. Featured: ## 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. 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. 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-url, Open-rail pay any MPP/x402 URL (Idempotency-Key recommended) GET /spend/attempts, List open-rail spends (VW key) POST /pay, Background ledger: resource pay or P2P transfer (Idempotency-Key) 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. --- # Account & wallets Source: https://userill.com/docs/api/wallets Fund company wallets with Stripe Checkout, create wallets with a budget (rill_vw_*), manage fleet policy, and open the billing portal. Owner JWT for account wallets and create; wallet key for allowance status. Auth: Create wallet, list accounts, revoke, rotate, and billing portal need an owner Supabase JWT. Send X-Rill-Environment: live|test (default live) on owner JWT calls — Test mode uses a separate wallet balance and mints rill_vw_test_* / rill_sk_test_* keys. Fund-checkout accepts an owner JWT or a rill_vw_* key (VW may only fund its own account wallet; agents prefer POST /agent/fund-checkout). Wallet status uses Authorization: Bearer rill_vw_*. Send Idempotency-Key on fund-checkout, mock fund, and other mutating writes. Featured: ## Fund with Stripe Checkout POST /accounts/:id/fund-checkout Create a top-up PaymentIntent for the dashboard Payment Element (default), or pass hosted=true for a Stripe Checkout URL. Response includes amount (wallet credit), processing_fee, total_charged, and either client_secret (+ publishable_key) or checkout_url. Wallet credits face amount; human pays total. Poll GET /funding/:id until paid, then create wallets. Save funding_intent_id. Dashboard uses client_secret in-modal; agents that need a link should pass hosted=true and send checkout_url. Poll the funding intent until paid before expecting Spend to succeed. - Agents: POST /agent/fund-checkout with a rill_vw_* key (always hosted Checkout URL). - Local or non-production may allow POST /accounts/:id/fund (mock) when Stripe is unset, mock credits face amount with no card fee. - MCP twin: rill_fund with action=checkout, then action=intent. ## Create a wallet POST /wallets Create a wallet with a budget from a funded account wallet. Set period allowance and max per transaction in USD. Optional allowlist and policy_template_id apply fleet defaults for many agents sharing one template. Save the rill_vw_* key immediately, it is shown once. Use it for POST /spend/pay-url and POST /pay. Store the wallet id for revoke/rotate. - Fund the account wallet before creating a wallet or pays fail with insufficient balance. - MCP twin: rill_create_wallet. ## Read wallet allowance GET /wallets/me/status Return remaining period allowance and per-tx caps for the calling wallet. Call after pays to stay inside budget. Seller balance is a different route (GET /sellers/me/balance). Use remaining allowance and max_transaction from the response to decide whether to pay, wait for period reset, or create a wallet with a higher budget. - Auth with the wallet key (Bearer rill_vw_*). - MCP twin: rill_balance with vw_key. All endpoints: GET /accounts, List owner wallets GET /accounts/me, Primary wallet GET /accounts/:id, Wallet by id POST /accounts, Create wallet POST /accounts/:id/fund-checkout, Stripe top-up (Idempotency-Key) POST /accounts/:id/fund, Mock fund when allowed GET /accounts/:id/spend-attempts, Open-rail MPP/x402 spend history (owner) POST /accounts/me/billing-portal, Stripe Customer Portal GET /funding/:id, Poll Checkout status GET /wallets, List VW keys POST /wallets, Mint VW (optional policy_template_id) GET /wallets/:id, VW by id GET /wallets/me/status, Allowance remaining (VW key) GET /wallets/:id/status, Status by id POST /wallets/:id/revoke, Revoke VW POST /wallets/:id/rotate, Rotate VW secret GET /ledger, Ledger lines GET /receipts, Receipts Notes: - Revoke or rotate a wallet with POST /wallets/:id/revoke|rotate when a key leaks. - Fleet defaults: create a policy template, then pass policy_template_id when creating a wallet. - Spend happy path: claim → fund-checkout → create wallet → pay Accept link (seed_gate) or payment_ready URL via POST /spend/pay-url. --- # Handles Source: https://userill.com/docs/api/handles Your org slug is the pay address for background ledger transfers. Signing in creates one. You can rename it. Auth: POST /handles/claim and PATCH /handles require an owner Supabase JWT. Resolve and bare-handle lookup are public reads, no key required. Featured: ## Set or change the org slug POST /handles/claim Creates the account wallet if needed and assigns a generated org slug. Pass handle to set or rename it. The slug is the prefix for agent FQDNs such as research.acme.userill.com. Save account_wallet_id for fund-checkout and mint. The org slug is your pay address and FQDN prefix. - MCP twin: rill_claim_handle. PATCH /handles also renames. ## Resolve a destination GET /handles/resolve/:destination Confirm a destination exists before a background ledger transfer with POST /pay to=…. Accepts @handle, handle FQDN, or agent FQDN. Open-world Spend with pay-url usually targets an HTTPS gate URL instead, so resolve is optional on that path. Use the resolved handle / agent identity when composing POST /pay transfers. - MCP twin: rill_resolve_handle. All endpoints: POST /handles/claim, Create wallet + set or keep org slug PATCH /handles, Rename the current org slug GET /handles/resolve/:destination, @handle, handle FQDN, or agent FQDN GET /handles/:handle, Bare handle lookup GET /directory, List pay URLs (rail, payment_ready, max_probe_age_hours, probe_method) POST /directory/sync, Owner: refresh catalogs + probe all pay URLs Notes: - Agent discovery also exposes GET /agent/capabilities. - Resolve before background ledger POST /pay transfers; skip resolve for open-world POST /spend/pay-url against HTTPS gates. --- # Sellers & resources Source: https://userill.com/docs/api/sellers Accept-side APIs for sellers, priced resources, hosted gates, Stripe Profile (MPP/x402), Express or Standard Connect, withdraw, and recycle. Open-rail Accept credits seller balance; Connect withdraw Transfers that balance to the connected account. Auth: Create seller, list sellers, recycle, and owner dashboard routes under /sellers/:id/* (Connect, payments, withdraw, resources) use an owner Supabase JWT. Agent/MCP seller-scoped routes under /sellers/me/* and /resources need Authorization: Bearer rill_sk_*. Send Idempotency-Key on withdraw, recycle, and resource PATCH. Featured: ## Create a seller POST /sellers Create an Accept seller and receive a rill_sk_* key. Call this before pay links, Stripe Profile, or Connect. Save the key immediately, it is shown once. Save the rill_sk_* seller key and seller id. Use the key for resources, payments, Connect, and withdraw. - MCP twin: rill_sellers action=create. ## Create a priced resource POST /resources Create a priced HTTP or MCP SKU. Response includes gate_url (agents pay this) and pay_url (human pay page, same as MCP pay_page_url). Prefer MCP/CLI create-pay-link for the composed Accept response. Agents pay gate_url with pay-url once payments are enabled. Save gate_url for agents (the SKU). pay_url is the human pay page for the same resource (MCP/CLI call it pay_page_url). Also save resource id and short_id. - List with GET /resources. Update with PATCH /resources/:id (idempotent). - MCP/CLI twins: rill_create_pay_link / create-pay-link, rill_resources action=create|update|deactivate. ## Enable MPP / x402 on gates PATCH /sellers/me/payments Enable MPP/x402 on seller gate URLs so agents can finish pay. Optional stripe_profile_id when attaching a Stripe Profile. Open-rail settlement lands in Stripe and credits seller balance for Connect payout. Confirm mpp_enabled / x402_enabled on the seller. Agents can then pay gate_url with open rails. - Open-rail pays credit seller balance for Connect payout. - MCP/CLI twins: rill_enable_payments / enable-payments. ## Withdraw seller balance POST /sellers/me/withdraw Transfer seller balance (open-rail Accept credits and ledger) to Stripe Express after Connect KYC. Complete Connect onboard with your country → sync until payouts_enabled first. Auto payout also runs when Connect is ready and balance meets the minimum. Save the withdrawal id / status from the response. Check GET /sellers/me/balance for Connect readiness flags before retrying. - Owner recycle into the account wallet: POST /sellers/:id/recycle. - Connect steps: GET/POST /sellers/me/connect* or MCP rill_connect. - MCP twins: rill_withdraw, rill_recycle. All endpoints: POST /sellers, Create seller + rill_sk_* GET /sellers, List sellers GET /sellers/me, Seller profile GET /sellers/me/balance, Balance + Connect flags PATCH /sellers/me/payments, Link profile_… / enable MPP POST /resources, Create priced resource GET /resources, List resources GET /resources/:id, Resource by id PATCH /resources/:id, Update (idempotent) DELETE /resources/:id, Delete POST /resources/:id/terms, 402 terms payload GET /r/:resourceId, Hosted gate (402 + optional MPP) GET /sellers/me/connect, Enriched Connect status POST /sellers/me/connect/onboard, Express Account Link URL POST /sellers/me/connect/link, Standard Connect OAuth URL POST /sellers/me/connect/oauth, Complete Standard OAuth with code POST /sellers/me/connect/sync, Sync from Stripe POST /sellers/me/connect/login-link, Express login for KYC POST /sellers/me/withdraw, Transfer payout POST /sellers/:id/connect/onboard, Owner JWT Express Account Link POST /sellers/:id/connect/sync, Owner JWT sync Connect POST /sellers/:id/connect/login-link, Owner JWT Express login PATCH /sellers/:id/payments, Owner JWT enable MPP/x402 POST /sellers/:id/withdraw, Owner JWT ledger withdraw GET /sellers/:id/resources, Owner JWT list resources POST /sellers/:id/resources, Owner JWT create resource PATCH /sellers/me, Seller key: website_url, description POST /sellers/:id/rotate-key, Owner JWT rotate rill_sk_* (shown once) POST /sellers/:id/recycle, Seller → account wallet Notes: - Accept go-live: create seller → gate URL → enable payments → webhook (payment.succeeded) → test with wallet pay-url. - API pay_url = MCP/CLI pay_page_url (human page). Agents always pay gate_url. - Dashboard owners can use /sellers/:id/* with JWT; agents keep /me + rill_sk_*. - Send Connect onboard_url or login_url to a human, never complete KYC inside an agent. - MCP/CLI twins: rill_sellers / create-seller / sellers list, create-pay-link, enable-payments, webhooks, rill_connect, rill_withdraw. --- # Access & receipts Source: https://userill.com/docs/api/access Re-verify receipts and unlock paid resources. Sellers should store used receipt_ids for one-time unlock even when protocols also return Payment-Receipt headers. Auth: POST /access/verify is public (pass the receipt). Listing receipts follows owner/VW auth on GET /receipts. Seed unlock uses X-Rill-Receipt on GET /demo/echo after a ledger pay. Featured: ## Verify a receipt POST /access/verify Re-check a receipt after pay. Optional resource_id scopes the verify call. Open-world Accept gates may also accept Payment-Receipt / PAYMENT-RESPONSE headers from MPP/x402 clients, still store used receipt_ids server-side for one-time unlock. Treat a successful verify as unlock proof for that receipt. Persist used receipt_ids so the same receipt cannot unlock twice. - Seed unlock over HTTP: GET /demo/echo with X-Rill-Receipt after paying SEED23 on the ledger. - MCP twin: rill_verify_receipt. All endpoints: POST /access/verify, Re-verify receipt (optional resource_id) GET /receipts, List receipts GET /demo/echo, Seed unlock with X-Rill-Receipt GET /r/:resourceId, Hosted gate 402 → pay → unlock Notes: - Verification is re-checkable; sellers enforce one-time unlock by storing used receipt_ids. - Hosted pay page (web): /r/:resourceId · balise script: /rill-balise.js. --- # Policy templates Source: https://userill.com/docs/api/policies Fleet spend templates applied when creating wallets, period allowance, max transaction, and optional allowlist, so many agents share one policy. Auth: Owner Supabase JWT required on every route. Send Idempotency-Key on create. Pass policy_template_id on POST /wallets to apply the template when creating a wallet. Featured: ## Create a policy template POST /policies Define fleet defaults once, then create many wallets with the same allowance and allowlist. Canonical product defaults live in @rill/shared PRODUCT_POLICY when you omit a template. Save template id and pass it as policy_template_id on POST /wallets (or MCP rill_create_wallet). - List with GET /policies; delete with DELETE /policies/:id. All endpoints: POST /policies, Create template (Idempotency-Key) GET /policies, List owner templates GET /policies/:id, Template by id DELETE /policies/:id, Delete template Notes: - When policy_template_id is set on mint, template allowance fields override the body values. - MCP twin path: create here, then rill_create_wallet with policy_template_id. --- # Webhooks Source: https://userill.com/docs/api/webhooks Register HTTPS callbacks for payment and funding events. Delivery is signed, SSRF-safe, retried via an outbox, and verifiable with the secret returned on create. Auth: Owner Supabase JWT required. Send Idempotency-Key on create. Save the signing secret from the create response, it is required to verify X-Rill-Signature on every delivery. Featured: ## Register a webhook POST /webhooks Register a callback URL for events such as payment.succeeded and funding.paid. Localhost callbacks are allowed outside production. List registered endpoints with GET /webhooks. Save the webhook id and signing secret. Verify X-Rill-Signature (v1,), X-Rill-Timestamp (300s tolerance), and X-Rill-Webhook-Id on every delivery. - Catalog events with GET /webhooks/events. - Test with POST /webhooks/:id/test; retry with …/deliveries/:deliveryId/retry. - MCP twin: rill_webhooks action=create|list|test|delete. All endpoints: POST /webhooks, Register URL (Idempotency-Key) GET /webhooks, List endpoints GET /webhooks/events, Event catalog DELETE /webhooks/:id, Delete endpoint GET /webhooks/:id/deliveries, Delivery log POST /webhooks/:id/test, Send test event POST /webhooks/:id/deliveries/:deliveryId/retry, Retry delivery Notes: - Headers: X-Rill-Signature (v1,), X-Rill-Timestamp (300s tolerance), X-Rill-Webhook-Id. Verify with the secret returned on create. - Events include payment.succeeded, payment.failed, transfer.received, funding.paid, withdrawal.paid, withdrawal.failed, vw.revoked, allowance.reset, seller.withdrawn, resource.updated. --- # Rill MCP Source: https://userill.com/docs/mcp/overview Connect Cursor, Claude, Grok Bot, or your own agents to Rill: sellers host pay links; agents fund a wallet and pay those links (or any verified payment_ready URL). Hosted guest MCP at https://mcp.userill.com/mcp/guest needs no API key. It exposes discovery, register, fund, pay, balance, and verify, the full Spend cold-start. Call rill_fund with action=checkout and an amount (optional environment=test): the session auto-registers a bootstrap wallet key, returns a Stripe Checkout URL for a human, then you poll action=intent until paid and call rill_pay_url. Save the wallet key once, it is not shown again. Accept/seller tools stay on the full MCP endpoint. Using guest MCP, a wallet key, or the hosted endpoint is use of the Service under the On the full MCP endpoint, authenticate with an owner JWT for Accept and custom wallets. The org slug is assigned when the account wallet is created. Fund with rill_fund, then create a wallet via rill_create_wallet. Guest Spend does not need an owner JWT, bootstrap agents fund via hosted Checkout with their VW key. Prefer rill_pay_url against capabilities.urls.seed_gate or a seller gate_url; use rill_discover for the curated can-pay set (Accept gates and partners). The full bazaar is rill_list_directory. Org path: get paid on MPP/x402 without us accessing your API. rill_sellers list or create → save rill_sk_* → rill_create_pay_link → copy gate_url → rill_enable_payments → rill_webhooks payment.succeeded to unlock on your product. Share the gate URL with agents, not a pricing page. pay_page_url is the same SKU for humans. Test with a funded wallet via rill_pay_url (Spend is the test buyer). Connect Stripe (rill_connect, pass country) so Accept pays Transfer to your account. Open-rail Accept credits seller balance, then Transfers to the connected Stripe account (Express by default, or a linked Standard account) when payouts are enabled. Call rill_connect with action=onboard (pass country) for Express, or action=link for an existing Stripe account. Agent bootstrap keys cannot open Connect. Send the human to https://userill.com/accept?connect=start. Poll action=sync until payouts_enabled. Then withdraw with rill_withdraw, or wait for auto payout. Recycle moves seller balance into the owner wallet without Stripe. Point your MCP client at the hosted HTTP endpoint (or a local http transport). For guest bootstrap without keys, use https://mcp.userill.com/mcp/guest. The server also exposes markdown docs as MCP resources at rill://docs/authentication, rill://docs/money, rill://docs/idempotency, rill://docs/webhooks, rill://docs/errors, and rill://docs/recipes. Prefer rill_capabilities for live policy numbers instead of hardcoding limits. { "mcpServers": { "rill": { "url": "https://mcp.userill.com/mcp" } } } --- # Search MCP tools Source: https://userill.com/docs/mcp/search Find available Rill MCP tools by keyword and read the server happy-path instructions for the current mode. Tool: rill_search_tools Auth: No key required. Available on guest and full MCP sessions. Call this when you are exploring the surface or unsure which tool to use next. Optional query filters by tool name or short description. The response also includes the mode-specific server instructions (guest bootstrap versus full owner/seller flows). Parameters: - query (string, no): Optional keyword matched against tool names and summaries Notes: - Start here on a new guest session before paying. - Prefer rill_capabilities when you need live policy numbers, seed IDs, or MCP URLs. - Same discovery over HTTP is not required, this tool is MCP-local. --- # Read agent capabilities Source: https://userill.com/docs/mcp/capabilities Fetch live policy, trust ladder, seed resources, rails, and the canonical MCP tool list from the API. Tool: rill_capabilities Auth: No key required. Available on guest and full MCP sessions. Use this instead of hardcoding limits or seed IDs. The response mirrors GET /agent/capabilities and includes happy_paths for Spend, Accept, fund, and Connect. Re-read after product changes so agents pick up new rails or tool names. Notes: - Prefer this over baking PRODUCT_POLICY numbers into prompts. - Guest-safe; pair with rill_resolve_handle before ledger transfers to a handle. - Same flow over HTTP: GET /agent/capabilities. --- # Resolve a pay destination Source: https://userill.com/docs/mcp/resolve-handle Turn an @handle, handle FQDN, or agent FQDN into a pay address and agent list before you transfer. Tool: rill_resolve_handle Auth: No key required. Available on guest and full MCP sessions. Call this before a background ledger transfer with rill_pay to=… so you confirm the destination exists. Open-world Spend with rill_pay_url usually targets an HTTPS gate URL instead of a handle, so resolve is optional on that path. Parameters: - handle (string, yes): @handle, handle.userill.com, or agent.handle.userill.com Notes: - Leading @ is optional and stripped for you. - Use the resolved address with rill_pay for in-Rill A2A transfers. - Same flow over HTTP: GET /handles/resolve/:destination. --- # List payment directory endpoints Source: https://userill.com/docs/mcp/list-directory List cached MPP and x402 pay URLs with live probe classification. Defaults to payment_ready gates. Tool: rill_list_directory Auth: No key required. Available on guest and full MCP sessions. Each row includes pay_url, probe_status, probe_method, optional probe_amount_cents, probe_rails, optional probe_pay_to, and optional body_hint. MCP defaults to payment_ready=true and skips probes older than 7 days. Pass payment_ready=false for the full research catalog (docs/dead history). Prefer rill_discover for the curated can-pay set (Accept gates and partners). The bazaar catalog stays here. Parameters: - q (string, no): Optional search filter - rail (string, no): mpp | x402 | any (default any) - probe_status (string, no): Comma list: payment_ready, docs_only, dead, auth_wall, unreachable, error, unknown, unprobed - payment_ready (boolean, no): MCP default true. Set false for the full catalog (not for spend). - capability (string, no): Filter by category (ai, data, search, blockchain, finance, compute, storage, web, commerce, content, social, infrastructure, verification, media, developer, other) - max_probe_age_hours (number, no): When listing payment_ready, drop rows older than this many hours (MCP default 168) - limit (number, no): Page size (1–100, default 50) - cursor (string, no): Pagination cursor from a previous response Notes: - Guest-safe discovery; does not move money. - Only trust payment_ready rows newer than ~7 days for rill_pay_url. - Owners refresh + re-probe with rill_sync_directory. - Same flow over HTTP: GET /directory. --- # Discover can-pay gates Source: https://userill.com/docs/mcp/discover List curated spendable Accept and partner gates ranked for Spend. Tool: rill_discover Auth: No key required. Available on guest and full MCP sessions. Always filters to payment_ready, recent probes, Base (eip155:8453), and source=rill,partner (first-party Accept gates plus curated partners). Prefer a known Accept gate (capabilities.urls.seed_gate or seller gate_url) first. Each row includes pay_url, probe_method (GET/POST), optional probe_amount_cents, and optional body_hint. Take pay_url (and id as directory_id) → rill_pay_url; when probe_amount_cents is set, pass max_amount_cents at or above that value. When body_hint is set, send that JSON shape with your own values. Do not use company websites or docs links. Parameters: - q (string, no): Optional search filter - rail (string, no): mpp | x402 | any (default any) - network (string, no): Network filter (default base). Pass empty only when you intentionally want all chains. - max_probe_age_hours (number, no): Drop rows older than this many hours (default 168) - limit (number, no): Page size (1–100, default 50) - cursor (string, no): Pagination cursor from a previous response Notes: - Order: fund → pay seed_gate / Accept gate → then rill_discover can-pay set → pay_url. - Full research catalog (including bazaar): rill_list_directory with payment_ready=false. - Same HTTP filter: GET /directory?payment_ready=1&network=base&source=rill,partner&max_probe_age_hours=168. --- # Register a bootstrap agent Source: https://userill.com/docs/mcp/register-agent Self-register with a short proof-of-work challenge and get a starter wallet key for Spend. Tool: rill_register_agent Auth: No prior key. Guest-safe. The tool solves PoW against the API and returns a rill_vw_* or rill_vw_test_* key. Cold-start step one on /mcp/guest. After success, the session adopts the wallet key so fund and pay tools work without pasting credentials. Next: rill_fund action=checkout → send the Stripe URL to a human → poll action=intent → rill_pay_url. (rill_fund can also auto-register if you skip this tool.) Parameters: - label (string, no): Optional human label for the bootstrap agent - environment (live | test, no): Money mode (default live). test mints rill_vw_test_* into a Test wallet. Notes: - Save api_key immediately, it is shown once. - Bootstrap allowances are tighter than owner-created wallets; read rill_capabilities for current caps. - If pay fails with insufficient balance, call rill_fund action=checkout and have a human pay, then retry. - Same flow over HTTP: POST /agent/register/challenge then POST /agent/register with optional environment. --- # Set org slug Source: https://userill.com/docs/mcp/claim-handle Create the owner account wallet if needed, then set or change the org slug used as the pay address. Tool: rill_claim_handle Auth: Owner Supabase JWT required (session RILL_OWNER_JWT or owner_jwt argument). Invalid JWT returns 401. Signing in already assigns a generated org slug. Pass handle only when you want a specific slug. Save account_wallet_id for rill_fund and rill_create_wallet. Parameters: - handle (string, no): Optional org slug to set or rename. Omit to keep the generated slug. Leading @ is stripped. - owner_jwt (string, no): Overrides session / RILL_OWNER_JWT for this call Notes: - Save account_wallet_id for fund and create-wallet steps. - Slug conflicts return a clear error, pick another. - Same flow over HTTP: POST /handles/claim or PATCH /handles. --- # List account wallets Source: https://userill.com/docs/mcp/accounts List the owner’s account wallets, or fetch the primary wallet when you only need the funded balance target. Tool: rill_accounts Auth: Owner Supabase JWT required (session or owner_jwt). Call this after claim (or when resuming a session) to recover account_wallet_id before rill_fund or rill_create_wallet. Set me=true to hit the /me shortcut for the primary wallet instead of the full list. Parameters: - me (boolean, no): When true, returns the primary wallet via GET /accounts/me - owner_jwt (string, no): Overrides session JWT for this call Notes: - Use the wallet id as account_wallet_id on rill_fund and rill_create_wallet. - Empty list usually means the owner has not claimed a handle yet. - Same flow over HTTP: GET /accounts or /accounts/me. --- # Create a wallet Source: https://userill.com/docs/mcp/create-wallet Create a wallet with a budget (rill_vw_*), period allowance, per-pay max, and optional allowlist. Tool: rill_create_wallet Auth: Owner Supabase JWT required. The account wallet should already be funded or pays will fail with insufficient balance. Create a wallet after claim and fund on the owner path. The MCP session adopts the new key for later Spend tools. Set period_allowance and max_transaction in USD (decimal dollars). Optional allowlist and policy_template_id apply fleet defaults for many agents sharing one template. Parameters: - account_wallet_id (string, yes): Funded account wallet that backs this wallet - agent_slug (string, no): Slug for the agent FQDN; defaults to agent - period_allowance (number, no): USD budget for the policy period - max_transaction (number, no): USD cap for a single pay - allowlist (string[], no): Allowed resource or destination patterns - policy_template_id (string, no): Fleet template that supplies default caps - owner_jwt (string, no): Overrides session JWT for this call Notes: - Save rill_vw_* immediately, it is shown once on create. - Check remaining budget later with rill_balance and vw_key. - Primary pay tool after mint is rill_pay_url against any MPP/x402 HTTPS URL. - Same flow over HTTP: POST /wallets. --- # Pay any MPP or x402 URL Source: https://userill.com/docs/mcp/pay-url Complete a Spend against any HTTPS URL that challenges with MPP or x402 under the wallet’s budget. Tool: rill_pay_url Auth: Wallet key required (rill_vw_* via session, RILL_VW_KEY, or vw_key). Missing key returns a clear error. 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. Parameters: - url (string, no): HTTPS URL of the paid resource or gate (or pass directory_id) - directory_id (string, no): Directory profile id from rill_discover, resolves pay_url and preferred method - method (string, no): HTTP method when probing; defaults to catalog probe_method or GET - max_amount (number, no): USD ceiling for this pay (decimal dollars) - max_amount_cents (number, no): Integer cents ceiling; overrides max_amount when set - prefer_rail (auto|mpp|x402, no): When the gate offers both rails: auto (default) uses Base/x402 first; mpp forces Tempo; x402 forces Base only - headers (object, no): Extra request headers forwarded to the target - body (string|object, no): Request body for methods such as POST. When the directory row has body_hint, copy that shape and substitute your own values. - idempotency_key (string, no): Safe retries; auto-generated when omitted - vw_key (string, no): Overrides the session wallet key 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. --- # Pay inside Rill Source: https://userill.com/docs/mcp/pay Secondary path: pay a priced Rill resource or transfer USD to a handle or agent FQDN. Tool: rill_pay Auth: Wallet key required (rill_vw_* via session, env, or vw_key). Use this for seed demos and transfers inside Rill. Resource pays credit seller balance; handle transfers settle inside Rill. For any external HTTPS pay link, prefer rill_pay_url instead. Parameters: - resource_id (string, no): Priced resource id or short id (omit amount for resource pays) - to (string, no): Destination handle or agent FQDN for a transfer - destination (string, no): Alias of to - amount (number, no): USD amount; required for transfers, omit for resource pays - idempotency_key (string, no): Safe retries; auto-generated when omitted - vw_key (string, no): Overrides the session wallet key - metadata (object, no): Opaque metadata stored with the pay Notes: - Save receipt_id and pass it to rill_verify_receipt or X-Rill-Receipt on unlock. - Seed demo: pay resource_id SEED23, then GET /demo/echo with X-Rill-Receipt. - Resolve destinations first with rill_resolve_handle when transferring to a handle. - Same flow over HTTP: POST /pay. --- # Read balance or wallet status Source: https://userill.com/docs/mcp/balance Read seller balance and Connect flags, or wallet remaining allowance, depending on which key you pass. Tool: rill_balance Auth: Provide a seller key (rill_sk_*) or a wallet key (rill_vw_*). Session keys count. Missing both returns an error. With a seller key, this returns seller balance plus Connect readiness flags useful before withdraw. With a wallet key, it returns remaining period allowance and per-tx caps, the same data formerly exposed as rill_wallet_status. Parameters: - seller_key (string, no): Seller key for balance and Connect flags - vw_key (string, no): Wallet key for allowance status Notes: - Pass exactly one principal (seller or VW), or rely on the matching session key. - Call with vw_key after pays to stay inside budget. - Seller path over HTTP: GET /sellers/me/balance. VW path: GET /wallets/me/status. --- # Verify a receipt Source: https://userill.com/docs/mcp/verify-receipt Re-check a Rill receipt before unlocking paid content or trusting a payment succeeded. Tool: rill_verify_receipt Auth: No key required. Guest-safe. Call after a successful pay when the seller or unlock path needs an independent check. Sellers should still store used receipt_ids themselves for one-time unlock, verification alone does not consume the receipt. For the seed demo, after a ledger pay to SEED23, unlock with GET /demo/echo and the X-Rill-Receipt header. Parameters: - receipt_id (string, yes): Receipt id returned from pay - resource_id (string, no): Optional resource scope for the verify call Notes: - Open-world Accept gates may also accept Payment-Receipt / PAYMENT-RESPONSE headers from MPP/x402 clients. - Seed unlock over HTTP: GET /demo/echo with X-Rill-Receipt after paying SEED23 on the ledger. - Same flow over HTTP: POST /access/verify. --- # Fund an account wallet Source: https://userill.com/docs/mcp/fund Top up with Stripe Checkout (send the URL to a human), poll the funding intent, or mock-credit in development. Tool: rill_fund Auth: Bootstrap VW key (session or vw_key) or owner JWT. On guest MCP with no key, action=checkout auto-registers a bootstrap agent first. Agent-first on-ramp: rill_fund action=checkout + amount → checkout_url for a human → poll action=intent until paid → rill_pay_url. No owner JWT required for bootstrap wallets. Owner JWT still works for dashboard wallets (pass account_wallet_id). Dashboard Payment Element remains available for signed-in owners. action=mock is local/non-prod only (RILL_ALLOW_MOCK_FUND). Parameters: - action (checkout|intent|mock, yes): checkout creates Checkout; intent polls status; mock credits without Stripe when allowed - account_wallet_id (string, owner path): Required for owner JWT fund; optional for VW (uses the VW account wallet) - amount (number, checkout/mock): USD top-up amount (required for checkout and mock) - funding_intent_id (string, intent): Id returned from checkout (required for intent) - owner_jwt (string, no): Overrides session JWT for owner fund - vw_key (string, no): Overrides session VW key for agent fund - label (string, no): Optional label when auto-registering a bootstrap agent - idempotency_key (string, no): Safe retries for checkout and mock writes Notes: - Send checkout_url to the human; do not open it in the agent. - Poll action=intent until paid, then rill_pay_url. - Guest cold-start can skip rill_register_agent, checkout auto-registers when no key is present. - action=mock fails with mock_fund_disabled when Stripe is required in production. - Same flows over HTTP: POST /agent/fund-checkout (VW), POST …/accounts/:id/fund-checkout, GET /funding/:id. --- # List or create resources Source: https://userill.com/docs/mcp/resources List, create, update, or deactivate seller SKUs. Prefer rill_create_pay_link for a hosted Accept gate. Tool: rill_resources Auth: Seller key required (rill_sk_* via session, RILL_SELLER_KEY, or seller_key). Use action=list to inventory priced resources. Use action=create for a raw SKU when you will gate with your own SDK. action=update changes path or amount. action=deactivate sets active=false. For hosted Accept without an SDK, prefer rill_create_pay_link, it returns gate_url (agents pay this) and pay_page_url for humans. Parameters: - action (list|create|update|deactivate, yes): list inventory; create posts a SKU; update path/amount; deactivate sets active=false - path_or_tool (string, create; update optional): HTTP path or MCP tool name - amount (number, create; update optional): USD price - resource_id (string, update/deactivate): Existing resource id - resource_type (http|mcp, no): create only; defaults to http - seller_key (string, no): Overrides the session seller key Notes: - After create, call rill_create_pay_link with resource_id if you still want a hosted page. - Open-rail pays on the gate credit seller balance for Connect payout. - Same flows over HTTP: GET /resources, POST /resources, PATCH /resources/:id. CLI twin: update-resource. --- # Create a gate URL Source: https://userill.com/docs/mcp/create-pay-link Create or reuse a priced resource and return gate_url (agents pay this). Also returns pay_page_url for humans. Tool: rill_create_pay_link Auth: Seller key required (rill_sk_* via session, env, or seller_key). Primary Accept path for no-SDK sellers. Pass path_or_tool plus amount to create a resource, or pass resource_id to compose URLs for an existing SKU. Share gate_url with agents. pay_page_url is the same SKU for humans. Then enable payments and register a webhook to unlock on your product. Parameters: - path_or_tool (string, when creating): HTTP path or tool name when creating a new resource - amount (number, when creating): USD price when creating a new resource - resource_id (string, when reusing): Existing resource id to compose pay/gate URLs for - resource_type (http|mcp, no): Defaults to http when creating - seller_key (string, no): Overrides the session seller key Notes: - Provide resource_id, or path_or_tool + amount, never neither. - Save gate_url for agents (SKU). pay_page_url is the same link for humans (API field pay_url). - Next: rill_enable_payments, then rill_webhooks action=create for payment.succeeded. - Creates via POST /resources when no resource_id is supplied. CLI twin: create-pay-link. --- # Enable payments on the gate Source: https://userill.com/docs/mcp/enable-payments Enable MPP/x402 on seller gate URLs so agents can finish pay. Tool: rill_enable_payments Auth: Seller key required (rill_sk_*). Call after rill_create_pay_link when you want open-world MPP and x402 on the gate URL. Omitting stripe_profile_id adopts the platform profile for the seller money environment (Live or Test). Settlement lands in Stripe and credits seller balance for Connect payout. Parameters: - stripe_profile_id (string, no): Optional Stripe Profile id (profile_…). When omitted, uses the platform profile for this environment - mpp_enabled (boolean, no): Defaults to true - x402_enabled (boolean, no): Defaults to true - seller_key (string, no): Overrides the session seller key Notes: - Agents then pay the gate with rill_pay_url or native MPP/x402 clients. - After pay, seller balance increases. Connect Stripe (rill_connect) then rill_withdraw, or wait for auto payout when Connect is ready. - Same flow over HTTP: PATCH /sellers/me/payments. CLI twin: enable-payments. --- # Unlock on your product Source: https://userill.com/docs/mcp/webhooks Register, list, test, or delete HTTPS webhook endpoints. payment.succeeded is how Accept connects to your backend. Tool: rill_webhooks Auth: Owner Supabase JWT required (session or owner_jwt). Use action=create to register a callback for payment.succeeded so your product can grant access after pay. Delivery is signed and SSRF-safe. Use action=list to review registered endpoints. action=test sends a sample event. action=delete removes the endpoint. Save the signing secret from the create response, you need it to verify X-Rill-Signature. Parameters: - action (create|list|test|delete, yes): create registers a URL; list returns endpoints; test and delete need webhook_id - url (string, create): HTTPS callback URL (create only) - events (string[], no): Optional event allowlist (create only) - webhook_id (string, test/delete): Endpoint id from action=list - owner_jwt (string, no): Overrides session JWT for this call Notes: - Verify X-Rill-Signature and X-Rill-Timestamp (300s tolerance) on every delivery. - Localhost callbacks are allowed outside production. - Same flows over HTTP: POST /webhooks, GET /webhooks, POST /webhooks/:id/test, DELETE /webhooks/:id. CLI twin: webhooks create|list|test|delete. --- # Accept sellers Source: https://userill.com/docs/mcp/sellers List, create, inspect, update listing copy, or rotate Accept sellers. List before create after Authenticate. Tool: rill_sellers Auth: create, list, and rotate need an owner Supabase JWT (session or owner_jwt). me and update need a seller key (rill_sk_*). After Authenticate, call action=list before action=create so you resume an existing seller. action=create mints rill_sk_* (shown once); the MCP session adopts it. action=me returns the current seller. action=update sets website_url and description for directory listing. action=rotate mints a new key (shown once). Parameters: - action (create|list|me|update|rotate, yes): Which seller step to run - name (string, create): Seller display name - website_url (string, no): https company website for directory listing (create/update) - description (string, no): Short public listing copy (create/update) - seller_id (string, rotate): Seller id from action=list - owner_jwt (string, no): Overrides session JWT for create, list, and rotate - seller_key (string, no): Overrides the session seller key for me and update Notes: - List before create. Next: rill_create_pay_link (share gate_url) → enable payments → webhooks. CLI twins: create-seller, sellers list|rotate|update. - To get paid: rill_connect action=onboard (pass country), then rill_withdraw when payouts_enabled. - Same flows over HTTP: POST /sellers, GET /sellers, GET /sellers/me, PATCH /sellers/me, POST /sellers/:id/rotate-key. --- # Manage Stripe Connect Source: https://userill.com/docs/mcp/connect Run Connect steps for seller KYC: status, onboard, link, oauth, sync, or login. Tool: rill_connect Auth: Seller key required (rill_sk_*). Agent bootstrap wallet keys cannot open Connect. Send the human to https://userill.com/accept?connect=start. Onboard Stripe Express (default) so Accept pays can Transfer to your account, or link an existing Standard account. action=onboard returns an Account Link URL. action=link returns an OAuth URL for Standard. action=oauth completes the Standard link with the Stripe code. Pass country (ISO-3166, default US) on onboard. After KYC, poll action=sync until payouts_enabled. Then call rill_withdraw, or wait for auto payout. Parameters: - action (status|onboard|link|oauth|sync|login, yes): Which Connect step to run - code (string, no): oauth only: authorization code from Stripe - country (string, no): onboard only: ISO-3166 alpha-2 country code - seller_key (string, no): Overrides the session seller key Notes: - Never complete KYC inside the agent, always send onboard_url or login_url to the human. - Pass country on onboard (example EE, SN, CY). Default is US if omitted. - action=link + action=oauth links an existing Standard account. Money still Transfers from the Rill platform. - Same flows over HTTP: GET/POST /sellers/me/connect*. --- # Withdraw seller balance Source: https://userill.com/docs/mcp/withdraw Transfer seller balance to the connected Stripe account when payouts are enabled. Tool: rill_withdraw Auth: Seller key required. Connect must already report payouts_enabled. Call after rill_connect action=sync shows the seller is onboarded. This Transfers seller balance (including open-rail Accept credits) to Stripe Express. Auto payout also runs when Connect is ready and balance meets the minimum. Prefer rill_recycle when the owner wants ledger earnings back into the account wallet without a Stripe payout. Parameters: - amount (number, yes): USD amount to withdraw - seller_key (string, no): Overrides the session seller key - idempotency_key (string, no): Safe retries; auto-generated when omitted Notes: - connect_required / connect_incomplete means finish KYC with rill_connect first. - Check balance with rill_balance and seller_key before withdrawing. - Same flow over HTTP: POST /sellers/me/withdraw. --- # Recycle seller balance Source: https://userill.com/docs/mcp/recycle Move seller ledger balance into the owner account wallet without a Stripe payout. Tool: rill_recycle Auth: Owner Supabase JWT required. You must know the seller_id. Use this when you want seller earnings back under the owner wallet for Spend, instead of Express withdraw. Opposite direction from rill_withdraw. Recycle does not require Connect KYC. Parameters: - seller_id (string, yes): Seller id whose balance to move - amount (number, yes): USD amount to recycle - owner_jwt (string, no): Overrides session JWT for this call - idempotency_key (string, no): Safe retries; auto-generated when omitted Notes: - After recycle, the owner can fund/mint Spend again from the account wallet. - Does not require Connect KYC. - Same flow over HTTP: POST /sellers/:id/recycle. --- # Sync payment directory Source: https://userill.com/docs/mcp/sync-directory Refresh the cached MPP + x402 directory catalog and start re-probing pay URLs. Tool: rill_sync_directory Auth: Owner Supabase JWT required (session or owner_jwt). Reindexes Rill sellers, mpp.dev / Stripe / public x402 catalogs, remaps leftover payment_ready rows, then starts probes in the background. Returns remapped counts and probe.status=started. Probe history is appended as checks finish. Parameters: - owner_jwt (string, no): Overrides session JWT for this call Notes: - List spendable gates with rill_list_directory payment_ready=true after sync. - Probe history is retained so status changes are visible over time. - Same flow over HTTP: POST /directory/sync. --- # Privacy policy Source: https://userill.com/docs/privacy This policy explains what information Rill collects, how we use it, and the choices you have. Rill is operated by lomi. Inc (we, us). Affiliates include lomi. Technologies Africa S.A. Rill is a separate service from lomi.africa. Using Rill does not create a lomi.africa merchant agreement, and Rill card funding, Connect verification, and payouts go through Stripe, not lomi.africa payment channels. This policy applies to the Rill website, owner dashboard, API, MCP (including guest), pay links under /r/, and the directory (together, the Service). We collect information in these categories: Account: email address, name, company name, handle, and sign-in data when you use an email link, Google, or GitHub. Wallets and money: balances, funding records, receipts, withdraw and recycle activity, and whether you are using Live or Test. Agent and seller keys: we store hashes and prefixes after a key is created. The full key is shown once at mint. Spend logs may include the URL, amount, rail, status, and a truncated response. Webhooks: the endpoint URL, an encrypted signing secret, event subscriptions, and delivery payloads. Connected apps: MCP OAuth grants, client name, scopes, and last-used time. Guest and bootstrap use: IP address and rate-limit data used to register agents and stop abuse. Directory: cached metadata about third-party pay endpoints. A Spend payment does not send your organization profile to the payee unless you include it on the request. Communications: messages you send to @userill.com addresses. Inbound mail is forwarded to operators. Browser storage: essential sign-in cookies; local storage for theme, Live/Test preference, docs progress, and an optional docs key vault if you choose to store keys in the browser. We use information to: Operate Accept and Spend, including wallets, pay links, receipts, and budgets. Settle payments through Stripe and open rails (MPP and x402). Enforce allowances, allowlists, rate limits, and abuse controls. Provide support and respond to legal or security requests. Improve reliability and the product. Comply with law and enforce our Terms of use. We do not send marketing email unless you ask us to. Sign-in links, receipts of action you took, and operational notices are not marketing. We do not sell personal information. We may share information with: Stripe, to process card top-ups, Connect verification and payouts, and open-rail settlement. Authentication and database providers that run accounts and store Service data. An email provider for sign-in links and mail you send to @userill.com. Website analytics on userill.com. Infrastructure hosts that run the website, API, and MCP. Affiliates in the lomi. group when needed to operate or support Rill. Professional advisers or authorities when required by law or to protect rights, safety, and security. We may share aggregated or de-identified information that cannot reasonably identify you. The Service is used globally. Information may be stored and processed outside your country, including in the United States, where privacy rules may differ. We take steps designed to keep that information protected to the standards in this policy. We keep account data while your account is active and as needed to operate the Service, resolve disputes, and meet legal duties. If you delete your account in settings or email privacy@userill.com, we remove account access and related records we no longer need. Some payment, ledger, and receipt records may be kept for tax, disputes, Stripe, or other legal requirements. Deleting an account is not a wipe of every historical payment record. Depending on where you live, you may have rights to: Access, correct, or delete personal information we hold about you. Object to or restrict certain processing. Withdraw consent where processing is based on consent. Request a copy of your data in a portable format. You can delete a signed-in account from settings. To exercise these rights, email privacy@userill.com. We may need to verify the account before we respond. We use essential cookies to keep you signed in. The browser may also store theme, Live/Test preference, and docs progress. If you use the docs key vault, keys stay in local storage on your device until you clear them. The website uses Vercel Analytics. We do not use a cookie banner for these essential and first-party measures. If we add non-essential tracking later, we will update this policy. A wallet key or guest MCP session can create logs and payments the same way a signed-in person can. For that wallet, we treat the account owner as the person those records belong to. The Service is not directed to children under 13, or under 16 where that is the required minimum. We do not knowingly collect personal information from children. We use technical and organizational measures designed to protect information. See for access controls, money safeguards, and how to report a vulnerability. We may update this Privacy policy. We will post the revised version with an updated last-updated date. Continued use after changes means you accept the updated policy. Questions about privacy: privacy@userill.com --- # Terms of use Source: https://userill.com/docs/terms These Terms govern access to and use of Rill. Please read them carefully. By using the Rill website, dashboard, API, MCP (including guest), pay links, or by signing in, you agree to these Terms of use. The is part of this agreement. If you use the Service on behalf of an organization, you represent that you have authority to bind that organization. These Terms are between you and lomi. Inc (we, us), the operator of Rill. Affiliates include lomi. Technologies Africa S.A. Affiliates may help operate or support Rill. They are not a second product contract. Rill is software that lets companies accept agent payments and lets funded agents pay endpoints under a budget. Accept hosts pay links and settles through MPP and x402. Spend funds a wallet, sets a budget, and pays a URL. Handle transfers and POST /pay remain available as a background ledger. Features may change over time. Rill is not a bank, not a marketplace, and not a consumer mall. You keep your product, your price, and your fulfillment. Wallet balances are prepaid credits for use of the Service. They are not bank deposits and are not insured. Stripe processes card top-ups and Connect payouts. Open-rail pays may settle in stablecoins on public networks. Rill is a separate service from lomi.africa. Using Rill does not create a lomi.africa merchant agreement and does not give you lomi.africa collection rails. Rill card funding, Connect verification, and payouts go through Stripe. You are responsible for keeping sign-in credentials, Accept keys, and wallet keys secret, and for all activity under those credentials, including automated spends by agents you authorize. You must provide accurate account information and tell us promptly about unauthorized use. Revoke keys if they leak. You set allowances and optional host allowlists. An empty allowlist means the wallet may pay allowed HTTPS URLs under Service policy. Using a wallet key, guest MCP, or a bootstrap registration tied to you binds you to these Terms for that activity. The person who owns or funds the account is responsible for agent actions taken with those keys. Live and Test are separate money environments. Test is not real money. You must choose the environment. Do not treat Test receipts, balances, or payouts as live settlement. You can add funds to a wallet through Stripe Checkout or the payment form we show. The minimum top-up is one U.S. dollar. Card processing fees may be added on checkout. The wallet is credited the face amount you chose. Rill does not currently charge a platform fee (0 basis points). We may change this. The current rate is published in the Service, including GET /agent/capabilities. Transfers between wallets on Rill do not take a platform fee. If you sell, you set the price and you fulfill the unlock in your own product. Receipts are re-verifiable. You should store used receipt_id values so a receipt cannot unlock twice. Connect verification and payouts are provided by Stripe. Where you use Connect, you also agree to the Card chargebacks apply to wallet top-ups processed by Stripe, not to open-rail agent pays that have already settled. Paying a URL is your instruction. Directory listings and probe status are not a promise that an endpoint is safe, current, or will unlock. Open-rail pays are typically irreversible. We are not liable for what a paid URL returns, for a seller who fails to unlock, or for harm from a URL you ask us to call. You must not use Spend to attack, scan, or reach systems you are not allowed to access. The directory caches third-party service metadata so agents can find pay endpoints. A listing is not an endorsement, not a guarantee of payment readiness, and not legal advice. You may use the Service only for lawful purposes. You may not: Violate applicable law, sanctions, or export rules. Use Rill for money laundering, fraud, card testing, ransomware, or other prohibited financial activity. Use Rill as a remittance or cash-out rail that is not tied to a real software capability you sell or pay for. Upload or traffic child sexual abuse material, or exploit minors. Attempt unauthorized access, overload the Service, or bypass rate limits, signatures, or access controls. Misrepresent your identity, your product, or a pay link price. We may remove resources, revoke keys, freeze wallets, or suspend accounts when we believe these Terms have been violated. Report abuse to abuse@userill.com. You must verify webhook signatures before you fulfill. We grant you a limited, revocable, non-exclusive, non-transferable license to call the hosted API and MCP solely to use the Service. Open-source kits such as @userill/accept and @userill/spend have their own licenses. Those licenses cover the kits. These Terms cover the hosted Service. The Service is provided without a service-level agreement unless we sign a separate one with you. We may apply rate limits and fair-use controls. We may modify, suspend, or discontinue any part of the Service with notice where practicable. The Rill name, software, documentation, and directory compilation are owned by us or our licensors. You may not copy or misuse them except as allowed by these Terms. You keep your product, your API, and content you submit, and you grant us a limited license to host and process that content solely to operate the Service. The Service is provided as is and as available, without warranties of any kind, whether express or implied, including merchantability, fitness for a particular purpose, and non-infringement. We do not warrant that the Service will be uninterrupted, error-free, or free of harmful components, or that a third-party endpoint will unlock after a pay. To the maximum extent permitted by applicable law, lomi. Inc and its affiliates will not be liable for indirect, incidental, special, consequential, or punitive damages, or for loss of profits, data, goodwill, or irreversible open-rail settlement. Our total liability for any claim relating to the Service is limited to the greater of (a) amounts you paid us for Rill in the twelve months before the claim or (b) one hundred U.S. dollars, except where applicable law does not allow that limit. You will defend and indemnify lomi. Inc and its affiliates, and their officers, directors, and employees, against claims, losses, and costs arising from your use of the Service, your agents' use, your pricing or fulfillment, leaked keys, prohibited use, or third-party claims from URLs you pay or pay links you host, except to the extent caused solely by our fraud or willful misconduct. You may stop using the Service or delete your account from settings, or by emailing support@userill.com or privacy@userill.com. We may suspend or terminate access for abuse, legal risk, unpaid amounts, or requirements from Stripe or payment networks. After termination, some payment and ledger records may remain as described in the Privacy policy. Sections that should survive (including disclaimers, limitation of liability, indemnity, and governing law) will survive. We may update these Terms. We will post the revised version with an updated last-updated date, and we may also notify you through the Service when a change is material. Continued use after changes means you accept the updated Terms. These Terms are governed by applicable laws without regard to conflict-of-law principles. Courts with appropriate jurisdiction may hear disputes, subject to mandatory consumer protections where you live. Questions about these Terms: legal@userill.com --- # Agent corpus index Source: https://userill.com/agents - https://userill.com/agents/product - https://userill.com/agents/spend - https://userill.com/agents/accept - https://userill.com/agents/mcp-quickstart