Python SDK

Install and configure the Grantex Python SDK for delegated authorization of AI agents.

Installation

Published release: grantex==0.5.0. PyPI metadata, distribution contents, and a clean public-index install were verified before this page was updated.

python -m pip install grantex==0.5.0

The unpinned python -m pip install grantex command follows PyPI’s current release. Keep the exact version above in reproducible builds. See Release Status before upgrading.

Requirements

• Python 3.9 or higher
• httpx (sync HTTP client)
• PyJWT >= 2.8 with cryptography (for offline token verification)

All dependencies are installed automatically with the SDK.

Version 0.5.0 adds EVM payment responses and authenticated principal/agent reservation reconciliation for Base USDC custody. It retains bounded refresh lost-response recovery from 0.4.1 and the layered policy, exact approval, reload, and ES256 DPoP wallet clients from 0.4.0. It does not add an automatic x402 HTTP payment-and-retry wrapper; applications must implement their merchant HTTP flow. See Agent Wallet Governance.

Quick Start

from grantex import Grantex, AuthorizeParams

client = Grantex(api_key="gx_live_...")

# Register an agent
agent = client.agents.register(
    name="travel-assistant",
    scopes=["booking:read", "booking:write"],
    description="Books flights and hotels on behalf of users",
)

# Start the authorization flow
auth = client.authorize(AuthorizeParams(
    agent_id=agent.id,
    user_id="user_abc123",
    scopes=["booking:read", "booking:write"],
))

# Redirect the user to the consent URL
print(auth.consent_url)

client.close()

Configuration

The Grantex client accepts three keyword-only arguments:

Parameter	Type	Default	Description
api_key	str	GRANTEX_API_KEY env var	Your Grantex API key. Required.
base_url	str	https://api.grantex.dev	Override the API base URL (e.g. for self-hosted).
timeout	float	30.0	Request timeout in seconds.

API Key Resolution

The client resolves the API key in this order:

1. The api_key keyword argument passed to the constructor.
2. The GRANTEX_API_KEY environment variable.

If neither is set, a ValueError is raised.

import os

# Option 1: Pass directly
client = Grantex(api_key="gx_live_...")

# Option 2: Set environment variable
os.environ["GRANTEX_API_KEY"] = "gx_live_..."
client = Grantex()

# Option 3: Custom base URL for self-hosted deployments
client = Grantex(
    api_key="gx_live_...",
    base_url="https://grantex.internal.example.com",
    timeout=60.0,
)

Context Manager

The Grantex client implements the context manager protocol. Using with ensures the underlying HTTP connection pool is properly closed when you are done:

from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    agents = client.agents.list()
    print(f"Total agents: {len(agents.agents)}")
# Connection pool is closed automatically

This is equivalent to calling client.close() manually:

client = Grantex(api_key="gx_live_...")
try:
    agents = client.agents.list()
finally:
    client.close()

Resource Clients

The Grantex client exposes the following resource clients as attributes:

Attribute	Type	Description
agents	AgentsClient	Register, list, update, and delete agents
grants	GrantsClient	Get, list, revoke, delegate, and verify grants
tokens	TokensClient	Exchange, verify, and revoke tokens
audit	AuditClient	Log, list, and retrieve audit entries
webhooks	WebhooksClient	Create, list, and delete webhook endpoints
billing	BillingClient	Subscription status, checkout, and portal
policies	PoliciesClient	Create, list, update, and delete policies
compliance	ComplianceClient	Summaries, exports, and evidence packs
anomalies	AnomaliesClient	Detect, list, and acknowledge anomalies
scim	ScimClient	SCIM 2.0 user provisioning and tokens
sso	SsoClient	OIDC SSO configuration and login
passports	PassportsClient	Issue, list, get, and revoke MPP agent passports
vault	VaultClient	Store, list, get, delete, and exchange service credentials
budgets	BudgetsClient	Per-grant spending budgets and transactions
events	EventsClient	SSE event streaming
usage	UsageClient	Usage metering and history
domains	DomainsClient	Custom domain verification
webauthn	WebAuthnClient	FIDO2/WebAuthn passkey management
credentials	CredentialsClient	Verifiable Credentials and SD-JWT
commerce	CommerceClient	Commerce V1/OACP merchant discovery, catalog, checkout, webhooks, and ops
dpdp	DpdpClient	DPDP Act 2023 compliance — consent, grievances, erasure, exports

Standalone Functions

In addition to the client, the SDK exports standalone utility functions:

from grantex import (
    verify_grant_token,      # Offline JWT verification via JWKS
    generate_pkce,           # Generate PKCE code_verifier + code_challenge
    verify_webhook_signature, # Verify webhook payload signatures
)

Data Model Conventions

All response types are frozen dataclasses with snake_case field names. Lists are returned as Python tuple objects for immutability.

agent = client.agents.get("agt_abc123")

# Fields use snake_case
print(agent.developer_id)
print(agent.created_at)

# Scopes are a tuple
print(agent.scopes)  # ('booking:read', 'booking:write')

Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: [e-mail] or [e-mail].