Documentation

Python SDK

The Python SDK mirrors the TypeScript client and depends only on the standard library - drop it into any service or script with no extra dependencies.

Install

terminal

pip install sgovr-sdk

Pre-release

The Python SDK is not yet published to PyPI. The install command below shows the intended form once the first release lands; until then, use the SDK directly from the Sgovr source. Package names may change before 1.0.

Initialize the client

Construct a SgovrClient. It reads its endpoints from the environment, or you can pass base URLs to target your own deployment.

client.py

from sgovr_sdk import SgovrClient
 
# Reads SGOVR_GATEWAY_URL / SGOVR_REGISTRY_URL from the environment,
# or pass base URLs explicitly to target your own deployment.
client = SgovrClient()

Discover providers

Pass an intent and get back ranked, verified providers and the actions they expose.

discover.py

# Natural-language intent -> ranked, verified providers
results = client.discover("book a hotel room in Lisbon")
hit = results[0]
print(hit["providerId"], hit["action"]["name"])  # prov_lux_hotels book_room

Mint a mandate

A mandate declares the scopes an agent may use, a spend cap in minor units, and a currency. The helper below is for local development.

mandate.py

from sgovr_sdk import mint_dev_mandate
 
# Dev helper only. In production the principal issues the mandate;
# the agent never mints its own. The signing secret defaults to the
# gateway's dev secret ("dev-secret-change-me"); pass secret=... to override.
token = mint_dev_mandate(
    "agent_demo",
    ["booking:write", "payments:charge", "payments:refund"],
    spend_cap_minor=50_000,  # EUR 500.00, in minor units
    currency="EUR",
)

Spend caps are hard

The spend_cap_minor is enforced by reservation: a transactional call that would exceed it is rejected before the provider is ever called.

Invoke a free action

Actions with sideEffects: "none" need only a valid mandate with the right scopes.

search.py

search = client.invoke(
    "prov_lux_hotels",
    "search_rooms",
    {"city": "Lisbon", "checkIn": "2026-07-01", "checkOut": "2026-07-03", "maxPrice": 200},
    token,
)
print(search.status, search.body)

Invoke a transactional action

Transactional actions require an idempotency_key and an amount_minor - the spend you authorize, reserved against the cap and captured on success.

book.py

book = client.invoke(
    "prov_lux_hotels",
    "book_room",
    {"roomId": "room_101", "checkIn": "2026-07-01",
     "checkOut": "2026-07-03", "guestName": "Ada Lovelace"},
    token,
    idempotency_key="demo-booking-001",  # de-dupes retries
    amount_minor=29_800,                 # spend authorized, reserved against the cap
)
 
print(book.transaction_id, book.captured_minor, book.fee_minor)

transaction_id - the settled transaction, used for refunds.
captured_minor - the amount actually charged; the rest is released.
fee_minor - Sgovr's take-rate portion.

Idempotent replay

A retry with the same key returns the original result rather than charging again.

replay.py

# Re-invoking with the same idempotency key returns the original
# result instead of booking twice.
again = client.invoke(
    "prov_lux_hotels", "book_room", {...},
    token, idempotency_key="demo-booking-001", amount_minor=29_800,
)
print(again.idempotent_replay)  # True

Refund a transaction

Refunds honour the provider's declared refund policy and require the payments:refund scope.

refund.py

refund = client.refund(book.transaction_id, token)
print(refund.status, refund.body)

PreviousTypeScript SDK NextMCP server