> ## 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 Go stock research MCP server, a paid MCP server built with the SolvaPay Go SDK.

## Stock research MCP server

[`examples/go-stock-research-mcp`](https://github.com/solvapay/solvapay-sdk/tree/main/examples/go-stock-research-mcp) is a paid MCP server with six research tools. It is a port of the [Python stock research example](https://docs.solvapay.com/sdks/python/guides/examples.md): same tools, same recorded market data, same environment, so you can compare the two servers call for call. It is educational market research, not financial advice.

It shows:

* `NewMCPServer` with customer sign-in through SolvaPay over OAuth.
* Six tools registered with `RegisterPayable`. Each call is checked against the customer's plan, and billed as one unit when it succeeds.
* SolvaPay's `account` and `activate_plan` tools, the checkout widget and its prompts, added by `NewMCPServer`.
* Tests that run the tools against a fake SolvaPay API and recorded data, with no keys or network.

| Tool | Upstream calls | Returns |
| - | - | - |
| `top_ranked_assets` | 1 | Five rows by `selection_score`, plus regime, timestamp and disclaimer |
| `company_brief` | 1 | 10-K extract, earnings and key filings for a ticker |
| `research_top_assets` | 6 | The ranked rows, each with a company brief |
| `verify_catalyst_claims` | 6 | Each catalyst against four quarters of EPS 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

### Prerequisites

* Go 1.26 or later
* A sandbox secret key and a product with an active plan. See [Installation](https://docs.solvapay.com/sdks/go/setup/installation.md#set-your-keys).
* [ngrok](https://ngrok.com) or another tunnel

**1. Configure**

From `examples/go-stock-research-mcp`, copy the template and fill it in:

```bash theme={null}
cp .env.example .env
```

```bash .env theme={null}
SOLVAPAY_SECRET_KEY=sk_sandbox_...
SOLVAPAY_PRODUCT_REF=prd_...
SOLVAPAY_API_BASE_URL=https://api.solvapay.com
PUBLIC_BASE_URL=https://<your-tunnel>.ngrok.app
MCP_PORT=3031
# MARKET_DATA=fixtures
```

`MARKET_DATA=fixtures` serves the recorded market data instead of calling the live APIs.

**2. Start a tunnel**

```bash theme={null}
ngrok http 3031
```

Put the tunnel's URL in `PUBLIC_BASE_URL`. It must be the URL clients use, because it is the OAuth issuer they see. See [Set PublicBaseURL](https://docs.solvapay.com/sdks/go/guides/mcp.md#set-publicbaseurl-to-the-url-clients-use).

**3. Start the server**

```bash theme={null}
go run .
```

The MCP endpoint is `http://localhost:3031/mcp`.

**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 with `go test ./...`.

## Use a published version of the SDK

The example's `go.mod` replaces the SDK with the repository's own `go/` module, so it always builds against the code next to it:

```text go.mod theme={null}
replace github.com/solvapay/solvapay-sdk/go => ../../go
```

To build it against a published release instead, for example after copying the example out of the repository, drop the `replace` and the placeholder `v0.0.0` requirement, then get a version:

```bash theme={null}
go mod edit -dropreplace github.com/solvapay/solvapay-sdk/go -droprequire github.com/solvapay/solvapay-sdk/go
go get github.com/solvapay/solvapay-sdk/go@latest
go mod tidy
```

Drop the requirement too: `v0.0.0` was never published, so `go get` fails while `go.mod` still names it.

## More examples

* [TypeScript SDK examples](https://docs.solvapay.com/sdks/typescript/guides/examples.md)
* [Python SDK examples](https://docs.solvapay.com/sdks/python/guides/examples.md)


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