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

# Examples

> Run the Python stock research example: a paid MCP server built with the Python SDK.

## Stock research MCP server

[`examples/python-stock-research-mcp`](https://github.com/solvapay/solvapay-sdk/tree/main/examples/python-stock-research-mcp) is a paid MCP server with six research tools. They join a public stock ranking feed with SEC company data. The output is educational market research, not financial advice.

It shows:

* `create_solvapay_mcp_server` with SolvaPay sign-in, served by uvicorn
* Six tools registered with `register_payable`, each billed as one unit whatever its upstream fan-out
* The built-in `account` and `activate_plan` tools and prompts, and the checkout widget in ChatGPT and Claude
* Closing the HTTP clients in the Starlette lifespan
* Tests that run against recorded market data and a mocked SolvaPay API, with no keys or network

| Tool | Upstream calls | Returns |
| - | - | - |
| `top_ranked_assets` | 1 | Five ranked rows, with the market regime, timestamp and disclaimer |
| `company_brief` | 1 | A 10-K extract, earnings and key filings for one ticker |
| `research_top_assets` | 6 | The ranked rows, each with a company brief |
| `verify_catalyst_claims` | 6 | Each catalyst checked against four quarters of earnings beats |
| `detect_stale_rankings` | 6 | Symbols with SEC filings newer than the ranking |
| `compare_symbols` | 1 + N | Side-by-side briefs for any tickers |

## Run it

**1. Install**

The example uses [uv](https://docs.astral.sh/uv/).

```bash theme={null}
git clone https://github.com/solvapay/solvapay-sdk.git
cd solvapay-sdk/examples/python-stock-research-mcp
uv sync
cp .env.example .env
```

**2. Fill in .env**

```bash theme={null}
SOLVAPAY_SECRET_KEY=sk_sandbox_...
SOLVAPAY_PRODUCT_REF=prd_...
PUBLIC_BASE_URL=https://<your-tunnel>.ngrok.app
MARKET_DATA=fixtures   # optional: recorded data, no live market calls
```

`PUBLIC_BASE_URL` must be the URL MCP clients use. See [Paid MCP server](https://docs.solvapay.com/sdks/python/guides/mcp.md) for why.

**3. Start a tunnel and the server**

```bash theme={null}
ngrok http 3030
uv run python main.py   # MCP endpoint: http://localhost:3030/mcp
```

Set `MCP_PORT` to use another port.

**4. Connect a client**

Add `https://<your-tunnel>.ngrok.app/mcp` to an MCP client as a remote server. The client opens SolvaPay's sign-in, then can call the tools.

## Run the tests

```bash theme={null}
uv run pytest
```

## TypeScript examples

For MCP servers, web checkout and webhooks in TypeScript, see the [TypeScript examples](https://docs.solvapay.com/sdks/typescript/guides/examples.md).


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