inamprotocol (Python SDK)

Reference Python client for the INAM Protocol — parity with the TypeScript InamClient in ../sdk-js/src/client.ts. See ../SPEC.md for the full protocol specification.

Install (development)

python -m venv .venv
./.venv/Scripts/python.exe -m pip install -e . pytest   # Windows
# ./.venv/bin/python -m pip install -e . pytest          # macOS/Linux

Test

./.venv/Scripts/python.exe -m pytest -v

tests/test_interop.py is the important one: it checks this SDK's did:key encoding, canonical JSON, and Ed25519 signing against fixed values generated once by the TypeScript reference implementation (../scripts/interop-vectors.ts). If a change here ever breaks that test, a receipt signed by this SDK would stop verifying against a registry or another SDK written in a different language — that's the whole point of the test.

Usage

from inamprotocol import InamClient, generate_keypair

keypair = generate_keypair()
client = InamClient("http://localhost:4021", keypair)

profile = client.register_agent(["document-extraction"], {"name": "My Agent"})
print(profile["id"])  # did:key:z...

reputation = client.get_reputation(profile["id"])

Jobs (post -> offer -> accept -> execute -> receipt)

from datetime import datetime, timezone

now = datetime.now(timezone.utc).isoformat()
job = poster.post_job("document-extraction", "sha256:...")
worker.submit_offer(job["jobId"], "I can do this in an hour")
poster.accept_offer(job["jobId"], worker.did)

receipt = worker.submit_work(poster.did, {
    "jobId": job["jobId"],
    "task": {"capability": "document-extraction", "specHash": "sha256:...", "createdAt": now},
    "result": {"outputHash": "sha256:...", "completedAt": now},
    "verification": {"method": "payer_confirmation", "outcome": "success"},
})
poster.accept_work(receipt)  # finalizes the receipt and auto-completes the job

poster.cancel_job(job["jobId"]) cancels a not-yet-completed job (poster only); client.get_job(id) / client.search_jobs(capability=..., status=...) / client.list_offers(job_id) round out discovery.

External identity linking (challenge-response)

Linking a key-derived external identity (agentpass_id / aitp_id / passport_id; SPEC.md section 2.1) requires proving control of that external key via a single-use, ~60s challenge. a2a_endpoint isn't key-derived, so it skips straight to link_identity(protocol, value). ### Deciding whether to deal with an agent

check_trust turns an agent's reputation into allow, escrow (deal, but hold payment until delivery is confirmed), or deny, with the reasons. It runs on your side; the registry's numbers are a hint (SPEC.md §5.4).

from inamprotocol import check_trust

d = check_trust(did, client, allow={"min_evidence": "independently_verified", "min_trust_score": 5})
# {"decision": "escrow", "reasons": ["evidence countersigned is below independently_verified"], ...}

A revoked or unknown ID is deny; warning flags (in_dispute, attestation_rejected, nonperformance_reported, concentrated_counterparty) cap the decision at escrow (change with escrow_flags).

Verifying an x402 payee before paying

A payer pays only a payTo the payee's INAM ID proved control of (linked.erc8004_id), and only if its reputation meets the payer's policy (SPEC.md §11.2). counterparty_context records that decision as an x402 CounterpartyContext (x402 #1777), with policy_input_hash over the JCS form of exactly what was checked:

from inamprotocol import counterparty_context

agent, rep = client.get_agent(did), client.get_reputation(did)
request = {"resource": "https://paid.example/api", "amount": "1000", "network": "eip155:8453", "nonce": "req-0001"}
ctx = counterparty_context(agent, rep, [a["payTo"] for a in accepts], request, min_evidence="countersigned", min_trust_score=0)
# {"decision": "allow", "reason": "ok", "policy_input_hash": "sha256:...", ...}

decide_x402 is the decision alone and x402_policy_input the hashed input. Hashes and reasons match sdk-js byte for byte, checked against ../tests/vectors/x402-counterparty-context.json.

Publishing a receipt as ERC-8004 feedback

The receipt's requester can post it to ERC-8004's Reputation Registry from its linked erc8004_id (SPEC.md §11.1). The file carries the signed receipt, so readers can tell it from a bare score:

from inamprotocol import build_erc8004_feedback, verify_erc8004_feedback

fb = build_erc8004_feedback(receipt, requester_record, "eip155:8453:0x...", agent_id=42)
# host fb["file_text"] at feedbackURI, then send giveFeedback(**fb["args"], feedbackURI=...)

check = verify_erc8004_feedback(file_text, feedback_hash, client_address, client, value=100)
# {"valid": ..., "reasons": [...], "receipt_id": ..., "provider_did": ..., "provider_address": ...}

See examples/erc8004_demo.py.

See examples/interop_worker.py for this in a full running script.

# external_keypair stands in for whatever key AgentPass/AITP/Passport
# Alliance already issued this agent -- not an INAM keypair.
challenge = client.request_link_challenge("agentpass_id", to_base64(external_keypair.public_key), "ed25519")
proof = to_base64(sign(from_hex(challenge["challenge"]), external_keypair.private_key))
client.complete_link("agentpass_id", "ap_my_external_id", challenge["challengeId"], proof)

Verification (independent attestation)

A third party -- anyone but the receipt's own worker (agentB) -- can attest that a finalized receipt's output actually holds up (SPEC.md section 12), feeding a reputation boost:

verification = verifier_client.submit_verification(
    receipt_id=receipt["receiptId"],
    method="deterministic",  # or "agent_attestation"
    output_hash=receipt["result"]["outputHash"],
    result="verified",  # or "rejected"
)

verifier_client.get_verification(verification["verificationId"])
verifier_client.list_receipt_verifications(receipt["receiptId"])

See examples/interop_worker.py for a full worker-side flow (register, link an external identity, submit signed Execution Receipt drafts), and ../scripts/run-interop-demo.sh for the end-to-end cross-language demo (a TypeScript requester and this Python worker doing real business through the same live registry).