Python SDK

Installation

The SDK is published on PyPI as cred-protocol and needs Python 3.10 or later.

# Core client
pip install cred-protocol

# With FastAPI integration
pip install "cred-protocol[fastapi]"

# With Know Your Agent hooks for x402 sellers
pip install "cred-protocol[x402]"

Quote the package name when it has an extra in brackets: zsh, the default shell on macOS, otherwise treats [...] as a filename pattern and fails with no matches found. The same commands work with uv (uv add "cred-protocol[x402]") and Poetry (poetry add "cred-protocol[x402]").

Quick Start

import asyncio
from cred_protocol import CredClient

async def main():
    async with CredClient(api_key="cred_sk_...") as cred:
        result = await cred.evaluate(
            wallet_address="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
            policy="standard",
        )

        print(result.trust_score)   # 75
        print(result.trust_tier)    # TrustTier.VERIFIED
        print(result.all_passed)    # True

asyncio.run(main())

Evaluate Options

Using a Policy Template

result = await cred.evaluate(
    wallet_address="0x...",
    policy="standard",
)

Using Custom Gates

result = await cred.evaluate(
    wallet_address="0x...",
    gates=["human", "verified", "established"],
    operator="WEIGHTED",
    weights={"human": 0.4, "verified": 0.35, "established": 0.25},
    composite_threshold=60,
)

With Dynamic Pricing

result = await cred.evaluate(
    wallet_address="0x...",
    policy="reputation",
    include_pricing=True,
    base_price_usdc=0.01,
)

print(result.price_multiplier)      # 0.25
print(result.suggested_price_usdc)  # 0.0025

TrustResult Fields

Field	Type	Description
`wallet_address`	`str`	The evaluated wallet
`trust_score`	`int`	0–100 composite score
`trust_tier`	`TrustTier`	`TRUSTED`, `VERIFIED`, `LIMITED`, `UNTRUSTED`, `BLOCKED`
`confidence`	`float`	0.0–1.0 data confidence
`all_passed`	`bool`	Whether all gates passed
`gate_results`	`list[GateScoreBreakdown]`	Per-gate breakdown
`price_multiplier`	`float \| None`	Dynamic pricing multiplier
`suggested_price_usdc`	`float \| None`	Computed price
`reputation`	`WalletReputation \| None`	Behavioral history
`cached`	`bool`	Whether this was a cache hit
`request_id`	`str`	Unique request ID
`challenge`	`dict \| None`	402 challenge body (if gates failed)

Error Handling

from cred_protocol import CredClient, CredAPIError

try:
    result = await cred.evaluate(wallet_address="0x...", policy="standard")
except CredAPIError as e:
    print(e.status)  # 401, 429, etc.
    print(e.body)    # Error details

FastAPI Integration

The require_trust() dependency gates endpoints with a single line:

import os
from fastapi import Depends, FastAPI
from cred_protocol.fastapi import require_trust
from cred_protocol import TrustResult

app = FastAPI()

@app.get("/resource")
async def get_resource(
    trust: TrustResult = Depends(require_trust(
        api_key=os.environ["CRED_API_KEY"],
        policy="standard",
    )),
):
    return {
        "data": "...",
        "wallet": trust.wallet_address,
        "score": trust.trust_score,
        "tier": trust.trust_tier.value,
    }

FastAPI Configuration

require_trust(
    api_key="cred_sk_...",           # Or set CRED_API_KEY env var
    base_url="https://...",          # Defaults to production
    policy="standard",               # Named template
    # gates=["human", "verified"],   # Or custom gates
    # operator="AND",
    include_pricing=False,
    base_price_usdc=None,
    on_fail="deny",                  # "deny" (403), "challenge" (402), "pass"
)

Wallet Extraction

The FastAPI dependency checks (in order):

X-Wallet-Address request header
?wallet= query parameter

Override with a custom extractor:

from fastapi import Request
from cred_protocol.fastapi import CredTrustDependency

trust_dep = CredTrustDependency(
    api_key=os.environ["CRED_API_KEY"],
    policy="standard",
    extract_wallet=lambda req: req.headers.get("x-agent-wallet"),
)

@app.get("/resource")
async def get_resource(trust: TrustResult = Depends(trust_dep)):
    ...

Failure Responses

Response	When
`400`	No wallet address found on the request
`402`	Gates failed, `on_fail="challenge"`
`403`	Gates failed with `on_fail="deny"`, or wallet is `blocked`
`429`	Cred API rate limit exceeded
`502`	Upstream gate provider error

Screen x402 payers (Know Your Agent)

If you sell over x402 with the Python x402 package (v2), one call screens every paying agent with Know Your Agent before its payment settles:

pip install "cred-protocol[x402]"

import os
from x402.server import x402ResourceServer
from cred_protocol import register_cred_kya

server = x402ResourceServer(facilitator_client).register("eip155:8453", ExactEvmServerScheme())
register_cred_kya(server, api_key=os.environ["CRED_API_KEY"])

It works with both x402ResourceServer (async hooks) and x402ResourceServerSync (blocking hooks), and picks the right one for the server it is given.

Verify, then screen. The facilitator verifies the payment first, so only a payer who really signed it is looked up.
Refusal. If your policy refuses the payer, the payment is aborted before settlement and no funds move. The payer gets a 402 whose error is payer_sanctioned, payer_needs_review, payer_not_registered_agent or payer_screening_unavailable. The TypeScript page explains when each is sent.
Every payment flow. The default authorization flow is screened after verify. The upfront and escrow flows, which settle without a verify step, are screened just before that early settle.

Where the check runs

The hooks register_cred_kya installs run between the facilitator’s verify and settle. Refusals never settle, so no funds move.

Policy

from cred_protocol import CacheTtl, CredKyaPolicy, register_cred_kya

register_cred_kya(
    server,
    api_key=os.environ["CRED_API_KEY"],
    policy=CredKyaPolicy(
        review="accept",                 # or "refuse", or a callable (profile, context) -> bool
        refuse_flags=("K02", "K03"),     # review flags that always refuse
        no_agent="screen",               # plain wallets: OFAC screen (1 CU) | "refuse" | "accept"
        on_error="accept",               # Cred unavailable or slow: "accept" | "refuse"
    ),
    timeout=1.5,                         # seconds to wait for the profile
    cache_ttl=CacheTtl(passed=900, block=3600),
    on_decision=lambda decision, context: audit.write(decision),
)

Cost. A KYA lookup costs 10 Cred Units; a wallet with no agent is a free 404, then a 1 CU screen.
Caching. Decisions are cached per payer: 15 minutes, or 1 hour for a sanctions refusal. An incomplete check (K13) is never cached.
Fail open, but not past sanctions. With on_error="accept" the hook still runs the fast OFAC screen and refuses a sanctioned payer. It accepts unchecked only if that screen fails too.
Never raises. x402 re-raises a hook’s exception and fails the request, so the hooks turn every failure into an explicit accept or refuse.
Async server. Concurrent payments from one payer share a lookup. A lookup that runs past timeout keeps going in the background, so the payer’s next payment gets the full answer.
Sync server. timeout bounds the HTTP call itself, and a timed-out payer is looked up again on their next payment.

CredKyaClient (async) and CredKyaClientSync expose the same calls directly: kya_by_wallet, kya_by_agent_id and sanctions_screen.

Choosing a policy

Cred answer	What to do	SDK setting
`block`	Always refuse. K01 means the agent’s owner or agent wallet is on an OFAC list.	Not configurable; cached 1 hour
`review`	Decide by flag and amount. K07 (no domain proof) or K08 (registered under 30 days) can be fine for small payments; K02/K03 (sanctioned funding source or counterparty) should refuse. K13 means a check didn’t complete, so the payer’s next payment is checked again.	`review` (`"accept"`, `"refuse"`, or a function of the profile and payment), `refuse_flags`
`pass`	Settle and serve.	Cached 15 minutes
`404`, no agent	The payer is a plain wallet. Screen it against OFAC, or refuse if you only serve registered agents. The hook doesn’t check one-hop exposure; call `/sanctions/exposure` (3 CU) yourself if you need it.	`no_agent` (`"screen"`, `"refuse"`, `"accept"`)

Using Without FastAPI

The core CredClient works with any async Python code:

from cred_protocol import CredClient

# As async context manager (recommended)
async with CredClient(api_key="cred_sk_...") as cred:
    result = await cred.evaluate(wallet_address="0x...", policy="standard")

# Or manage lifecycle manually
cred = CredClient(api_key="cred_sk_...")
result = await cred.evaluate(wallet_address="0x...", policy="standard")
await cred.close()

SDKs

Framework Adapters

Installation

Quick Start

Evaluate Options

Using a Policy Template

Using Custom Gates

With Dynamic Pricing

TrustResult Fields

Error Handling

FastAPI Integration

FastAPI Configuration

Wallet Extraction

Failure Responses

Screen x402 payers (Know Your Agent)

Where the check runs

Policy

Choosing a policy

Using Without FastAPI

​Installation

​Quick Start

​Evaluate Options

​Using a Policy Template

​Using Custom Gates

​With Dynamic Pricing

​TrustResult Fields

​Error Handling

​FastAPI Integration

​FastAPI Configuration

​Wallet Extraction

​Failure Responses

​Screen x402 payers (Know Your Agent)

​Where the check runs

​Policy

​Choosing a policy

​Using Without FastAPI

Installation

Quick Start

Evaluate Options

Using a Policy Template

Using Custom Gates

With Dynamic Pricing

TrustResult Fields

Error Handling

FastAPI Integration

FastAPI Configuration

Wallet Extraction

Failure Responses

Screen x402 payers (Know Your Agent)

Where the check runs

Policy

Choosing a policy

Using Without FastAPI