# Python client (/sdks/python/client)

The package supports Python 3.11 through 3.14. From an empty project, create a virtual environment first:

```bash
python -m venv .venv
. .venv/bin/activate
```

Configure one test merchant API key in the server process:

```bash
pip install recuut
export RECUUT_API_KEY="recuut_test_..."
```

Use `Recuut` in normal Python code and `AsyncRecuut` in asynchronous code. The API key selects the account and environment; client methods do not accept either as request input.

```python
from recuut import Recuut

with Recuut() as client:
    for resource in client.resources.list(max=100, page_size=25):
        print(resource.id, resource.name)
```

```python
from recuut import Recuut
from recuut.merchant_api import TransactionFilter, TransactionStatus

with Recuut() as client:
    for transaction in client.transactions.list(
        filter=TransactionFilter(status=TransactionStatus.SUCCEEDED),
        max=100,
        page_size=50,
    ):
        print(transaction.id, transaction.status, transaction.payment_request_id)
```

List methods return a typed first page. Iterate over it to load later pages
lazily, and use `max` to cap the total records yielded. The first page still
exposes `items`, `count`, `as_of`, and `next` when page boundaries matter.
Use a generated `filter` object for backend selection fields such as transaction
status. `page_size` and `order` are also sent to the backend; `max` is only an
SDK iteration limit and never changes the request's page size.

Every operation accepts `request_options={"timeout": 10.0, "headers": {...}}`.
Call the same operation through `with_raw_response`, for example
`client.resources.with_raw_response.list()`, to receive `status_code`,
`headers`, raw `content`, and typed `data` for a successful response.

`RECUUT_API_URL` defaults to `https://api.recuut.com`. Set it only when Recuut gives you a local or staging API URL. The examples print each object’s public ID and name or status. An HTTP `401` means the key is missing or invalid; a `403` means the authenticated key lacks the required capability.

The client is framework-neutral. Use it in workers, commands, and services that need records. It does not protect an HTTP endpoint by itself; use [FastAPI](/sdks/python/fastapi/), [Django](/sdks/python/django/), or the [Direct HTTP integration](/guides/http/) for that boundary.