algovoi-passport-sdk

A small SDK for building passport-aware agents on the AlgoVoi payment rails. It turns the two agent patterns into a few lines each: an agent that presents its Agent Passport on outbound calls, and a relying-party agent that guards its endpoints by verifying presented passports offline and enforcing a policy.

Built on algovoi-passport-client. Part of the AlgoVoi Payment Rails.

pip install algovoi-passport-sdk

Present your passport (agent side)

from algovoi_passport_sdk import PassportHolder

me = PassportHolder.from_env()            # $ALGOVOI_AGENT_PASSPORT, or from_file(path)

# attach it to an outbound call
headers  = me.apply({"Accept": "application/json"})   # adds X-Agent-Passport
metadata = me.a2a_metadata()                           # A2A message metadata

Guard your agent (relying-party side)

from algovoi_passport_sdk import PassportGuard, PassportPolicy

guard = PassportGuard(
    issuer_url="https://pay.issuer.com",              # resolves + caches key & CRL
    policy=PassportPolicy(required_scopes=("pay:invoice",), min_spend_microusd=1_000_000),
)

decision = guard.check(incoming_headers, required_scope="pay:invoice")
if decision:                                          # truthy only when admitted
    verdict = decision.verdict                        # agent_did, scopes, spend, ...
    ...                                               # grant the spend
else:
    reject(decision.reason)                           # e.g. "revoked: REVOKED"

guard.check(...) accepts a raw credential, an x402 headers mapping, an A2A metadata mapping, or a full A2A message; it pulls the passport out, verifies it offline (fail-closed), and applies the policy. Issuer key and revocation list are cached with a TTL (default 300s). For a strictly offline trust base, pin them instead of fetching:

guard = PassportGuard(issuer_keys={kid: pk_bytes}, crl={"revoked": [...]})

Policy

PassportPolicy fields, all optional:

• required_scopes: every scope must be present on the passport.
• min_spend_microusd: a floor; the passport's own limit must cover it (a passport with no stated limit is treated as unbounded).
• allowed_agents: an allowlist of agent_dids.
• require_revocation_check: default True; if the CRL cannot be confirmed the passport is denied as unverifiable, never admitted.

Per-call required_scope and min_spend on check(...) add to the policy.

FastAPI

from fastapi import FastAPI, Depends
from algovoi_passport_sdk import PassportGuard
from algovoi_passport_sdk.integrations import fastapi_passport_dependency

guard = PassportGuard(issuer_url="https://pay.issuer.com")
require_pay = fastapi_passport_dependency(guard, scope="pay:invoice")

app = FastAPI()

@app.post("/charge")
def charge(verdict = Depends(require_pay)):   # 403 unless a valid, in-scope passport is presented
    return {"agent": verdict.agent_did}

Install the extra with pip install 'algovoi-passport-sdk[fastapi]'.

License

Apache-2.0. (c) AlgoVoi. Keep the NOTICE attribution when you redistribute.