---
updatedAt: 2026-06-19T17:51:32.000Z
agentTools:
  projectIndex: https://docs.oasy.ai/llms.txt
---

# Metered paywall

Free quota, window, checkout URL — and how idempotent re-reads keep it fair.

The meter governs **PAYWALL-policy** articles only. `Observe` and `Advertise`
articles always serve; `Block` always 403s.

## Configuration

On the [MCP page](https://app.oasy.ai/mcp) → **Paywall & Identity** section:

| Knob                         | What                                                            | Default |
| ---------------------------- | --------------------------------------------------------------- | ------- |
| **Free articles per window** | How many PAYWALL articles an install can read before the upsell | `5`     |
| **Window**                   | `day` / `week` / `month` — how often the quota resets           | `month` |
| **Checkout URL**             | Where the upsell payload sends unsubscribed readers             | unset   |
| **Require OAuth**            | When on, MCP route 401s without a token, forcing DCR + PKCE     | off     |

## How the meter counts

The meter is a counter keyed by `(installId, articleId, windowKey)`:

* **`installId`** is the OAuth `client_id` when the request carries a verified
  bearer token, or the MCP session id otherwise.
* **`articleId`** is the article being fetched.
* **`windowKey`** is the bucket — e.g. `"2026-06"` for monthly.

Re-fetching the same article within the same window **doesn't burn a credit**
— the row already exists, the meter no-ops. This is what lets agents
follow up on an article they already read without penalizing the reader.

## When the meter trips

`get_article` returns a structured upsell payload instead of the body:

```json
{
  "status": "paywalled",
  "article": { "title": "...", "summary": "...", "url": "..." },
  "meter": { "remaining": 0, "limit": 5, "window": "month" },
  "upsell": {
    "headline": "You've used your 5 free articles this month.",
    "cta": "Subscribe to continue reading.",
    "checkoutUrl": "https://..."
  }
}
```

The agent renders this inline — Claude, ChatGPT, etc. all show the headline

* CTA to the user.

## Subscriber bypass

If a reader links their subscription via [Flip-Pay](https://docs.oasy.ai/docs/flip-pay) or the
[HMAC webhook](https://docs.oasy.ai/docs/hmac-webhook), their OAuth tokens get `tier=subscriber`
and the meter early-returns. Their PAYWALL articles serve normally with no
`MeterEvent` row written.

## Recommended starting values

* **5 articles / month** for general-interest publications.
* **3 articles / month** for serious trade or investigative titles where the
  per-article value is high.
* **Checkout URL** → wherever your existing reader subscription flow lives.

You can tune these any time without affecting in-flight meter rows.