KeeperGate — fail-closed execution assurance for AI agents

Decide locally. Execute through KeeperHub. Prove what actually landed onchain.

KeeperGate is an execution boundary for AI agents. It validates transaction intent, enforces cumulative policy, prevents duplicate submission, routes approved writes through KeeperHub, reconciles KeeperHub execution with an independent Sepolia RPC, and emits a tamper-evident evidence record.

The central invariant is simple: no confirmed receipt, no claim of execution. Demo mode never fabricates transaction hashes. Live failures stop closed.

Why this is different

KeeperHub already provides secure wallets, gas management, retries, and agentic-wallet payment limits. KeeperGate does not replace those controls. It adds application-level assurance around an agent's business intent:

• token units are separated from USD policy value (amount vs amountUsd);
• the 24-hour budget is cumulative per agent, not a per-transaction label;
• denylist matching is exact, avoiding prefix false positives;
• out-of-policy requests enter a real approve/reject flow;
• caller retries reuse an idempotency key instead of broadcasting twice;
• concurrent retries compete for an atomic idempotency claim before execution;
• KeeperHub execute_workflow is reconciled through get_execution;
• a transaction is confirmed only after an independent Sepolia receipt succeeds;
• every record receives a canonical SHA-256 evidence hash and verify URL.

Architecture

Agent / ElizaOS
      |
      |  intent + amountUsd + idempotencyKey
      v
@keepergate/sdk  -- backend unavailable --> FAIL CLOSED
      |
      v
KeeperGate API
  1. validate address / amount / calldata shape
  2. exact denylist + allowlist + cumulative 24h budget
  3. block | request human approval | approve
      |
      | approved live intent only
      v
KeeperHub MCP
  execute_workflow -> get_execution -> canonical tx hash
      |
      v
Independent Sepolia JSON-RPC receipt check
      |
      v
SHA-256 evidence record -> /api/evidence/verify/:id

KeeperHub remains the execution layer and signer. KeeperGate never accepts a private key.

Verify in 60 seconds

Requires Node.js 20 or newer.

git clone https://github.com/xDzaky/KeeperGate.git
cd KeeperGate
npm ci
npm run check

npm run check runs workspace typechecks, the seven-request integration flow, all package builds, and the production dashboard build. The integration test deliberately uses demo mode and asserts:

• five policy scenarios return their expected decisions;
• demo approval has executionStatus=simulated;
• demo approval has txHash=null;
• the evidence pack reports zero confirmed transactions;
• repeating the same idempotency key returns the original record.

Run the dashboard

One-command judge start:

./start.sh

Or run both development processes directly:

cp backend/.env.example backend/.env
npm run dev

• Dashboard: http://localhost:3000
• API: http://localhost:3001
• Evidence: http://localhost:3001/api/evidence
• Submission proof: http://localhost:3001/api/submission

The homepage includes a one-click Run judge tour. Complete SDK, ElizaOS, CLI, approval, production, and troubleshooting instructions are in docs/USAGE.md. Reviewers can use JUDGE_GUIDE.md.

Run live through KeeperHub

Set these in backend/.env:

DEMO_MODE=false
STRICT_MODE=true
KEEPERHUB_API_KEY=kh_...
KEEPERHUB_WORKFLOW_ID=...
KEEPERHUB_WALLET_INTEGRATION_ID=...
TURNKEY_WALLET_ADDRESS=0x...
KEEPERGATE_GATE_TOKEN=<random-client-token>
KEEPERGATE_ADMIN_TOKEN=<different-random-admin-token>
SEPOLIA_RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
PUBLIC_URL=https://api.example.com
FRONTEND_URLS=https://dashboard.example.com

Then submit a uniquely keyed intent:

curl -X POST http://localhost:3001/api/gate/intercept \
  -H 'content-type: application/json' \
  -H 'x-agent-id: judge-demo-agent' \
  -H 'authorization: Bearer <gate-token>' \
  -d '{
    "to":"0x1111111111111111111111111111111111111111",
    "amount":"0.0001",
    "amountUsd":0.25,
    "token":"ETH",
    "idempotencyKey":"judge-demo-2026-001",
    "intent":"Demonstrate a guarded Sepolia transfer"
  }'

Possible execution states:

State	Meaning	Transaction claim
not_submitted	blocked or waiting for approval	none
simulated	demo policy passed	none
submitted	KeeperHub accepted the run; receipt not yet confirmed	no confirmed claim
confirmed	KeeperHub hash has a successful Sepolia receipt	explorer link shown
failed	KeeperHub or the onchain receipt failed	none

Human approval

An over-budget or non-allowlisted request returns HTTP 202 and a txId. An operator can approve or reject it with the admin token:

curl -X POST http://localhost:3001/api/gate/<txId>/approve \
  -H 'authorization: Bearer <admin-token>'

curl -X POST http://localhost:3001/api/gate/<txId>/reject \
  -H 'authorization: Bearer <admin-token>'

Approval executes once through the same KeeperHub reconciliation path. Rejection never touches KeeperHub.

Evidence API

curl http://localhost:3001/api/evidence
curl http://localhost:3001/api/evidence/verify/<record-id>
curl http://localhost:3001/api/evidence/download > keepergate-evidence.json
curl -X POST http://localhost:3001/api/evidence/reconcile/<submitted-record-id> \
  -H 'authorization: Bearer <admin-token>'

The evidence hash commits to the intent, decision, workflow ID, execution ID, execution state, mode, and transaction hash. Changing any committed field invalidates verification.

GET /api/submission separately re-checks the public historical transaction through the configured Sepolia RPC. It labels that receipt as pre-Evidence-v2 and never attaches it to demo records.

Historical KeeperHub execution

The earlier prototype produced this KeeperHub-linked Sepolia transaction:

• KeeperHub workflow: mnsqq9gybo6gr4lcs4knx
• KeeperHub execution ID: tt0c632aqtwgv3qruccyt
• Sepolia transaction: 0x91a9073b…f50f50b

An independent JSON-RPC check confirms chain ID 11155111 and a successful receipt. Correction to the original prototype notes: the outer sponsored/relayed transaction has zero native value and targets an execution contract; it is not a direct 0.0001 ETH self-transfer. A fresh v0.3 live run should be captured for final judging so the evidence format, KeeperHub run, and chain receipt all correspond to the submitted code.

Packages

Path	Purpose
backend/	policy, KeeperHub MCP client, reconciliation, evidence API
packages/sdk/	fail-closed TypeScript client
packages/plugin-eliza/	ElizaOS secure-transfer action
packages/dashboard/	simulation, policy, and evidence UI
packages/scaffold/	safe onboarding CLI; never invents a workflow or tx hash
test/run.mjs	self-contained integration test

Submission artefacts: DORAHACKS_SUBMISSION.md, JUDGE_GUIDE.md, and CHANGELOG.md.

Security model

• no private key or seed phrase is accepted;
• the SDK never sends a KeeperHub API key to the proxy;
• live execution errors cannot fall back to an approved fake result;
• demo and live evidence are distinguishable in storage and UI;
• the public Simulation Lab is permanently dry-run and cannot call KeeperHub, even when the backend is live;
• policy writes and human approvals require an admin token;
• production gate access requires a separate client token;
• production refuses missing or identical gate/admin tokens;
• dashboard origins are explicitly allowlisted and API responses include baseline security headers;
• mutating API requests receive request IDs and a bounded per-client write rate;
• malformed EVM addresses, decimal amounts, and calldata are rejected;
• CI rejects known private-key and fake-hash generator patterns.

See SECURITY.md before using any wallet associated with an earlier revision.

Honest limitations and submission status

• The dashboard is a local judging surface; no public deployment is included yet.
• The DoraHacks BUIDL form still needs to be completed on the platform.
• The historical transaction predates evidence v2; capture a new live run after rotating credentials.
• USD valuation is supplied by the caller. A production deployment should bind it to a trusted oracle quote and expiry.
• The current workflow executes a native transfer. ERC-20 and arbitrary contract calls need asset-specific workflow templates.
• Private routing, gas strategy, and transaction ordering are KeeperHub guarantees; KeeperGate records their execution result but does not reimplement them.
• The dashboard temporarily pins Next.js 16.3.0-preview.8, the first release outside the current high-severity advisory range; move to the corresponding stable release as soon as it is published. Production dependencies currently audit clean. A low-severity Windows-only esbuild dev-server advisory remains in tsup's build-time dependency tree.

License

MIT

Submission preflight

npm run submit:check

This runs typechecks, integration tests, every workspace build, the production dependency audit, and current-tree submission/secret checks.