Skip to content
Back to search

cyphos-guard

Guardrails and human approval for AI agents that spend crypto: on-chain limits, passkey approvals, x402. Open source, self-hosted, testnet-only.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/phosse136--cyphos-guard/badge.svg)](/listings/phosse136--cyphos-guard)

HTML

<a href="/listings/phosse136--cyphos-guard"><img src="/api/listings/phosse136--cyphos-guard/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requirements: Node ≥ 24, pnpm 12, [Foundry](https://getfoundry.sh) (for `anvil`), Chrome or Chromium.

pnpm install
pnpm poc     # proof of concept on a local Base Sepolia fork: limits, rejections, revoke, all on-chain
pnpm dev     # fork + policy service + approver → open http://localhost:3000

In the approver: **Create passkey → Create account → Grant a new agent**. Then let an agent use it:

pnpm demo:setup   # agent key + gas; prints a link that prefills the demo grant
pnpm demo:agent   # a Claude agent pays four invoices (needs ANTHROPIC_API_KEY in .env)

One run shows all three layers: two invoices paid alone, one approved by you with your passkey, one blocked by your denylist ([demo details](examples/demo-agent/README.md), [video script](docs/demo-script.md)).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 382 lines
  1. # cyphos-guard
  2. **Guardrails and human approval for AI agents that spend crypto. Open source, self-hosted, testnet-first.**
  3. Give an agent a budget it can't exceed, get a passkey prompt when it wants more, and make some things impossible.
  4. All of it is enforced by your smart account, not by a server you have to trust.
  5. ![Demo: Claude pays two invoices alone, one after a Face ID approval, and is blocked from a forbidden vendor](docs/media/cyphos-guard-demo.gif)
  6. ![cyphos-guard demo: grant an agent, approve a big payment with a passkey, see a forbidden payment blocked](docs/assets/demo.gif)
  7. > **Status:** working MVP on Base Sepolia (and local forks of it). **Testnet only. Not audited. Do not use with real funds.**
  8. ## The three layers
  9. | Layer | Example | What happens |
  10. | ------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
  11. | **Routine** | Pay ≤ 2 USDC per invoice, ≤ 5 USDC a day, to your API provider | The agent pays alone. Limits are enforced **on-chain** |
  12. | **Big or unusual** | A 4 USDC annual-plan invoice | You get an approval request and approve with your **passkey** (Face ID, fingerprint, YubiKey). No seed phrase |
  13. | **Forbidden** | Paying a vendor on your denylist | Blocked. Never executed, never offered for approval |
  14. ## Quick start (5 minutes, no faucet, no API keys)
  15. Requirements: Node ≥ 24, pnpm 12, [Foundry](https://getfoundry.sh) (for `anvil`), Chrome or Chromium.
  16. ```sh
  17. pnpm install
  18. pnpm poc # proof of concept on a local Base Sepolia fork: limits, rejections, revoke, all on-chain
  19. pnpm dev # fork + policy service + approver → open http://localhost:3000
  20. ```
  21. In the approver: **Create passkey → Create account → Grant a new agent**. Then let an agent use it:
  22. ```sh
  23. pnpm demo:setup # agent key + gas; prints a link that prefills the demo grant
  24. pnpm demo:agent # a Claude agent pays four invoices (needs ANTHROPIC_API_KEY in .env)
  25. ```
  26. One run shows all three layers: two invoices paid alone, one approved by you with your passkey, one blocked by
  27. your denylist ([demo details](examples/demo-agent/README.md), [video script](docs/demo-script.md)).
  28. ## Verified on Base Sepolia
  29. The proof of concept (`NETWORK=live pnpm poc`) ran against live Base Sepolia on 2026-11-20. Every rejection
  30. is a real transaction that the chain reverted; Basescan shows which caveat enforcer refused it.
  31. | Step | Result | Transaction |
  32. | ------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  33. | Owner's smart account (MetaMask Hybrid DeleGator) | deployed | [account](https://sepolia.basescan.org/address/0xBDCBf99882c8B1907d2D50B002b5442A909E39aC) · [deploy tx](https://sepolia.basescan.org/tx/0x8d45daa06ebaba7e97e0ebcf7f7b13f98681b6a219a061120ae247872a0a5054) |
  34. | Grant: max 0.001 ETH/day, one recipient, 7 days | signed off-chain (no gas) | n/a |
  35. | Agent sends 0.0005 ETH | ✔ executed | [tx](https://sepolia.basescan.org/tx/0x2a80682ea8ceef5055348df41024e938186024fbbdf41425119322f3a4ef96d4) |
  36. | Agent sends 0.0006 ETH more (0.0011 for the day) | ✘ `NativeTokenPeriodTransferEnforcer:transfer-amount-exceeded` | [reverted](https://sepolia.basescan.org/tx/0xe63575d7c35c7969f3c06d6f6d28bec51f111e2258a2465068c5d7a0f1635551) |
  37. | Agent pays an address that isn't allowed | ✘ `AllowedTargetsEnforcer:target-address-not-allowed` | [reverted](https://sepolia.basescan.org/tx/0x5884582d3a6f8f039d37d41827abfadef98c31f3e74514daa6e6e1d41dcd6e55) |
  38. | Agent attaches calldata to an allowed payment | ✘ `ExactCalldataEnforcer:invalid-calldata` | [reverted](https://sepolia.basescan.org/tx/0x2169ba5984a34d531e5b54afa860e3062b0a5655eaf69bbcea0cbe2d7a5412af) |
  39. | Owner revokes the grant | ✔ executed | [tx](https://sepolia.basescan.org/tx/0x4005499051f8fd8977a3ba6c511ed4c3ca387ae6fc3e7fbcaeacfe822ccb17e2) |
  40. | Agent tries again after revocation | ✘ `CannotUseADisabledDelegation()` | [reverted](https://sepolia.basescan.org/tx/0x3539b22250cf502d8f21a4840f770d6548a51723cf67bbbe2ef1b7abb4875125) |
  41. cyphos-guard's own **CosignerEnforcer** ([ADR 0005](docs/decisions/0005-cosigner-enforcer.md)) is deployed on Base Sepolia at
  42. [`0x0a2f40e9789235B6ce2a23668FD3F90cef5eefbf`](https://sepolia.basescan.org/address/0x0a2f40e9789235B6ce2a23668FD3F90cef5eefbf)
  43. ([deploy tx](https://sepolia.basescan.org/tx/0x173932c273aa54d8d1751b2a1c646ba12c7fee64e8480e7869548d3523892b47)). It has the same address on every
  44. chain, no owner and no upgrade path.
  45. **Co-signer scenario** (`NETWORK=live pnpm poc:cosigner`, 2026-11-20). Grant: 0.001 ETH/day to one shop, with a co-signer.
  46. The co-signer key signs exactly the typed data the policy service signs.
  47. Account [0xd7a0…bD60](https://sepolia.basescan.org/address/0xd7a053F7d2063705FC0b5F84879331044Af6bD60).
  48. | What the agent tried | Result | Transaction |
  49. | ---------------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
  50. | Send 0.0002 ETH with a fresh cosignature | ✔ executed | [tx](https://sepolia.basescan.org/tx/0x98c8fbcfb21e4ab4b2772d56767a4460e6589f686f09361e11aa1605d63ad071) |
  51. | Same payment without a cosignature (bypassing the service) | ✘ `CosignerEnforcer:missing-cosignature` | [reverted](https://sepolia.basescan.org/tx/0x74d20745be7b21a55ddf4634180db726b4f9ae3644adeb9069a8c5340b658041) |
  52. | Cosignature forged with the agent's own key | ✘ `CosignerEnforcer:invalid-cosignature` | [reverted](https://sepolia.basescan.org/tx/0x4fd3b0f4b1e4210d7ee18e3a9cd97fae202dc8744bbedf45ddc0875e589cb7d1) |
  53. | Cosignature for 0.0002 used to send 0.0003 | ✘ `CosignerEnforcer:invalid-cosignature` | [reverted](https://sepolia.basescan.org/tx/0x2da5e6a1f8d63b04e8994c4b5516bb405e68b19fcbc6cd95f512b9514ff98c2f) |
  54. | Replaying the used cosignature | ✘ `CosignerEnforcer:already-used` | [reverted](https://sepolia.basescan.org/tx/0x0abed9c6a41f151e4d97dcaa6f13780396a46f045137b974368114974bdec4b8) |
  55. | Expired cosignature | ✘ `CosignerEnforcer:expired` | [reverted](https://sepolia.basescan.org/tx/0x9cbe4bf88970cbfb55234e119422bdd943a5b2c2f006284ceec38e4b1288f902) |
  56. | 0.0009 ETH with a valid cosignature (over the daily cap) | ✘ `NativeTokenPeriodTransferEnforcer:transfer-amount-exceeded` | [reverted](https://sepolia.basescan.org/tx/0xc4808b32771c1e941adda5219b2a3b2e96748d9fbbe76cfb53ceb9ec27f0437b) |
  57. **Approver app, live** (`pnpm --filter @cyphos-guard/approver e2e:live`, 2026-11-20). The real UI in Chromium with a virtual
  58. passkey: the passkey-only account was created through the public Pimlico bundler, then granted a co-signed 0.0005 ETH/day
  59. permission. Account [0x408a…cEEB](https://sepolia.basescan.org/address/0x408a4835F92C8d5fd173769a08BB4C26B584cEEB).
  60. | Step | Result | Transaction |
  61. | ------------------------------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
  62. | Agent pays 0.0002 ETH alone (co-signed) | ✔ executed | [tx](https://sepolia.basescan.org/tx/0x69754a60214bd1544edce679afcc7cac6c5ac275617d2f582ab1e88dc3490059) |
  63. | Agent wants 0.0006 ETH (over the daily cap) → owner approves with passkey | ✔ executed after approval | [tx](https://sepolia.basescan.org/tx/0x48275c3c2449841416d064b660a09eb2d0eb620b8502b837ab4afd4642d3e48c) |
  64. | Owner clicks Revoke (passkey-signed userOp via bundler) | ✔ revoked; the agent's next attempt is refused | [tx](https://sepolia.basescan.org/tx/0x8ee0aa16145b38a0f260cdcc2b0e16901f67faae23296cf95290d599c900bbee) |
  65. The demo agent was also run with the real Claude model (`claude-opus-5-5`, `pnpm demo:selftest`, on a local
  66. Base Sepolia fork). It paid the two routine invoices alone, waited for the owner's passkey approval on the 4 USDC
  67. invoice, and was blocked when it tried to pay the denylisted vendor. On-chain balances confirmed each outcome.
  68. **Public instance with a real phone** (2026-11-21). A self-hosted instance behind HTTPS, the owner on a phone with a
  69. synced passkey, and the real Claude agent (`claude-opus-5-5`) paying four invoices from the owner's account
  70. [0x58Df…EC29](https://sepolia.basescan.org/address/0x58Dfa6C6F5b910f3ae24D2C93BcAf8F46d1bEC29):
  71. | Invoice | Result | Transaction |
  72. | ----------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
  73. | 1.20 USDC · API usage | ✔ paid by the agent alone | [tx](https://sepolia.basescan.org/tx/0xe4f89770842ce13e1f320afa22ebcee5e6e9c12343def588e0e855088eccd862) |
  74. | 0.0005 ETH · GPU time | ✔ paid by the agent alone | [tx](https://sepolia.basescan.org/tx/0x62420fe16650974ffdc911d0e65d16bb523c1488c48119fd14dea8404b9426f6) |
  75. | 4.00 USDC · annual plan | ✔ approved with Face ID on the phone, then paid | [tx](https://sepolia.basescan.org/tx/0xab39a007ae8dcde213d088442e8c790e4773cf8fef896cde4dfc481c8df36ee9) |
  76. | 0.0003 ETH · denylisted | ✘ blocked; Claude didn't retry and flagged the vendor | n/a |
  77. **Recovery without cyphos-guard** (2026-11-21). With the [recovery page](apps/recovery) (static, at
  78. cyphosguard.com/recover/), the owner's recovery wallet (a MetaMask account, EIP-7702-upgraded) emptied that same account:
  79. no service, no passkey, no bundler. The wallet signed the UserOperation and submitted it itself
  80. ([tx](https://sepolia.basescan.org/tx/0x16b461ccbdf1e9416fa1ee1c1434d8ba5e44a787fe72f73771e570053b91e9a4): 14.8 USDC
  81. and the remaining ETH to the recovery address; the account is now empty).
  82. **x402 with a vault, live** (2026-11-21, `pnpm --filter @cyphos-guard/x402-seller buy`). The agent paid an x402 API
  83. (the [demo seller](examples/x402-seller/src/main.ts), settled by the public x402.org testnet facilitator) from the
  84. owner's account [0x13fE…127A](https://sepolia.basescan.org/address/0x13fED70ad7b46E2c14bc418b7E7D32565bDf127A) through
  85. its X402Vault [0x6563…8Fc0](https://sepolia.basescan.org/address/0x6563dDa8a8d1Daee0aCE8d17E460DbD01C548Fc0), created at
  86. grant time. Afterwards vault and agent held 0 USDC: only the price moved, just in time.
  87. | API call | Result | Transaction |
  88. | ----------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
  89. | Market data · 0.50 USDC | ✔ paid alone (within limits) | [tx](https://sepolia.basescan.org/tx/0x91c3ea9ceaae852df8cb492c4ea68da6afa423fe5c398309b8a1f087c77ea692) |
  90. | Deep report · 3 USDC | ✔ approved with a passkey on a phone, then paid | [tx](https://sepolia.basescan.org/tx/0x076c13d962f42b4b5d17fdb467d58c7b200e4998d9354783afd464dd37644ffc) |
  91. ## Use it from your agent
  92. The packages are on npm (Node ≥ 22.18, Base Sepolia testnet only):
  93. ```sh
  94. npm i @cyphos-guard/sdk viem # SDK for your agent
  95. npx @cyphos-guard/cli agent new # create the agent's key (see below)
  96. npx -y @cyphos-guard/mcp # MCP server for Claude & co. (see below)
  97. ```
  98. ### Create the agent's key
  99. The agent has its own key pair. The agent's developer creates it where the agent runs and gives the **owner only the
  100. address**. cyphos-guard never sees the key, and the key holds no owner funds (just a little gas):
  101. ```sh
  102. npx @cyphos-guard/cli agent new --env agent.env --approver https://your-approver.example
  103. # Agent address 0x9520…0b01 ← give this to the owner, who grants it limits with their passkey
  104. # Private key stored in agent.env as CYPHOS_AGENT_PRIVATE_KEY (mode 600, never printed)
  105. npx @cyphos-guard/cli agent show --env agent.env # address + gas balance
  106. ```
  107. It refuses to overwrite an existing key (`--force` replaces it and prints the old address) and warns if the file is in
  108. a git repo but not ignored. For production, a KMS or server-wallet key works just as well: only its address matters.
  109. ### Call the SDK
  110. ```ts
  111. import { createCyphosGuard, ApprovalPending, PolicyViolation } from "@cyphos-guard/sdk";
  112. const pw = createCyphosGuard({ policyServiceUrl, agent: privateKeyToAccount(AGENT_KEY) });
  113. try {
  114. const { txHash } = await pw.execute({ to: vendor, value: parseEther("0.0005"), reason: "GPU credits" });
  115. } catch (e) {
  116. if (e instanceof ApprovalPending)
  117. await pw.waitForApproval(e.request.id); // owner approves with passkey
  118. else if (e instanceof PolicyViolation)
  119. console.log("not allowed:", e.reason); // forbidden / over_hard_max / no_grant
  120. else throw e;
  121. }
  122. ```
  123. [SDK quickstart & API reference](packages/sdk/README.md) · [policy examples](docs/policy-examples.md)
  124. ### …or from any MCP agent
  125. The [cyphos-guard MCP server](packages/mcp/README.md) gives Claude Code, Claude Desktop and other MCP clients the tools
  126. `get_wallet_status`, `pay`, `call_contract`, `fetch_paid_api` (x402), `check_approval` and `list_activity`. They're
  127. backed by the same three layers:
  128. ```sh
  129. claude mcp add cyphos-guard -e CYPHOS_AGENT_PRIVATE_KEY=0x… -e NETWORK=live \
  130. -e CYPHOS_POLICY_SERVICE_URL=https://app.cyphosguard.com/api -- npx -y @cyphos-guard/mcp
  131. ```
  132. Also listed in the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.Phosse136/cyphos-guard`.
  133. ### …and pay x402 APIs
  134. [x402](https://docs.x402.org) lets APIs charge per request over HTTP 402. With an `x402` permission, the agent pays
  135. allowed sellers within your limits, asks you above them, and never pays a forbidden seller:
  136. ```ts
  137. const { response, paid } = await pw.payX402("https://api.example/report", {}, { reason: "weekly market report" });
  138. ```
  139. How it works: an x402 payment must be signed by the payer, and only your passkey can sign for your account. So when
  140. you grant x402, the SDK deploys a small **vault contract** for that agent (one extra passkey confirmation). Each payment
  141. moves exactly the price from your account into the vault, and the agent signs the x402 payment _as the vault_. The vault
  142. ([X402Vault.sol](packages/contracts/src/X402Vault.sol), ERC-1271) only approves a USDC payment to a **listed seller**, up
  143. to its cap, signed by the agent. Everything else is refused, including any other kind of signature request.
  144. | Rule | Enforced |
  145. | -------------------------------- | -------------------------------------------------------------------------------------------------- |
  146. | Which sellers may be paid | **on-chain** (vault). Unlisted sellers can't be paid, not even with approval: add them to the list |
  147. | Largest single payment | **on-chain** (vault cap = your "ask me up to" maximum) |
  148. | Total x402 spend per period | **on-chain** (top-ups only into the vault, period cap) |
  149. | Routine vs. "ask me" per payment | SDK + escalation; binding on-chain too if you enable the co-signer |
  150. So a **stolen agent key can only pay your listed sellers**, within your caps. The vault is owned by your account: you
  151. can withdraw from it anytime (normally it's empty, because it's topped up just before each payment).
  152. Verified against the official x402 server and facilitator (`@x402/core` / `@x402/evm` 2.30) on a Base Sepolia fork
  153. with real USDC: vault deployment at grant time, routine payment, escalation with approval, unlisted seller refused before
  154. any money moves, and the vault refusing unlisted sellers, over-cap amounts and foreign signatures even when asked
  155. directly ([integration test](examples/x402-seller/src/x402.fork.test.ts),
  156. [vault test](examples/x402-seller/src/vault.fork.test.ts)). **The vault contract is new and not audited**; see the
  157. [internal security review](docs/security/x402-vault-review.md).
  158. ## How it works
  159. ```mermaid
  160. flowchart LR
  161. subgraph Owner["Owner (browser)"]
  162. A["Approver app<br/>passkey (WebAuthn)"]
  163. end
  164. subgraph Agent["Agent process"]
  165. G["AI agent + @cyphos-guard/sdk<br/>own EOA key"]
  166. end
  167. subgraph PS["policy-service (self-hosted)"]
  168. Q["approval queue · grants · activity<br/>holds no keys"]
  169. end
  170. subgraph Chain["Base Sepolia"]
  171. DM["DelegationManager<br/>+ caveat enforcers"]
  172. SA["Owner's Hybrid smart account<br/>(passkey + recovery EOA)"]
  173. R["Recipients"]
  174. EP["EntryPoint (ERC-4337)"]
  175. end
  176. A -- "grant: passkey-signed delegations" --> Q
  177. G -- "1 · redeem delegation (plain tx, agent pays gas)" --> DM
  178. DM -- "caveats pass → execute" --> SA --> R
  179. G -- "2 · above limits: approval request (signed)" --> Q
  180. Q -- "pending request" --> A
  181. A -- "one-shot delegation: exact call, once, minutes" --> Q
  182. Q -- "approved" --> G
  183. A -- "revoke: passkey-signed userOp (bundler)" --> EP --> SA
  184. ```
  185. - Your account is a **MetaMask Hybrid smart account** owned by your passkey, with an optional recovery EOA.
  186. - A grant is a set of **delegations** (ERC-7710, [MetaMask Delegation Framework](https://github.com/MetaMask/delegation-framework),
  187. audited). Each carries on-chain **caveats**: recipients, functions, per-tx and per-period caps, expiry.
  188. - The agent redeems delegations with **ordinary transactions from its own key**. No bundler, and it can't drain
  189. your account through gas.
  190. - Above its limits, the SDK files an **approval request**. Your passkey signs a **one-shot delegation**: exactly
  191. that call, usable once, valid for minutes. It can't be replayed or widened.
  192. - **Hybrid enforcement.** Hard caps live on-chain. The policy service only refuses or escalates: it holds no key that
  193. can move funds, can't widen a grant, and isn't needed to revoke.
  194. - **Optional co-signer** ([ADR 0005](docs/decisions/0005-cosigner-enforcer.md)). cyphos-guard's own `CosignerEnforcer` makes
  195. the rules the chain can't express (ERC-20 per-payment caps, range checks) binding: each redemption needs a fresh
  196. co-signature for that exact call, and the service only co-signs within policy. The co-signer can only block.
  197. Design records: [account stack](docs/decisions/0001-account-stack.md) ·
  198. [policy schema](docs/decisions/0002-policy-schema.md) ·
  199. [owner actions](docs/decisions/0003-owner-actions-without-bundler.md) ·
  200. [approval flow & trust model](docs/decisions/0004-approval-flow.md) ·
  201. [co-signer](docs/decisions/0005-cosigner-enforcer.md) · [security](SECURITY.md)
  202. | Pending approval (decoded locally from what will be signed) | Activity after the demo run |
  203. | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
  204. | ![Pending approval: Pay 4 USDC, with the agent's reason](docs/assets/demo-2-pending-approval.png) | ![Activity: paid within limits, approved, blocked by policy](docs/assets/demo-3-activity.png) |
  205. ## What is the co-signer?
  206. The co-signer is an optional second signature that cyphos-guard adds to every payment an agent makes. Think of a
  207. bank that requires two signatures on a cheque, except that the second signer can only say "no", never "yes" on its own.
  208. **The problem it solves.** An agent's limits come in two kinds:
  209. - **Limits the smart contracts enforce directly**, such as "max 5 USDC per day" or "only pay this address". The
  210. blockchain refuses anything outside them, whatever the agent does.
  211. - **Limits the contracts can't express**, such as "max 2 USDC _per payment_" for tokens, or "amount must be below X".
  212. Without the co-signer only the SDK checks these, inside the agent's own program. A hacked or buggy agent could skip
  213. the SDK and use its signed permission directly, and the blockchain would let the payment through.
  214. **How it fixes that**
  215. 1. You grant an agent permissions with the co-signer turned on (the "Require the cyphos-guard co-signer" checkbox in
  216. the approver). The permission then says that every payment also needs a fresh signature from the co-signer.
  217. 2. Before each payment, the agent asks the cyphos-guard policy service to co-sign it.
  218. 3. The service checks the payment against all the rules, including the ones the contracts can't express, and only
  219. signs if everything is fine.
  220. 4. The agent attaches the signature and sends the payment. cyphos-guard's own smart contract, the
  221. [`CosignerEnforcer`](packages/contracts/src/CosignerEnforcer.sol), checks on-chain that the signature is genuine,
  222. fresh and for exactly this payment.
  223. A hacked agent that tries to skip the rules fails on-chain because it has no valid co-signature (see the
  224. [live co-signer scenario](#verified-on-base-sepolia) above: `missing-cosignature`, `invalid-cosignature` and so on).
  225. **Why it's safe.** The co-signer **can only block, never move money.** Its signature alone does nothing: a payment
  226. still needs the agent's key and your passkey-signed permission, and every on-chain limit still applies. In the live
  227. test, a valid co-signature couldn't get past the daily cap. If the co-signer key were ever stolen, the worst case is
  228. that the extra rules stop working; your on-chain limits still hold.
  229. **The trade-off.** If the policy service is down, a co-signed agent can't make payments on its own until it's back.
  230. Your approvals and revocations keep working. That's why it's a checkbox: you choose between stricter safety and
  231. independence from the service. Design details: [ADR 0005](docs/decisions/0005-cosigner-enforcer.md).
  232. ## Why cyphos-guard
  233. cyphos-guard builds on the same primitive as MetaMask's Advanced Permissions, the Delegation Framework, and adds
  234. the parts an agent operator needs around it.
  235. | | **cyphos-guard** | **MetaMask Advanced Permissions** (ERC-7715) | **Fireblocks Agent Wallets** |
  236. | ----------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
  237. | Built for | Indie devs and small teams running their own agents | Dapps and agents requesting permissions from MetaMask users | Fintechs and payment providers issuing wallets to their end users |
  238. | Owner's side | A browser and a passkey | MetaMask extension (v13.23+) and an account upgraded to a MetaMask smart account | Wallets issued by the fintech on the Fireblocks platform (powered by Dynamic) |
  239. | Custody | Non-custodial smart account (passkey + optional recovery EOA) | User's MetaMask smart account | Users keep custody via MPC key management (per Fireblocks) |
  240. | Limits | On-chain caveats: per-tx / per-period caps, recipients, functions, argument pins, expiry | Spending and periodic permissions granted up front in the extension | Policy engine checks agent transactions before signing |
  241. | Above the limit | **Live escalation**: request → passkey approval → one-shot delegation | Not part of ERC-7715 itself (it defines permission requests) | Policy-engine rules (see Fireblocks docs) |
  242. | Forbidden actions | Denylist + hard maximums; never escalated | Whatever the granted permission excludes | Policy-engine rules |
  243. | Open source / self-host | Yes (Apache-2.0), self-hosted service + app | SDK and contracts open source; the extension is MetaMask's | Commercial platform |
  244. Sources: [MetaMask Advanced Permissions docs](https://docs.metamask.io/smart-accounts-kit/concepts/advanced-permissions/),
  245. [MetaMask support: Advanced Permissions](https://support.metamask.io/more-web3/dapps/advanced-permissions/),
  246. [Fireblocks agentic infrastructure](https://www.fireblocks.com/solutions/agentic-digital-asset-infrastructure),
  247. [Fireblocks Agentic Payments Suite](https://fireblocks.com/blog/agentic-payments-suite-psp-fintech) (checked November 2026;
  248. corrections welcome).
  249. ## Roadmap
  250. **Done recently**
  251. - **MCP server** ([packages/mcp](packages/mcp/README.md)). Any MCP-capable agent can pay under cyphos-guard's rules.
  252. - **Live Base Sepolia guide** ([docs/live-guide.md](docs/live-guide.md)). The full approver flow runs on live Base Sepolia.
  253. - **Co-signer enforcer** ([ADR 0005](docs/decisions/0005-cosigner-enforcer.md)). An optional caveat that requires a fresh
  254. policy-service signature per redemption. It makes ERC-20 per-payment caps and range checks on arguments binding
  255. even for a compromised agent, while the co-signer still can't move funds.
  256. - **x402**: agents pay HTTP 402 APIs within your limits (`payX402`, MCP `fetch_paid_api`); an X402Vault per agent
  257. enforces the seller list on-chain.
  258. **Next**
  259. - Several ERC-20 recipients per permission (`LogicalOrWrapperEnforcer`), batch approvals, web push notifications.
  260. - Gasless revoke through a paymaster, plus a pinned or IPFS approver build so you don't have to trust a host.
  261. **Smart rules**
  262. - Swap guardrails: max slippage, allowed pools and tokens.
  263. - Market and protocol risk: pause on APY swings, depegs or protocol incidents.
  264. - Anomaly detection on agent behavior: unusual rate, new counterparties, off-hours spending, with automatic escalation.
  265. **Wider support**
  266. - Wallet-agnostic adapters behind the same policy schema (e.g. ERC-7579 smart sessions, ZeroDev Kernel).
  267. **Not planned:** a token, a DAO, or mainnet before an independent audit.
  268. ## Repo layout
  269. ```
  270. apps/approver Next.js owner app: passkey login, approvals, grants, revoke, activity
  271. apps/policy-service approval queue · grant registry · activity (Hono + node:sqlite), holds no keys
  272. packages/cli cyphos-guard CLI: `agent new` / `agent show` (agent key, kept by the agent's developer)
  273. examples/x402-seller x402 seller on the official x402 server logic (tests, live demo)
  274. packages/contracts CosignerEnforcer + X402Vault (Foundry, on Delegation Framework v1.3.0 as submodule)
  275. packages/mcp MCP server (pay, check_approval, … for Claude Code / Claude Desktop)
  276. packages/sdk @cyphos-guard/sdk: createCyphosGuard, policy compiler, co-signer, typed errors
  277. packages/shared policy schema (zod), API types, escalation and off-chain checks
  278. examples/poc Phase 1 proof of concept + passkey spike + e2e escalation flow
  279. examples/demo-agent Claude accounts-payable agent (Messages API tool runner)
  280. docs/ ADRs, policy examples, demo script, assets
  281. ```
  282. ## Development
  283. ```sh
  284. git submodule update --init --recursive # once, for packages/contracts
  285. pnpm lint && pnpm typecheck && pnpm test # offline
  286. pnpm contracts:test # Foundry tests
  287. pnpm test:fork # SDK integration tests on a fork
  288. pnpm e2e && pnpm demo:selftest --fake-model # end-to-end flows on a fork
  289. pnpm e2e:browser && pnpm e2e:demo # approver in Chromium with a virtual passkey
  290. ```
  291. See [CONTRIBUTING.md](CONTRIBUTING.md). Commits are scanned for secrets (pre-commit hook + gitleaks).
  292. ## License
  293. [Apache License 2.0](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.