loomal-sdk 0.4.1

Official Python SDK for the Loomal API — identity, mail, vault, calendar, and Loomal Pay (x402 paywall) for AI agents

Loomal Python SDK

The official Python SDK for the Loomal API -- identity, mail, vault, calendar, and Loomal Pay for AI agents.

Installation

pip install loomal-sdk          # core SDK
pip install loomal-sdk[fastapi] # core SDK + FastAPI paywall middleware

The distribution is loomal-sdk on PyPI, but the import name is loomal.

Loomal Pay paywall (FastAPI)

Charge USDC per call on top of any FastAPI route. The dependency does the two-call x402 flow against api.loomal.ai for you.

from fastapi import FastAPI, Depends
from loomal.paywall import require_payment

app = FastAPI()

@app.get(
    "/api/search",
    dependencies=[Depends(require_payment(amount="0.01"))],
)
def search():
    return {"results": [...]}

The dependency reads your seller API key from LOOMAL_API_KEY (or SELLER_LOOMAL_API_KEY) by default. Pass api_key= to override.

Settled payments return a signed receipt and an on-chain USDC transfer on Base. See the full payments guide for the protocol shape and webhook configuration.

For non-FastAPI frameworks, the lower-level helpers are exposed too:

from loomal.paywall import build_challenge_async, verify_and_settle_async, PaywallConfig, PaywallRouteOptions

Webhook signature verification

Loomal sends X-Loomal-Signature: sha256=<hex> (HMAC-SHA256 of the raw request body) along with X-Loomal-Event / X-Loomal-Idempotency-Key. The signing secret is generated by Loomal when you register an endpoint in the Console and shown to you exactly once.

import os
from fastapi import FastAPI, HTTPException, Request
from loomal.webhook import verify_webhook

app = FastAPI()

@app.post("/webhooks/loomal")
async def webhook(request: Request):
    raw = await request.body()
    ok = verify_webhook(
        raw,
        request.headers.get("x-loomal-signature"),
        os.environ["LOOMAL_WEBHOOK_SECRET"],
    )
    if not ok:
        raise HTTPException(400, "invalid signature")
    # de-dupe on x-loomal-idempotency-key, then handle the event.
    # Today the only event type is `payment.received`.

Quick start

from loomal import Loomal

client = Loomal(api_key="loid-...")

me = client.identity.whoami()
print(me.email)

client.mail.send(
    to=["[e-mail]"],
    subject="Hello from my agent",
    text="Sent via the Loomal Python SDK.",
)

Async usage

from loomal import AsyncLoomal

async with AsyncLoomal(api_key="loid-...") as client:
    me = await client.identity.whoami()
    await client.mail.send(
        to=["[e-mail]"],
        subject="Hello",
        text="Sent asynchronously.",
    )

Authentication

Pass your API key directly, or set the LOOMAL_API_KEY environment variable:

# Explicit
client = Loomal(api_key="loid-...")

# From environment
import os
os.environ["LOOMAL_API_KEY"] = "loid-..."
client = Loomal()

Both Loomal and AsyncLoomal support context managers for automatic resource cleanup:

with Loomal() as client:
    me = client.identity.whoami()

Usage

Identity

me = client.identity.whoami()
print(me.email, me.display_name)

Vault

The vault is password-manager-style encrypted secret storage (AES-256-GCM at rest). Use client.vault.store() for arbitrary types, or the typed helpers below.

# Simple API key
client.vault.store_api_key("stripe", "sk_live_...")

# OAuth-style client credentials (client id + secret)
client.vault.store_api_key("twitter", {
    "clientId": "abc123",
    "secret": "def456",
})

# Credit card (encrypted at rest — this is a secret vault, not a payment processor)
client.vault.store_card("personal-visa", {
    "cardholder": "Jane Doe",
    "number": "4242 4242 4242 4242",
    "expMonth": "12",
    "expYear": "2029",
    "cvc": "123",
    "zip": "94103",
}, metadata={"brand": "Visa"})

# Shipping address
client.vault.store_shipping_address("home", {
    "name": "Autonomous Agent",
    "line1": "1 Demo Way",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
})

Supported credential types: LOGIN, API_KEY, OAUTH, TOTP, SSH_KEY, DATABASE, SMTP, AWS, CERTIFICATE, CARD, SHIPPING_ADDRESS, CUSTOM.

More resources

The SDK also exposes client.mail, client.calendar, client.logs, and client.did. See the full reference at docs.loomal.ai for request/response shapes, pagination, and end-to-end examples.

Error handling

All API errors raise LoomalError with structured fields:

from loomal import LoomalError

try:
    client.mail.send(to=["[e-mail]"], subject="Hi", text="Hello")
except LoomalError as e:
    print(e.status)   # HTTP status code
    print(e.code)     # Error code string
    print(e.message)  # Human-readable message

Types

The SDK returns typed dataclasses, not raw dictionaries. API responses are automatically converted from camelCase to snake_case.

Type	Description
IdentityResponse	Agent identity details
MessageResponse	Email message
ThreadResponse	Thread summary
ThreadDetailResponse	Thread with messages
CredentialMetadata	Vault credential metadata
CredentialWithData	Credential with decrypted data
ActivityLog	Single activity log entry
LogsStats	Aggregated log statistics
TotpResponse	Generated TOTP code
DidDocument	DID document

Note: The from field in message responses is exposed as from_addrs since from is a reserved keyword in Python.

Requirements

• Python 3.9+
• httpx (installed automatically)

Links

• Documentation
• Console
• Website
• PyPI

License

MIT