> ## 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 Go function paid and serve it from a net/http handler.

## Prerequisites

* The Go SDK installed and `SOLVAPAY_SECRET_KEY` and `SOLVAPAY_PRODUCT_REF` set. See [Installation](https://docs.solvapay.com/sdks/go/setup/installation.md).
* A product with at least one plan in SolvaPay Console. Use sandbox while you build.

## 1) Make a function paid

`Payable` wraps a function so that each call is decided by the paywall first:

* If the customer's plan allows the call, your function runs, and the call is recorded as usage when it returns.
* If it doesn't, your function does not run, and the call returns a `*PaywallError`. Its `Gate` says what the customer has to do and where to pay.

This server sells a report at `POST /reports`:

```go main.go theme={null}
package main

import (
	"context"
	"encoding/json"
	"errors"
	"log"
	"net/http"

	solvapay "github.com/solvapay/solvapay-sdk/go"
)

type reportArgs struct {
	Topic string `json:"topic"`
}

type report struct {
	Topic   string `json:"topic"`
	Summary string `json:"summary"`
}

func main() {
	// SOLVAPAY_SECRET_KEY and SOLVAPAY_API_BASE_URL come from the environment.
	client, err := solvapay.NewClient(solvapay.Config{})
	if err != nil {
		log.Fatal(err)
	}
	// The product comes from SOLVAPAY_PRODUCT_REF.
	paywall, err := solvapay.NewPaywall(client, solvapay.PaywallOptions{})
	if err != nil {
		log.Fatal(err)
	}

	writeReport, err := solvapay.Payable(paywall, solvapay.PayableOptions{ToolName: "write_report"},
		func(ctx context.Context, call solvapay.PaidCall[reportArgs]) (report, error) {
			return report{Topic: call.Args.Topic, Summary: "..."}, nil
		})
	if err != nil {
		log.Fatal(err)
	}

	http.HandleFunc("POST /reports", func(w http.ResponseWriter, r *http.Request) {
		var args reportArgs
		if err := json.NewDecoder(r.Body).Decode(&args); err != nil {
			http.Error(w, err.Error(), http.StatusBadRequest)
			return
		}
		// Your own user id. The paywall finds or creates the SolvaPay customer for it.
		userID := r.Header.Get("X-User-ID")

		result, err := writeReport(r.Context(), solvapay.PaidCall[reportArgs]{CustomerRef: userID, Args: args})
		var gated *solvapay.PaywallError
		switch {
		case errors.As(err, &gated):
			// gated.Gate["message"] says what to do; gated.Gate["checkoutUrl"] is where to pay.
			writeJSON(w, http.StatusPaymentRequired, gated.Gate)
		case err != nil:
			http.Error(w, err.Error(), http.StatusInternalServerError)
		default:
			writeJSON(w, http.StatusOK, result)
		}
	})
	log.Fatal(http.ListenAndServe(":8080", nil))
}

func writeJSON(w http.ResponseWriter, status int, body any) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)
	json.NewEncoder(w).Encode(body)
}
```

`PaidCall.CustomerRef` says who is calling. Pass your own user id: the paywall finds the SolvaPay customer with that `externalRef`, or creates one on first use. You can also pass a SolvaPay customer reference (`cus_…`) directly. An empty `CustomerRef` fails with the code `identity_required`.

## 2) Run it

```bash theme={null}
go run .
curl -X POST localhost:8080/reports -H 'X-User-ID: user_42' -d '{"topic":"chips"}'
```

A customer without a plan gets `402 Payment Required` and the gate:

```json theme={null}
{
  "kind": "payment_required",
  "reason": "upgrade_required",
  "checkoutUrl": "https://...",
  "message": "You don't have an active plan for this tool. [Open checkout](https://...) to pick a plan (expires in 15 minutes), ...",
  "product": "prd_..."
}
```

Show `message` to the customer, or send them to `checkoutUrl`. Once they have a plan, the same request returns the report.

> [!NOTE]
>
> The gate's `message` is the same text the TypeScript and MCP paywalls use, so it also mentions the `account` MCP tool. On a plain HTTP API, show `checkoutUrl` instead if that line doesn't fit.

## 3) Handle the other errors

An error your function returns comes back unchanged, and the call is recorded as failed. Every error from the SDK itself is a `*solvapay.Error` (a `*PaywallError` unwraps to one, with the gate's kind as its code). Branch on `Code` or `Status`, never on `Message`. See [API client](https://docs.solvapay.com/sdks/go/guides/api-client.md#handle-errors).

## Options

`PayableOptions` says what a paid function is for:

| Field | Meaning |
| - | - |
| `Product` | The product reference. Empty uses the paywall's product (`SOLVAPAY_PRODUCT_REF`). |
| `Meter` | The meter a call counts against. Empty uses `requests`. |
| `FreeLimit` | A free allowance: `Cap` calls per `Scope` (`"rolling_window"` with `WindowDays`, or `"lifetime"`) before a plan is required. |
| `ToolName` | Recorded with every usage event. |

`Payable` checks the product and the free allowance when you call it, so a misconfigured paid function fails at startup, not on its first call.

## Next steps

* [MCP server](https://docs.solvapay.com/sdks/go/guides/mcp.md): sell the same function as an MCP tool, with sign-in and checkout built in.
* [Webhooks](https://docs.solvapay.com/sdks/go/guides/webhooks.md): react to purchases and payments.
* The TypeScript equivalent of this page: [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.