Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

solvapay

SolvaPay for Python: paywalls, usage billing, webhooks and paid MCP tools.

pip install solvapay            # API client, paywall, webhooks
pip install 'solvapay[mcp]'     # paid tools for the official MCP Python SDK
pip install 'solvapay[web]'     # the routes @solvapay/react calls

Python 3.10+. Typed (py.typed), async-first, with blocking twins for the API client.

Configure

export SOLVAPAY_SECRET_KEY=sk_sandbox_...   # required
export SOLVAPAY_PRODUCT_REF=prd_...         # the product paid calls bill against
export SOLVAPAY_API_BASE_URL=...            # optional; defaults to https://api.solvapay.com

Copy the secret key and product reference from SolvaPay Console (Developers → API keys, and the product's page). npx solvapay init writes them to .env too, but it is a Node.js tool and installs npm packages in a folder without package.json.

Make a function paid

import asyncio

from solvapay import PaywallError, create_solvapay

solvapay = create_solvapay()


@solvapay.payable()
async def summarise(text: str, *, customer_ref: str) -> str:
    return text[:100]


async def main() -> None:
    try:
        summary = await summarise("...", customer_ref="user_123")
        print(summary)
    except PaywallError as error:
        print(error.gate["message"])  # what the customer should see, with a checkout link


asyncio.run(main())

SOLVAPAY_PRODUCT_REF must be set before this module is imported: @solvapay.payable() reads it when it decorates the function, so a missing product fails at import, not on the first call.

customer_ref is your own user id: SolvaPay creates the customer on first use. Each call is checked against the customer's plan, and billed when it succeeds.

Paid MCP tools

from solvapay import create_solvapay
from solvapay.mcp import ResponseContext, create_solvapay_mcp_server

mcp = create_solvapay_mcp_server(
    solvapay=create_solvapay(),
    public_base_url="https://research.example.com",
)


async def quote(symbol: str, ctx: ResponseContext):
    return ctx.respond({"symbol": symbol, "price": 101.5})


mcp.register_payable("quote", handler=quote, description="Latest price for a symbol.")

app = mcp.http_app()  # serve with uvicorn; the MCP endpoint is /mcp

Customers sign in with SolvaPay over OAuth, and every bearer token is verified with SolvaPay. A call over the customer's limit returns the paywall: a message naming the next step, with a checkout link. See examples/python-stock-research-mcp.

The server also comes with SolvaPay's built-in tools, as the TypeScript server does: account shows the customer's plan, balance and usage with a checkout, top-up or account link (view: checkout, account or topup), and activate_plan activates a plan by planRef. The /upgrade, /manage_account, /topup and /activate_plan prompts and the docs://solvapay/overview.md resource come with them. Pass views=[...] to choose the views, or views=[] to leave account out.

The checkout widget

On hosts that support MCP Apps (ChatGPT, Claude), account also opens SolvaPay's checkout and account widget in the chat, the same one the TypeScript SDK serves. It ships in this package (solvapay/mcp/mcp-app.html) and is served at ui://<name>/mcp-app.html (resource_uri= to change it). Text-only hosts get the same text as before; mode: "text" asks for text on any host.

The widget pays, tops up, cancels and reactivates renewals through six tools only it calls: create_payment_intent, process_payment, create_hosted_session, set_renewal, attach_business_details and get_history. They are marked for the app (_meta.ui.visibility: ["app"]), so MCP Apps hosts keep them from the model. For a host that lists them anyway, hide_tools_by_audience=["ui"] leaves them out of tools/list; ChatGPT still gets them, since its widget can only call listed tools.

Its Content Security Policy allows Stripe and the SolvaPay API. Add domains with csp={"connectDomains": [...], "resourceDomains": [...], "frameDomains": [...]}.

Paid by agents (preview)

solvapay.agents.mcp.create_agent_mcp_route serves an MCP server that SolvaPay agents pay for per call: each paid tool call is authorized with SolvaPay before it runs and completed at the cost the upstream reports. Install solvapay[agents,mcp].

Agent payments are a preview. SolvaPay turns them on per merchant, and live agent payments aren't open yet, so build and test with a sandbox key.

React web checkout

solvapay.web.routes() serves every route the @solvapay/react components call (/api/check-purchase, /api/create-payment-intent, /api/list-plans, …), answering as @solvapay/server/fetch's solvapayRoutes() does, so the React components work with a Python backend. Install solvapay[web].

from starlette.applications import Starlette
from starlette.requests import Request
from starlette.routing import Mount

from solvapay import create_solvapay
from solvapay.web import User, routes


async def get_user(request: Request) -> User | None:
    # Verify the request with your app's own auth: its session cookie or bearer
    # token, checked the way the rest of your app checks it.
    session = await my_app_session(request)  # your code
    if session is None:
        return None
    return User(id=session.user_id, email=session.email, name=session.name)


solvapay = create_solvapay()
app = Starlette(routes=[Mount("/api", app=routes(solvapay, get_user=get_user, base_path=""))])

In FastAPI, app.mount("/api", routes(solvapay, get_user=get_user, base_path="")).

get_user is required and is the only source of identity: your user id becomes the SolvaPay customer's externalRef, and the customer is created with the email and name on first use. Answer None for a request without a signed-in user; the routes refuse it with 401 before calling SolvaPay. Nothing the browser sends is identity: an x-user-id header is ignored. merchant, get-product and list-plans answer without a user, as in TypeScript.

base_path (default /api) is where the routes are below the mount point. Another path answers 404, and a known path with the wrong method 405 with Allow. The routes don't add CORS headers: serve them from your app's own origin, or add Starlette's CORSMiddleware.

Verify webhooks

import os

from solvapay import SolvaPayError, verify_webhook

try:
    event = verify_webhook(
        body=raw_body,  # bytes or str, exactly as received
        signature=request.headers["sv-signature"],
        secret=os.environ["SOLVAPAY_WEBHOOK_SECRET"],
    )
except SolvaPayError as error:
    ...  # error.code: webhook_secret_missing, webhook_signature_invalid, webhook_timestamp_out_of_tolerance, ...

The API

Every SolvaPay API operation, generated from the API spec:

import asyncio

from solvapay import AsyncApiClient


async def main() -> None:
    async with AsyncApiClient(api_key="sk_sandbox_...") as api:
        customer = await api.get_customer(reference="cus_123")
        balance = await api.get_customer_balance(reference="cus_123")
        print(customer.email, balance)


asyncio.run(main())

ApiClient is the blocking twin. Errors are SolvaPayError with a stable code and the HTTP status; branch on those, not on the message.

Same behaviour as the TypeScript SDK

The paywall, its messages, the account and activate_plan narration, what the widget's tools and the React web routes answer, and webhook verification are checked against the TypeScript SDK on every change by a shared conformance suite (conformance/). The API client is generated from the same spec as the TypeScript types (openapi/).

Versions

solvapay has its own version line, starting at 0.1.0. Its numbers don't follow the TypeScript packages: Python 0.3.0 and @solvapay/server 2.12.0 can behave the same. What the two share is the conformance suite (the version this package passes is pinned in conformance.lock) and the API spec.

Until 1.0.0, a minor release (0.x → 0.y) may change the API. Previews of the next release are published from the dev branch as <next>.devN:

pip install --pre solvapay

Metadata

Release files for solvapay 0.1.1.dev18

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for solvapay 0.1.1.dev18
File Size Uploaded Provenance Actions
solvapay-0.1.1.dev18.tar.gz 545.8 kB With provenance Details for solvapay-0.1.1.dev18.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for solvapay 0.1.1.dev18
File Interpreter ABI Platform Actions
solvapay-0.1.1.dev18-py3-none-any.whl Python 3 none any Details for solvapay-0.1.1.dev18-py3-none-any.whl

Total release size: 901.1 kB

Release files / solvapay-0.1.1.dev18.tar.gz

Download URL solvapay-0.1.1.dev18.tar.gz
Size 545.8 kB
Tags Source
SHA-256 checksum
How to use checksums
dc936a42baeafde3306bb7404381707d920426cf89f064df5cc7cbb587eb09ad
BLAKE2b-256 checksum
How to use checksums
36f9e305959a8ecff430dda28a2e901caa96aac6a16361c2eb76a033c0496fc0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / solvapay-0.1.1.dev18-py3-none-any.whl

Download URL solvapay-0.1.1.dev18-py3-none-any.whl
Size 355.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2bddb6880cfa7c824028e51965a65baf5bff0e24c76fae82f30e0a8902819884
BLAKE2b-256 checksum
How to use checksums
719065d332eb51f826336a80fdd526b8fb6cdb0fd1f47e31f77b7bcc027e73d3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for solvapay 0.1.1.dev18

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for solvapay-0.1.1.dev18.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page