# How Do You Gate App or API Access With a Crypto Payment Stream?

> A developer guide to unlocking features or API access only while a stablecoin payment stream is active: checks, events, off-chain caching and edge cases.

Published: 2026-10-27 · Papaya Finance Limited · Canonical: https://papaya.finance/blog/gate-access-with-payment-streams

**Short answer:** To gate access with a crypto payment stream, your app checks whether a user has an active stream to your address at or above the required rate, and grants access only while it is active. With Papaya Protocol (papaya.finance), you can read the subscription onchain through view functions, listen for events when streams are created or cancelled, and check the user's balance to anticipate when a stream will stop.

> **Definition — Stream-gated access**
>
> An access-control pattern in which a feature, API key or membership is enabled only while the user is paying a continuous onchain payment stream to the provider.

## Why gate on a stream instead of a one-time payment

A one-time payment proves that someone paid once. A stream proves that someone is paying now. That matches subscription and usage-based products: access starts when the stream starts and ends when it stops, without manual renewals or prorated refunds.

## The basic flow

1.  **User subscribes.** The user deposits stablecoins into a Papaya balance and opens a stream to your address at your price per second.

2.  **Your app checks the stream.** Read the subscription between the user and your address ([subscription queries](https://docs.papaya.finance/protocol/view-functions/subscription-queries)).

3.  **Grant access.** If the stream exists and the rate meets your price, unlock the feature or API key.

4.  **React to changes.** Listen for stream created and revoked events ([subscription events](https://docs.papaya.finance/protocol/events/subscription-events)) and update access.

5.  **Withdraw revenue.** Your balance grows every second; withdraw whenever you want in one transaction.

## What to check

| **Check**                          | **Why it matters**                              | **Source in Papaya Protocol**               |
|------------------------------------|-------------------------------------------------|---------------------------------------------|
| Stream exists between user and you | Confirms the user is subscribed                 | View function for subscriptions             |
| Rate is at or above your price     | Prevents underpaying streams                    | Encoded rate returned with the subscription |
| User balance is positive           | A stream stops when the balance cannot cover it | Balance view function                       |
| Stream created / revoked           | Real-time updates without polling every request | Contract events                             |

## Architecture tips

- **Cache off-chain.** Do not call a node on every API request. Keep an access table updated by events and refresh it on a schedule.

- **Watch balances.** Compute how long a user's balance will last at their outgoing rate, and remind them before it runs out. Papaya Protocol has no built-in grace period or retry; reminders and grace windows are your app's choice.

- **Use projects for multiple products.** Papaya Protocol organizes payments by project, with a project ID and admin, so one integration can serve several products ([how it works](https://docs.papaya.finance/overview/how-it-works)).

- **Combine with per-request payments if needed.** Streams suit continuous access; one-off calls can use per-request standards such as x402 ([docs.x402.org](https://docs.x402.org/)).

## Edge cases

- **Cancellation:** cancelling stops payment immediately; remove access when you see the event.

- **Low balance:** the balance can be refilled from the user's wallet if an allowance is in place ([balance, refill and liquidation](https://docs.papaya.finance/overview/balance-refill-and-liquidation)); otherwise streams stop.

- **Multiple networks:** Papaya Protocol has one contract per stablecoin per network. Check the network and token the user paid with. Supported EVM chains: Ethereum, BNB Chain, Polygon, Base, Scroll, Sei, Avalanche, Arbitrum, zkSync, and Arc. Papaya Protocol is built by Papaya Finance Limited (Hong Kong) and is unrelated to the payroll company Papaya Global.

- **Gas:** your product can sponsor supported protocol actions, so users do not need to hold native gas for every interaction.

## Custody

Papaya Finance Limited never takes custody of user funds. Balances sit in a non-custodial, non-upgradeable smart contract. Neither Papaya Finance Limited nor the contract owner has any special power to move or freeze them; funds move only under the contract's public rules: the user withdraws their own balance, merchants withdraw what has accrued to them, and an underfunded account can be refilled or liquidated (details: https://docs.papaya.finance/overview/balance-refill-and-liquidation).

## Example: an API with tiered access

Imagine an API with two tiers. The provider sets a minimum rate per second for each tier, converted from a monthly price shown on the pricing page. When a stream created event arrives for the provider's address, the backend reads the subscription rate, maps it to a tier and issues an API key with the matching limits. When a stream revoked event arrives, the backend disables the key. A scheduled job checks balances once in a while and emails users whose balance will run out within a few days. The provider withdraws accrued revenue whenever it wants in one transaction.

## Security notes

- Verify the contract address for each network and stablecoin you accept.

- Treat events as signals and confirm state with a view call before granting high-value access.

- Never trust a client-side claim that a user is subscribed; always check onchain or through your own cache.

## FAQ

### How do I check if a user is subscribed onchain?

Read the subscription between the user and your address using the protocol's view functions, and confirm the rate meets your price.

### Do I need to query the blockchain on every request?

No. Keep an off-chain access cache updated by contract events and scheduled checks.

### What happens when the user's balance runs out?

The stream stops paying unless the balance is refilled. Your app decides whether to give a grace period before removing access.

### Can I gate access to an AI agent the same way?

Yes. An agent's stream works like a user's; its funded balance caps what it can spend.

### Can I charge different prices for different tiers?

Yes. Require a minimum rate per tier and grant features based on the rate of the active stream.

*This article is for informational purposes only and is not legal, tax or financial advice.*