riOs docs
ConsoleGet your key
Docs · riOs 0.1.0

Prepay what you can. Your AI handles the rest.

riOs is an MCP server. Connect it to Claude, ChatGPT, Cursor or any MCP client and your AI can cover your subscriptions for the months you can afford. You approve once in PayPal, riOs locks the money for that subscription and pays every renewal on its due date.

Get your keyOpen consoleGitHub
9MCP tools
3PayPal APIs
0%fee during the hackathon
3 daysto cancel for a full refund

Quickstart

  1. Get a key. api.riospay.xyz/signup gives you a riOs key and a connector link.
  2. Connect your AI. Paste the connector link into your AI's connector settings (guides below).
  3. Ask. “Pay for my design tool, $25 a month to billing@designtool.com, renewing today. Cover it for 3 months.”
  4. Approve in PayPal. Your AI gives you a PayPal link. You approve. riOs locks the money and you're covered.

riOs runs on PayPal's sandbox during the hackathon. No real money moves. Use a PayPal sandbox personal account to approve.

Connect your AI

Every client talks to the same endpoint, https://api.riospay.xyz/mcp, using MCP's Streamable HTTP transport. Your key goes in an Authorization: Bearer header, or inside the URL for clients that only accept a link.

  1. In Claude, open Settings → Customize → Connectors → Add custom connector.
  2. Name it riOs and paste your connector link. Choose No sign-in.
  3. Turn on riOs in a chat's tools menu.
Connector link
https://api.riospay.xyz/mcp/k/<your-key>

How the money moves

1
You ask your AI

“Cover my design tool for 3 months.” Your AI calls rios_quote: $25 × 3 = $75, no fee.

2
riOs creates a PayPal order

rios_fund_subscription creates the checkout and returns the approve link.

Orders v2 · create
3
You approve in PayPal

Only you can. Your AI never sees your login or card.

4
riOs captures and locks

The money is locked for that one subscription and payee. The PayPal return page and rios_check_funding both capture, safely, at most once.

Orders v2 · capture
5
Every renewal date, riOs pays

A daily job pays exactly one month to the provider and moves the date forward.

Payouts v1
↺
Changed your mind?

Within 3 days, rios_cancel_deposit refunds whatever hasn't been paid out yet.

Payments v2 · refund
StepPayPal APISafety
FundPOST /v2/checkout/ordersAmount checked against the quote on capture
LockPOST /v2/checkout/orders/{id}/captureIdempotent: confirming twice never captures twice
Pay renewalPOST /v1/payments/payoutsOne payout per renewal; failures return the money to the balance
RefundPOST /v2/payments/captures/{id}/refundOnly the unspent part, only inside the window

Every money-moving call sends a PayPal-Request-Id, so a retry can never charge or pay twice.

The rules

Locked to one payee

Once funded, a subscription's payee and amount can't change. Even a tricked AI can't send locked money anywhere else.

Only you approve

Every payment is approved by you inside PayPal. The AI can prepare it, never press pay.

3-day cancel window

Cancel within 72 hours for a refund of everything not yet paid out. After that it stays locked for the provider.

Failed payout? Nothing lost

If PayPal rejects a payout, the money goes back to the balance and the subscription pauses for review.

Never pays itself

riOs refuses any payee that is riOs's own PayPal account.

Your key, your scope

A key only sees its own subscriptions. riOs stores a fingerprint of it, never the key itself.

MCP tools

Generated from the running server. Typical flow: rios_add_subscription → rios_quote → rios_fund_subscription → user approves → rios_check_funding.

rios_add_subscription

Add a subscription

Add a subscription riOs should pay. payee_email is the PayPal account that receives each renewal payment. Once funded, the payee and amount can no longer change.

InputTypeAbout
namerequiredstringWhat it is, e.g. "Spotify" or "Design tool"
payee_emailrequiredstringPayPal email address of whoever gets paid each month
monthly_amountrequiredstringAmount per month, e.g. "10.99"
next_billing_datestringNext renewal date, YYYY-MM-DD. Defaults to today.
Arguments
{
  "name": "Design tool",
  "payee_email": "billing@designtool.com",
  "monthly_amount": "25.00",
  "next_billing_date": "2026-11-10"
}
Result (shortened)
{
  "subscription_id": "sub_H-aB5pBwB15y",
  "name": "Design tool",
  "monthly": "25.00",
  "next_renewal": "2026-11-10",
  "locked_balance": "0.00",
  "renewals_covered": 0
}

rios_list_subscriptions

List subscriptions and runway

Show every subscription with its locked balance, how many renewals are covered, the date it is paid through, fundings waiting for approval and deposits that can still be cancelled.

No inputs.

Arguments
{}
Result (shortened)
{
  "count": 1,
  "subscriptions": [
    {
      "name": "Design tool",
      "monthly": "25.00",
      "locked_balance": "75.00",
      "renewals_covered": 3,
      "covered_through": "2027-02-09",
      "payee_locked": true
    }
  ]
}

rios_quote

Quote a funding

Work out what it costs to cover a subscription for a number of months, and which renewal dates that covers. Does not charge anything.

InputTypeAbout
subscription_idrequiredstringFrom rios_list_subscriptions
monthsrequiredinteger 1–24
Arguments
{
  "subscription_id": "sub_H-aB5pBwB15y",
  "months": 3
}
Result (shortened)
{
  "months": 3,
  "covered_amount": "75.00",
  "fee": "0.00",
  "total_to_pay": "75.00",
  "renewals_covered": [
    "2026-11-10",
    "2026-12-10",
    "2027-01-10"
  ]
}

rios_fund_subscription

Fund a subscription

Create a PayPal checkout to cover a subscription for N months. Returns approve_url: give it to the user, who approves the payment in PayPal themselves. After approval the funds are locked for this subscription.

InputTypeAbout
subscription_idrequiredstringFrom rios_list_subscriptions
monthsrequiredinteger 1–24
Arguments
{
  "subscription_id": "sub_H-aB5pBwB15y",
  "months": 3
}
Result (shortened)
{
  "deposit_id": "dep_At0cWK29L3WF",
  "status": "waiting_for_approval",
  "total_to_pay": "75.00",
  "approve_url": "https://www.sandbox.paypal.com/checkoutnow?token=…"
}

rios_check_funding

Check a funding

Check whether the user has approved a funding in PayPal. If approved, riOs captures the payment and locks the funds.

InputTypeAbout
deposit_idrequiredstringFrom rios_fund_subscription
Arguments
{
  "deposit_id": "dep_At0cWK29L3WF"
}
Result (shortened)
{
  "status": "locked",
  "covers": "75.00",
  "cancel_until": "2026-11-13T14:10:10Z"
}

rios_cancel_deposit

Cancel a deposit

Cancel a deposit within 3 days of approval and refund the part not yet paid out to the user's PayPal. After 3 days deposits are locked and this will refuse. Also cancels a funding that is still waiting for approval (nothing was paid, so nothing is refunded). Confirm with the user before calling.

InputTypeAbout
deposit_idrequiredstringFrom rios_list_subscriptions (cancellable_deposits or waiting_for_approval)
Arguments
{
  "deposit_id": "dep_At0cWK29L3WF"
}
Result (shortened)
{
  "status": "refunded",
  "refunded": "75.00",
  "fee_kept": "0.00"
}

rios_plan_budget

Plan a budget

Given an amount of money, suggest how many months of each subscription it can cover, filling them one month at a time in priority order. Does not charge anything.

InputTypeAbout
budgetrequiredstringAmount available, e.g. "50"
subscription_idsarrayOptional priority order. Defaults to all active subscriptions.
Arguments
{
  "budget": "50"
}
Result (shortened)
{
  "budget": "50.00",
  "plan": [
    {
      "name": "Design tool",
      "months": 1,
      "cost": "25.00"
    },
    {
      "name": "Music",
      "months": 2,
      "cost": "21.98"
    }
  ],
  "left_over": "3.02"
}

rios_activity

Recent activity

Recent events: subscriptions added, fundings locked, renewals paid or failed, refunds.

InputTypeAbout
limitinteger 1–100
Arguments
{
  "limit": 3
}
Result (shortened)
[
  {
    "type": "renewal_paid",
    "subscription": "Design tool",
    "amount": "25.00",
    "period": "2026-11-10"
  }
]

rios_remove_subscription

Remove a subscription

Remove a subscription that has no locked funds left.

InputTypeAbout
subscription_idrequiredstringFrom rios_list_subscriptions
Arguments
{
  "subscription_id": "sub_H-aB5pBwB15y"
}
Result (shortened)
{
  "removed": true
}

Raw MCP

riOs speaks JSON-RPC 2.0 over Streamable HTTP (stateless JSON responses). Protocol versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05.

Call a tool
curl -s https://api.riospay.xyz/mcp \
  -H "Authorization: Bearer <your-key>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"rios_list_subscriptions","arguments":{}}}'
Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"count\":1,\"subscriptions\":[…]}"
      }
    ],
    "structuredContent": {
      "count": 1,
      "subscriptions": [
        "…"
      ]
    }
  }
}

Console API

The console uses a small JSON API with the same key. Send Authorization: Bearer <your-key>.

MethodPathDoes
GET/v1/meYour account name
GET/v1/subscriptionsSubscriptions, balances, runway
POST/v1/subscriptionsAdd a subscription
POST/v1/subscriptions/{id}/quoteQuote N months
POST/v1/subscriptions/{id}/fundCreate the PayPal checkout
DELETE/v1/subscriptions/{id}Remove (no locked funds)
POST/v1/deposits/{id}/checkCapture and lock an approved funding
POST/v1/deposits/{id}/cancelCancel a checkout, or refund inside the window
GET/v1/activityRecent events
Example
curl -s https://api.riospay.xyz/v1/subscriptions -H "Authorization: Bearer <your-key>"

Limits & roadmap

  • Sandbox only. Live mode is blocked in code until riOs is registered and approved for live Payouts.
  • Providers need PayPal. Payouts only reach PayPal accounts. Netflix, Spotify and other big brands come next through virtual cards: one card per subscription, topped up from the locked balance on renewal day.
  • Limits. Up to 24 months per funding, $1–$1,000 a month, 25 subscriptions per account.
  • Coming: renewal notifications, more ways to fund (cards, bank, local rails), and gifting a subscription to someone else.

Source code

riOs is open source (MIT) with zero dependencies: Node 20+, PayPal REST, MCP.

Run it yourself
git clone https://github.com/nedsoft057/riOs.git
cd riOs && cp .env.example .env   # add your PayPal sandbox app keys
npm test                           # runs against a fake PayPal
npm start                          # http://localhost:8787/mcp
src/vault.jsmoney rules: subscriptions, deposits, renewalssrc/paypal.jsPayPal REST clientsrc/mcp.jsMCP protocol and tool definitionssrc/http.jsroutes: MCP, PayPal return, console API, cronsrc/web.jsconsole and pagessrc/docs.jsthis page