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

# API client

> Call the SolvaPay API from Python with AsyncApiClient or ApiClient, and handle SolvaPayError.

`AsyncApiClient` covers every SolvaPay SDK API operation. Its methods are generated from the same API spec as the TypeScript SDK's types. `ApiClient` is its blocking twin, with the same methods.

## Make a call

```python theme={null}
import asyncio
import os

from solvapay import AsyncApiClient


async def main() -> None:
    async with AsyncApiClient(api_key=os.environ["SOLVAPAY_SECRET_KEY"]) as api:
        customer = await api.get_customer_by_query(external_ref="user_123")
        balance = await api.get_customer_balance(reference=customer.reference)
        purchases = await api.get_purchases_for_customer(customer_ref=customer.reference)

        print(customer.email, balance.credits)
        for purchase in purchases.purchases or []:
            print(purchase.reference, purchase.status, purchase.plan_ref)


asyncio.run(main())
```

* Methods take keyword arguments only. Path and query parameters are snake\_case (`external_ref`, `customer_ref`).
* A request body is a dict with the API's camelCase keys, or the matching pydantic model, such as `models.CreateCustomerRequest` (`from solvapay import models`).
* Responses are pydantic models with snake\_case attributes.
* Use the client as a context manager, or call `aclose()` (`close()` on `ApiClient`).

If you already use `create_solvapay()`, its client is `solvapay.api`.

## Common operations

| Task | Method |
| - | - |
| Find a customer by your user id or email | `get_customer_by_query(external_ref=..., email=...)` |
| Get a customer | `get_customer(reference=...)` |
| Create a customer | `create_customer(body={...})` |
| Get a credit balance | `get_customer_balance(reference=...)` |
| Grant credits | `grant_credits(reference=..., body={...}, idempotency_key=...)` |
| List a customer's purchases | `get_purchases_for_customer(customer_ref=...)` |
| Cancel or reactivate a purchase | `cancel_purchase(purchase_ref=..., body={...})`, `reactivate_purchase(purchase_ref=...)` |
| Record a usage event | `record_meter_event(body={...})` |
| Check a customer's limits | `check_limits(body={...})` |
| Create a checkout session | `create_checkout_session(body={...})` |

For every operation and its fields, see the [API reference](https://docs.solvapay.com/api-reference/authentication.md).

### Create a customer

```python theme={null}
import os

from solvapay import ApiClient

with ApiClient(api_key=os.environ["SOLVAPAY_SECRET_KEY"]) as api:
    customer = api.create_customer(body={"email": "ada@example.com", "externalRef": "user_123"})
    print(customer.reference)
```

### Record a usage event

```python theme={null}
import os

from solvapay import ApiClient

with ApiClient(api_key=os.environ["SOLVAPAY_SECRET_KEY"]) as api:
    api.record_meter_event(
        body={
            "customerRef": "cus_3c4d5e6f7g8h",
            "meterName": "requests",
            "productRef": os.environ["SOLVAPAY_PRODUCT_REF"],
            "value": 1,
        }
    )
```

`@solvapay.payable()` and paid MCP tools record usage for you. Record it yourself only for usage that happens outside them. See [usage events](https://docs.solvapay.com/sdks/typescript/guides/usage-events.md) for how meters bill.

## Handle errors

Every error is a `SolvaPayError`. Branch on `code` and `status`, never on the message, which may change.

```python theme={null}
import os

from solvapay import ApiClient, SolvaPayError, models


def find_customer(api: ApiClient, user_id: str) -> models.CustomerResponse | None:
    try:
        return api.get_customer_by_query(external_ref=user_id)
    except SolvaPayError as error:
        if error.status == 404:
            return None
        raise


with ApiClient(api_key=os.environ["SOLVAPAY_SECRET_KEY"]) as api:
    customer = find_customer(api, "user_missing")
```

| Attribute | What it holds |
| - | - |
| `code` | A stable identifier: the API's own code when it sends one, else `http_<status>`. SDK errors use codes such as `network_error`, `invalid_response`, `non_json_response`, `missing_secret` and `invalid_argument`. |
| `status` | The HTTP status, when the error came from the API. `None` otherwise. |
| `body` | The API's error body, when there is one. |

The client retries reads, and writes with an idempotency key, on `429`, `502`, `503`, `504` and network errors (`max_retries=2` by default). Other writes are sent once.

## Next steps

* [Webhooks](https://docs.solvapay.com/sdks/python/guides/webhooks.md): verify the events SolvaPay sends you.
* The TypeScript equivalent is [purchase management](https://docs.solvapay.com/sdks/typescript/guides/purchase-management.md).


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