Models & Exceptions

Data models and exceptions used throughout the AgentMarque SDK.

from agentmarque.schemas import (
    VerificationResult,
    VerificationCheck,
    OrganizationInfo,
    SettlementInfo,
)
from agentmarque.exceptions import (
    AgentMarqueError,
    CredentialError,
    VerificationError,
    HandshakeError,
)

MODELclass VerificationResult

VerificationResult

Returned by AgentMarqueVerifier.verify() and AgentMarqueVerifier.verify_async(). Contains the overall result plus granular check outcomes.

Name
valid
Type
bool
Description
Overall verification result. True only if all performed checks passed.
Name
checks
Type
VerificationCheck
Description
Individual check results. See VerificationCheck.
Name
claims
Type
dict | None
Description
Disclosed claims from the presentation. None if signature verification failed.
Name
errors
Type
list[str]
Description
Human-readable error messages for each failed check. Empty list when valid is True.

Example

result = verifier.verify(
    presentation=jwt_string,
    min_tier=1,
)

if result.valid:
    print(result.claims["agentName"])
    print(result.claims["capabilities"])
else:
    for err in result.errors:
        print(f"  - {err}")

MODELclass VerificationCheck

VerificationCheck

Granular results for each verification step. Each field is True if the check passed, False if it failed, or None if the check was not performed.

Name
signature
Type
bool
Description
SD-JWT issuer signature is valid.
Name
holder_bound
Type
bool | None
Description
KB-JWT signature matches the cnf public key in the credential, proving the presenter controls the holder key. None if no KB-JWT was present in the presentation.
Name
status
Type
bool | None
Description
Credential has not been revoked. None if check_revocation was False or no status list URL was present.
Name
dates
Type
bool
Description
Credential is within its validFrom / validUntil window.
Name
issuer_trusted
Type
bool
Description
Issuer DID is in the trusted_issuers list.
Name
nonce
Type
bool | None
Description
Nonce matches the expected challenge nonce. None if no nonce was expected.
Name
audience
Type
bool | None
Description
KB-JWT audience matches the expected audience from the challenge. None if no audience was expected.
Name
policy
Type
bool
Description
All policy constraints (min_tier, min_reputation, required_capabilities) are satisfied.

Example

result = verifier.verify(
    presentation=jwt_string,
    expected_nonce="abc123",
    min_tier=2,
)

checks = result.checks
print(checks.signature)      # True
print(checks.holder_bound)   # True
print(checks.status)         # None (not checked)
print(checks.dates)          # True
print(checks.issuer_trusted) # True
print(checks.nonce)          # True
print(checks.audience)       # True
print(checks.policy)         # True

MODELclass OrganizationInfo

OrganizationInfo

Organization metadata embedded in agent credentials. Passed as a dict to issue_credential().

Name
id
Type
str
Description
Organization identifier (e.g., "https://acme.co").
Name
name
Type
str
Description
Organization display name.

Example

from agentmarque.issuer import issue_credential

credential = issue_credential(
    issuer_key=issuer_key,
    subject_did=agent_did,
    subject_key=agent_pub,
    agent_name="my-agent",
    organization={
        "id": "https://acme.co",
        "name": "Acme Corp",
    },
    capabilities=["translate"],
    verification_tier=1,
    reputation_score=75.0,
)

MODELclass SettlementInfo

SettlementInfo

Settlement configuration embedded in agent credentials. Describes how the agent accepts payment for its services.

Name
methods
Type
list[str]
Description
Supported settlement methods (e.g., ["x402", "stripe"]).
Name
x402_address
Type
str | None
Description
Blockchain address for x402 micropayments.
Name
stripe_account
Type
str | None
Description
Stripe connected account ID.

Example

from agentmarque.issuer import issue_credential

credential = issue_credential(
    ...,
    settlement={
        "methods": ["x402"],
        "x402_address": "0xABC...",
    },
)

Exceptions

All SDK exceptions inherit from AgentMarqueError.

AgentMarqueError
├── CredentialError
├── VerificationError
└── HandshakeError

AgentMarqueError

Base exception for all AgentMarque errors. Catch this for broad error handling across the entire SDK.

Example

from agentmarque.exceptions import AgentMarqueError

try:
    result = verifier.verify(presentation)
except AgentMarqueError as e:
    print(f"AgentMarque error: {e}")

CredentialError

Raised when credential issuance or deserialization fails. Common causes:

Invalid organization dict (missing id or name)
Malformed JSON passed to AgentCredential.from_json()

Example

from agentmarque.exceptions import CredentialError

try:
    cred = AgentCredential.from_json(json_str)
except CredentialError as e:
    print(f"Credential error: {e}")

VerificationError

Raised for unrecoverable verification failures. Common causes:

Unsupported DID method (not did:key: or did:web:)
did:web: resolution failed (network error, invalid DID document)

Normal verification failures (invalid signature, policy mismatch, etc.) are reported via VerificationResult rather than exceptions.

Example

from agentmarque.exceptions import VerificationError

try:
    result = verifier.verify(presentation)
except VerificationError as e:
    print(f"Verification error: {e}")

HandshakeError

Raised when the handshake protocol encounters an error. Common causes:

Invalid DID format passed to verify_response()
DID resolution failure

Example

from agentmarque.exceptions import HandshakeError

try:
    result = AgentHandshake.verify_response(
        response=presentation,
        expected_challenge=challenge,
        verifier=my_verifier,
    )
except HandshakeError as e:
    print(f"Handshake error: {e}")