iap-sdk

Identity Anchor Protocol (IAP) gives AI agents persistent, cryptographically verifiable identities. An agent generates an Ed25519 keypair, anchors it at a public registry, and from that point every state transition is tracked in an append-only local ledger (AMCS) and can be certified by the registry. The result: you can prove — offline, to any third party — that this is the same agent as yesterday, even after restarts, migrations, or model swaps.

This SDK provides request signing, state continuity tracking, and offline certificate verification.

Website & docs: identityanchorprotocol.com

Beta — free to try. The registry is live. During beta, all certificate operations are free (no account required). See Try it now below.

Try it now

No account needed. Two ways to get started:

Option 1: Tamper-detection demo (2 minutes, fully offline)

git clone https://github.com/identity-anchor-protocol/iap_sdk.git
cd iap_sdk
pip install -e ".[dev]"
python examples/state-drift-demo/demo.py

You'll see verify_before_ok=True, then a simulated tamper, then verify_after_ok=False. That's the core idea: once state history is modified, verification fails.

Option 2: Full flow — anchor an identity and get a real certificate

pip install iap-agent
iap init --project-local
iap anchor --registry-base https://registry.ia-protocol.com
iap commit "my first state commit" --registry-base https://registry.ia-protocol.com

That creates a keypair, registers it at the public registry, and issues your first continuity certificate. The certificate is a signed JSON file you can verify offline.

Install

Published package:

python -m pip install -U pip
python -m pip install iap-agent
iap version
iap-agent version

Local editable development install:

python -m pip install -e ".[dev]"

For clean public installs, use iap-agent >= 0.1.5. That is the first release that depends on the correct PyPI package name for AMCS (iap-amcs).

What this package provides

• Deterministic agent_id derivation from Ed25519 public keys
• Canonical request builders and signers for continuity, lineage, key rotation
• Registry API client helpers
• Offline certificate verification (including identity-anchor checks)
• Liveness and transparency helper utilities

IAP tracks agent state evolution. It does not reduce LLM sampling randomness.

Quick example

from iap_sdk import build_continuity_request, sign_continuity_request

payload = build_continuity_request(
    agent_public_key_b64="...",
    agent_id="ed25519:...",
    memory_root="a" * 64,
    sequence=1,
    manifest_version="IAM-1",
    manifest_hash="b" * 64,
)
signed = sign_continuity_request(payload, private_key_bytes=b"...")

Run tests

pytest

Reproducible install

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev]"
iap-agent version

For a clean-room install smoke test, run:

./scripts/smoke_install.sh

Run the hardened closeout verification script against a live registry and issued records:

python scripts/final_live_test.py \
  --registry-base https://registry.ia-protocol.com \
  --identity-anchor ./identity_anchor_record.json \
  --continuity-record ./continuity_record.json

Validate CLI snippets in docs:

python scripts/validate_doc_commands.py

CLI (beta)

Install editable and run:

python -m pip install -e ".[dev]"
iap version
iap init
iap track
iap anchor
iap commit "updated agent objective"
iap verify ./continuity_record.json --registry-public-key-b64 <key>

# Legacy CLI remains supported in v0.1.x:
iap-agent continuity request --registry-base https://registry.ia-protocol.com --json
iap-agent registry status --registry-base https://registry.ia-protocol.com --json

Fresh identity vs existing identity

• iap-agent init --project-local creates a new identity in the current project at ./.iap/identity/ed25519.json.
• iap-agent init without --project-local uses the global identity at ~/.iap_agent/identity/ed25519.json if it already exists.

Use --project-local when you want a genuinely new agent. Use the global identity only when you intentionally want to continue the same agent across different folders.

Upgrade safety

• python -m pip install -U iap-agent updates the SDK package only; it does not change agent_id.
• iap-agent upgrade status --json checks the current identity path, local state sequence, and registry capabilities before you request new certificates.
• iap-agent upgrade migrate --json previews safe local .iap metadata migrations; rerun with --apply only when you want the SDK to normalize local metadata/schema markers.
• Routine software upgrades should normally continue with a new continuity event, not lineage.

If a continuity request fails with:

• ledger_sequence must strictly increase; latest registry sequence is X

inspect the current registry state:

iap-agent registry status --registry-base https://registry.ia-protocol.com --json

That shows whether this agent_id already has an identity anchor and what the latest certified continuity sequence is.

CLI exit codes

• 0: success
• 1: validation/config/user input error
• 2: network/registry unavailable
• 3: timeout waiting for certification
• 4: verification failure

Version compatibility

See /COMPATIBILITY.md for pinned SDK/protocol/registry API assumptions.

For the deployed beta line, the protocol-level certificate version remains IAP-0.1, while the continuity certificate subtype remains IAP-Continuity-0.2 for backward compatibility with the existing issued certificate chain and verification vectors. This is intentional. It does not mean continuity is on a different protocol generation than identity, lineage, or key rotation.

Support / Feedback

If you hit a bug, an upgrade issue, or have recommendations for improvement, contact:

• admin@ia-protocol.com
• identityanchorprotocol.com

Docs

• /docs/quickstart-first-certificate.md
• /docs/e2e-user-walkthrough.md
• /docs/e2e-dev-local-walkthrough.md
• /docs/operator-runbook-payments.md
• /docs/local-amcs-privacy-model.md
• /docs/lnbits-vs-stripe-flow.md
• /docs/troubleshooting.md
• /docs/migration-cli-first.md
• /docs/transition-terminology.md
• /docs/final-live-test.md
• /docs/upgrade-guide.md
• /docs/security-assumptions.md
• /examples/state-drift-demo/README.md
• /RELEASE.md
• /RELEASE_NOTES_TEMPLATE.md

Drift demo

Run the transition demo in under 5 minutes:

python examples/state-drift-demo/demo.py

Expected:

• verify_before_ok=True
• verify_after_ok=False

Beta mode config

Default config path:

~/.iap_agent/config.toml

Example:

beta_mode = true
maturity_level = "beta"
registry_base = "https://registry.ia-protocol.com"
registry_api_key = "iap_live_optional"
account_token = "iapt_live_optional"
amcs_db_path = "./amcs.db"

To bootstrap the two most common registry settings without editing TOML manually:

iap-agent registry set-base --base "https://registry.ia-protocol.com"
iap-agent registry set-api-key --api-key "iapk_live_optional"

Or bootstrap base URL, entitlement API key, and account token together:

iap-agent setup --registry-base "https://registry.ia-protocol.com" --registry-api-key "iapk_live_optional" --account-token "iapt_live_optional" --check --json

Before issuing requests, you can run a read-only preflight:

iap-agent registry check --json

To bootstrap just the account token without editing TOML manually:

iap-agent account set-token --token "iapt_live_optional"

Environment override:

export IAP_REGISTRY_BASE="https://registry.ia-protocol.com"
export IAP_REGISTRY_API_KEY="iap_live_optional"
export IAP_ACCOUNT_TOKEN="iapt_live_optional"

With an account token configured, you can inspect your current quota usage:

iap-agent account usage --json

If you are the operator handing off bootstrap instructions to a user, you can generate the exact copy/paste commands:

iap-agent account handoff --registry-base "https://registry.ia-protocol.com" --registry-api-key "iapk_live_optional" --account-token "iapt_live_optional" --json

The CLI also writes the latest successful account usage response to:

• <sessions_dir>/account_usage_last.json

Local development override example:

registry_base = "http://localhost:8080"