Codester demo · Scripts & Code → Python

x401 Gateway — Agent Identity and Human Approval Wallet

x401 agent identity gateway: signed proof of which agent is asking, plus a wallet where a human approves its actions.

$24 on CodesterUnit tests: 144 passed · smoke suite: PASSHandshake below: run end to end on the real demo

The approval screen

The pause is the product. When an agent asks for proof, the wallet shows the person exactly what is being approved — which agent, which merchant, what ceiling — before anything is signed. This is a captured snapshot of the wallet's real approval page from a live demo run (buttons are inert in the snapshot).

The full handshake, run end to end

The package's runnable demo: a merchant (verifier), an agent CLI, and the wallet. The agent fetches the challenge, hands it to the wallet, the approval is granted, and the agent retries with signed proof. Real output from the demo orchestrator (auto-approve mode, so no human had to click).

$ python3 -m demo.run_demo --auto-approve

x401-gateway demo (backend: real wallet; real x401 (10/10 modules))
wallet:   http://127.0.0.1:8071  (device issuer x401-wallet:JcmhlSkS0KhxzqE0, kid JcmhlSkS0KhxzqE0)
merchant: http://127.0.0.1:8072  (charge USD 49.99)

================================================================
ACTION REQUIRED — open this URL to approve as the person:
  http://127.0.0.1:8071/approve/appr-2OR7zPPfwAzm0AXe
================================================================

auto-approved via POST /api/approve/appr-2OR7zPPfwAzm0AXe (HTTP 200)
approved; retrying the merchant ...
HTTP 200
{"granted": true, "scheme": "x401", "version": "0.2.0", "request_id": "demo-purchase-v1-DhvA_5Ys", "mandate": {"issuer": "x401-wallet:JcmhlSkS0KhxzqE0", "agent_id": "demo-agent/1", "merchant": "https://merchant.demo", "action": "purchase", "ceiling": {"currency": "USD", "value": "100.00"}}, "charge": {"currency": "USD", "value": "49.99"}}

The proof the merchant accepted

The PROOF-RESULT the demo merchant returned after approval — the agent's mandate (charge up to USD 100.00 for this merchant) and the USD 49.99 charge it covered.

{
  "granted": true, "scheme": "x401", "version": "0.2.0",
  "request_id": "demo-purchase-v1-DhvA_5Ys",
  "mandate": {"issuer": "x401-wallet:JcmhlSkS0KhxzqE0", "agent_id": "demo-agent/1",
              "merchant": "https://merchant.demo", "action": "purchase",
              "ceiling": {"currency": "USD", "value": "100.00"}},
  "charge": {"currency": "USD", "value": "49.99"}
}

One honest note, from the listing: the download contains no keys and no stored credentials. The wallet generates its own device keys on your machine on first run — which is how it should be. The keys in this demo were generated fresh in a throwaway folder and discarded.

From the package

Screenshots shipped inside the Codester package.

What it does

Strict header codec for PROOF-REQUEST / PROOF-RESPONSE / PROOF-RESULT (signed and unsigned forms)
JWS signing: EdDSA (Ed25519) and ES256, with a mandatory single-use nonce cache
Self-hosted identity wallet: credential store, per-device key registration, approval queue
QR and deep-link transport for approval requests, with a return_uri relay
Local trust lists with DCQL satisfaction checks — you decide who is trusted
OAuth token-exchange leg included; SSRF-guarded by-reference responses
A runnable demo: merchant (verifier) + agent CLI + wallet, so the full handshake runs on your machine
Unit and end-to-end test suites included; stdlib + cryptography only — no web frameworks