> ## 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.

# Installation

> Install the Python SDK, choose its extras, and set the environment variables it reads.

## Prerequisites

* Python 3.10 or later
* A SolvaPay account with a product and at least one plan

## Install the package

```bash theme={null}
pip install solvapay
```

The base package gives you paid functions, the API client and webhook verification. Add an extra for the other features:

| Install | Adds |
| - | - |
| `pip install 'solvapay[mcp]'` | Paid MCP servers, on the official MCP Python SDK (`mcp`) and Starlette |
| `pip install 'solvapay[agents,mcp]'` | Agent payments (preview). `agents` adds JWT verification; the agent MCP route also needs `mcp` |

## Set up with the CLI

In an existing project, `npx solvapay init` signs you in, writes `SOLVAPAY_SECRET_KEY` and `SOLVAPAY_PRODUCT_REF` to `.env`, and adds `solvapay` pinned exactly with uv or Poetry (for pip it prints the install command). It needs Node.js 22 or later to run. The SDK reads environment variables, not `.env`, so load `.env` when your app starts (`python-dotenv`) or export the variables.

```bash theme={null}
npx solvapay init --features mcp
```

For a new paid MCP server, scaffold one instead:

```bash theme={null}
npm create solvapay@latest my-mcp-server -- --type mcp --language python
```

`npx solvapay doctor` checks that the SDK is the newest release and prints the upgrade command. See [CLI setup](https://docs.solvapay.com/sdks/typescript/setup/cli.md) for the flags.

## Set environment variables

| Variable | Required | What it is |
| - | - | - |
| `SOLVAPAY_SECRET_KEY` | Yes | Your secret key. Use a sandbox key (`sk_sandbox_...`) while you build |
| `SOLVAPAY_PRODUCT_REF` | For paid calls | The product paid calls bill against (`prd_...`) |
| `SOLVAPAY_API_BASE_URL` | No | Defaults to `https://api.solvapay.com` |

To get the values:

1. In SolvaPay Console, go to **Developers** > **API Keys** and copy a sandbox secret key into `SOLVAPAY_SECRET_KEY`.
2. Open your product and copy its reference into `SOLVAPAY_PRODUCT_REF`.

```bash theme={null}
export SOLVAPAY_SECRET_KEY=sk_sandbox_...
export SOLVAPAY_PRODUCT_REF=prd_...
```

`create_solvapay()` reads these variables. It raises `SolvaPayError` with code `missing_secret` when there is no secret key. A paid function or MCP tool raises `missing_product` when it's registered without a product.

## Configure in code

Pass the same settings as arguments to override the environment:

```python theme={null}
import os

from solvapay import create_solvapay

solvapay = create_solvapay(
    api_key=os.environ["SOLVAPAY_SECRET_KEY"],
    product_ref="prd_3c4d5e6f",
    api_base_url="https://api.solvapay.com",
    timeout=30.0,
    max_retries=2,
)
```

`max_retries` applies only to requests that are safe to send twice: reads, and writes with an idempotency key. It retries on `429`, `502`, `503`, `504` and network errors.

## Versions

The Python SDK has its own version line, starting at 0.1.0. Its numbers don't follow the TypeScript packages. What the two share is the API spec and the conformance suite, so a Python release behaves the same as the TypeScript release that passes the same suite version.

Until 1.0.0, a minor release (0.x to 0.y) may change the API. Pin a minor version in production:

```bash theme={null}
pip install 'solvapay>=0.1,<0.2'
```

## Next steps

* [Quick start](https://docs.solvapay.com/sdks/python/setup/quick-start.md): make a function paid.
* [Paid MCP server](https://docs.solvapay.com/sdks/python/guides/mcp.md): charge for MCP tools.


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