> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solvapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> SolvaPay quick facts:
> - REST API base URL: https://api.solvapay.com. All public endpoints are under /v1/sdk/ (for example GET https://api.solvapay.com/v1/sdk/products). Sandbox and production share this URL.
> - Auth: send a secret key as `Authorization: Bearer <secret key>` (the REST API also accepts `X-API-Key: <secret key>`).
> - Secret key prefixes: `sk_sandbox_` (sandbox, test payments) and `sk_live_` (production). The prefix selects the environment.
> - Get keys in SolvaPay Console (https://app.solvapay.com) > Developers > API Keys. Use a sandbox key while building.
> - Admin MCP Server: https://mcp.solvapay.com/mcp (Streamable HTTP). Connect with OAuth: add the URL and sign in with the SolvaPay account; no API key needed. OAuth sessions use the live account; for sandbox data or headless clients, send `Authorization: Bearer <secret key>` (X-API-Key is ignored).
> - Install the SolvaPay agent skills: `npx skills add https://solvapay.com` (skills CLI older than 1.5.7: `npx skills add solvapay/skills`).
> - TypeScript SDK setup: `npx solvapay@latest init`. The SDK reads SOLVAPAY_SECRET_KEY and defaults to https://api.solvapay.com.
> - Plans take an options[] array (billingCycle, charge, limit, ...). Retired plan fields price, freeUnits and billingCycle are rejected.
> - Step-by-step from zero to a first paid call: Managed MCP https://docs.solvapay.com/build/managed-mcp.md, TypeScript SDK https://docs.solvapay.com/build/typescript-sdk.md, agent skill https://docs.solvapay.com/build/agent-skill.md.
> - Details: https://docs.solvapay.com/api-reference/authentication.md. OpenAPI spec: https://docs.solvapay.com/api-reference/openapi.json.

# Quick start

> Make a Python function paid with @solvapay.payable() and serve it from a Starlette route.

This guide makes an async function paid and serves it from a web route. Each call is checked against the customer's plan. An allowed call runs and is recorded as usage. A call that isn't allowed raises `PaywallError`, and the route answers `402` with a checkout link.

## Prerequisites

* The Python SDK installed, with `SOLVAPAY_SECRET_KEY` and `SOLVAPAY_PRODUCT_REF` set. See [Installation](https://docs.solvapay.com/sdks/python/setup/installation.md).
* Starlette and uvicorn: `pip install starlette uvicorn`. FastAPI works the same way.

## Make a function paid

**1. Write the app**

Save this as `app.py`:

```python theme={null}
from solvapay import PaywallError, create_solvapay
from starlette.applications import Starlette
from starlette.requests import Request
from starlette.responses import JSONResponse
from starlette.routing import Route

solvapay = create_solvapay()  # reads SOLVAPAY_SECRET_KEY and SOLVAPAY_PRODUCT_REF


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


async def summarise_route(request: Request) -> JSONResponse:
    body = await request.json()
    user_id = request.headers["x-user-id"]  # replace with your signed-in user's id
    try:
        summary = await summarise(body["text"], customer_ref=user_id)
    except PaywallError as error:
        return JSONResponse(
            {"message": error.gate["message"], "checkoutUrl": error.gate["checkoutUrl"]},
            status_code=402,
        )
    return JSONResponse({"summary": summary})


app = Starlette(routes=[Route("/summarise", summarise_route, methods=["POST"])])
```

**2. Run it**

```bash theme={null}
uvicorn app:app --port 8000
```

**3. Call it**

```bash theme={null}
curl -X POST http://localhost:8000/summarise \
  -H 'content-type: application/json' \
  -H 'x-user-id: user_123' \
  -d '{"text": "Quarterly revenue grew 12% on subscription sales."}'
```

While the customer is within their plan, you get the summary. Once they aren't, you get a `402`:

```json theme={null}
{
  "message": "You don't have an active plan for this tool. [Open checkout](https://...) to pick a plan (expires in 15 minutes), or call the `account` tool with view: 'checkout'.",
  "checkoutUrl": "https://..."
}
```

> [!WARNING]
>
> The `x-user-id` header keeps the example short. In your app, take the customer from your own session or token, never from a value the caller can set.

## How `payable()` works

* `customer_ref` is your own user id. It must be passed as a keyword argument. SolvaPay creates the customer on first use and links it to that id. A call without `customer_ref` raises `SolvaPayError` with code `identity_required`.
* `payable()` wraps async functions only.
* The product comes from `SOLVAPAY_PRODUCT_REF`, or `@solvapay.payable(product="prd_...")`. It's resolved when the decorator runs, so set the variable before you import the module.
* Use `meter="..."` to bill a meter other than the default `requests`, and `customer_ref_arg="user_id"` when your function names the customer argument differently.
* If the function raises, the call is recorded as failed and the exception reaches you unchanged.

## Show the paywall

`PaywallError.gate` is a dict with the API's camelCase keys. The fields you'll use most:

| Key | What it holds |
| - | - |
| `kind` | `payment_required` or `activation_required` (also `PaywallError.code`) |
| `message` | A sentence for the customer, with the checkout link in Markdown |
| `checkoutUrl` | The checkout link. Can be empty, so check it before you redirect |
| `reason` | Why the call was gated, such as `upgrade_required`, `topup_required` or `limit_reached` |
| `plans` | The plans the customer can pick from, when the API returned them |

> [!NOTE]
>
> The message is written for MCP clients and names the `account` tool. In a web app, show your own copy and link to `checkoutUrl`.

## Next steps

* [Paid MCP server](https://docs.solvapay.com/sdks/python/guides/mcp.md): charge for MCP tools.
* [Webhooks](https://docs.solvapay.com/sdks/python/guides/webhooks.md): react to purchases.
* The TypeScript equivalent is the [quick start](https://docs.solvapay.com/sdks/typescript/setup/quick-start.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.