mintid-agent

The MintID agent client for Python: the agent runtime's side of an agent credential. An agent credential proves that a person, verified at an issuer, delegated this agent to pay this kind of counterparty within stated bounds, and nothing about who that person is. The client obtains the credential from an agent offer, keeps its witnesses current, answers a seller's identity requirement inside an x402 payment flow, and refuses, before anything is sent or paid, whatever the delegation does not cover.

It carries no cryptography of its own: proofs come from the MintID holder library (mintid-proof-core), signatures from a signer you inject.

Where it fits

MintID is a network for verifiable, human-backed identity. Accepted issuers verify people and issue the credentials; the chain publishes their status roots, their bonds and the registries; each verifier decides on its own service. MintID itself issues nothing, certifies nothing and verifies nobody.

The agent client runs in your own infrastructure, and its keys never leave it: the credential's private bytes go only to the credential store you inject (encryption at rest is yours), and the request-signing key stays behind the signer you inject. The operator who mints the agent, not the agent, decides the delegation.

Install

pip install mintid-agent              # Python 3.12 or later
pip install "mintid-agent[ed25519]"   # with the software Ed25519 signer

It depends on mintid-proof-core, which compiles the Rust proof core in; where no wheel matches your platform, pip builds it from source with a Rust toolchain. Version 0.2.0 (with mintid-proof-core 0.4), published from the main repository, https://gitlab.com/mintid/mintid (sdk/python/mintid-agent).

Upgrading from 0.1. Two behaviour changes. The holder checks every challenge's signature before it presents: give AgentClient a source of verifiers' request keys, verifiers= (ProvenVerifierKeys over a proven chain read, or StaticVerifierKeys of records you pinned); without one, or for an unsigned or wrongly signed challenge, present raises ChallengeRefused and nothing is sent or paid. And refresh().usable is true only once a finalised root anchors every scope value of the delegation (agent.scope_anchored), so a new agent no longer presents into scope_axis_unprovable: poll refresh() until usable, as below.

Example

import time

from mintid_agent import AgentClient
from proof_core.holder import urllib_transport

# offer: the agent offer the operator made; principal: the principal's
# identity credential (a proof_core.holder.Holder); store: your CredentialStore.
# verifiers: where the holder reads verifiers' request keys (ProvenVerifierKeys
# over a proven chain read, or StaticVerifierKeys of records you pinned).
agent = AgentClient.issue_from_offer(
    offer, principal, transport=urllib_transport(), store=store, verifiers=verifiers
)

while not agent.refresh().usable:      # the status witness, then the scope log;
    time.sleep(5)                      # usable once a root anchors the delegation
envelope = agent.present(challenge)    # checks the verifier's signature (ChallengeRefused), then
                                       # proves or refuses, naming what the delegation cannot satisfy
result = agent.pay(url, payer=payer)   # one paid request; your payer builds the payment header

The same client renews the credential from a renewal offer and holds the agent's kill switch: holder self-revocation, submitted through a privacy relay and confirmed against the chain.

Where to test

On the public testnet and its KYC sandbox, and only there: check the status line of its page first. Nothing minted on it carries weight. The single-node production chain is not for third parties and is never a place to test.

Links

• Documentation: https://gitlab.com/mintid/mintid/-/blob/main/docs/sdk/15-agent-clients.md
• Source: https://gitlab.com/mintid/mintid (sdk/python/mintid-agent), where issues and merge requests go; read-only mirror: https://gitlab.com/mintid/sdk-python
• Public testnet: https://gitlab.com/mintid/mintid/-/blob/main/docs/sdk/17-sandbox-and-testnet.md
• Security: report a vulnerability privately to security@mintid.net, never in a public issue; policy: https://gitlab.com/mintid/mintid/-/blob/main/SECURITY.md
• Website: https://mintid.net

Licence

Apache License 2.0 (LICENSE, NOTICE). Author: Marc Molas.

This repository

This is a read-only mirror of sdk/python/mintid-agent of the MintID source tree, https://gitlab.com/mintid/mintid, and is published from it: each publication replaces its content, and nothing is merged here. Issues and merge requests go to the main project, https://gitlab.com/mintid/mintid/-/issues; a vulnerability goes privately to the address in its SECURITY.md, never to a public issue. Licence: Apache License 2.0 (LICENSE and NOTICE); contributions follow the main project's CONTRIBUTING.md.

Package: mintid-agent (Python >= 3.12). It depends on mintid-proof-core, the Python bindings of the Rust proof core and holder library, whose source is identity-proof-core/python of the main repository. To work here against the proof core of the same revision, build it from a clone of the main repository (pip install ./identity-proof-core/python, with a Rust toolchain), then install this package (pip install -e ".[ed25519]").