Valet

Give an AI agent a wallet without giving it your keys.

Valet is a spending guard for AI agents on NEAR. The agent never holds a key that can move your funds. It holds a function-call access key that can do exactly one thing: call pay on a vault contract. The vault enforces your limits on-chain, and an oracle checks every receiver before the agent is allowed to sign.

Screenshots of the real console against a real local NEAR chain. Play the same story in your browser: a replay of a recorded session, nothing to install.

Built at NEAR HACKATHON, in the AI Security & Defense track, and also entered in Agent Economy (what it covers there). Everything below runs locally on a real NEAR chain (nearcore 2.14.0, the runtime mainnet uses today). No accounts, no API keys, no funds. The same story also ran on the public NEAR testnet, with an explorer link for every transaction: docs/testnet-run.md.

Watch the short video (under two minutes) of the web console against the real local chain (the AI agent's decisions are scripted buttons; the vault, oracle and chain are real), or read how a real AI agent fared when Claude Code was pointed at the same vault.

                        prompt injection, scam invoice, poisoned web page ...
                                          |
   LLM agent  --valet_pay(receiver, amount)-->  ValetAgent (wrapper)
                                                   |  1. ask the oracle: allow / warn / block + reasons
                                                   |  2. block -> refuse, warn -> ask the human
                                                   |  3. sign with the function-call key
                                                   v
   Oracle (signs verdicts)  <---------------  guard contract (the vault)  ---> receiver
     account age/activity, lookalikes,          per-tx cap, rolling window cap, allow/deny lists,
     contract code changes, history,            oracle-signed attestation for strangers,
     shared blocklist with evidence             approval queue for `warn`, kill switch

Try it

Requirements: Node.js >= 22. The unit tests and npm run lookup run anywhere. The chain parts (demo, sandbox, test:e2e) start a real local NEAR node, near-sandbox 2.14.0, which runs on macOS with Apple silicon and on Linux (x64 or arm64) with glibc 2.39 or newer (Ubuntu 24.04, Debian 13, Fedora 40). On anything else (an Intel Mac, Debian 12, Ubuntu 22.04) use Docker; if the node cannot start, the program says why and what to do instead of failing with an exit code. The contracts are committed as prebuilt wasm, so no Rust is needed.

npm ci
npm run test:unit    # about 5 seconds: 205 unit tests (oracle risk engine, agent wrapper, MCP server, console, testnet script, replay page)
npm run demo         # about 1 minute: a hijacked agent against a real local chain
npm run test:e2e     # about 10 minutes: 50 tests, 42 of them on a real local chain
npm run sandbox      # a local chain that stays up: a web console to play with (see "Try it in your browser") and an MCP server for a real AI agent
npm run testnet      # about 3 minutes: the same story on the public NEAR testnet (needs a network, no local node)

npm run testnet asks the public testnet faucet for one account and builds everything under it: real accounts, both contracts, an explorer link for every transaction, a Markdown record in .valet/testnet/. It uses testnet NEAR only, and its keys are generated per run and stay on your machine. npm run testnet -- --rehearsal runs the same script on a local chain. A recorded run is in docs/testnet-run.md.

The first run of demo or test:e2e downloads the near-sandbox 2.14.0 binary once (about 30 MB, SHA-256 checked) into packages/e2e/.cache/. Why not the one bundled with near-workspaces: it is nearcore 2.6.2 and rejects the committed wasm (see Runtime note). On another platform, point NEAR_SANDBOX_BINARY_PATH at a directory that contains a near-sandbox >= 2.14.

The repository's .npmrc sets ignore-scripts=true: no dependency runs code at install time (the near-sandbox package would otherwise fetch that 2.6.2 binary), and npm ci takes about 10 seconds.

With Docker

docker build -t valet .            # Debian 13 + Node 22; npm ci; fetches the pinned sandbox binary once
docker run --rm valet              # the attack demo (no network needed)
docker run --rm valet npm run test:unit
docker run --rm valet npm run test:e2e
docker run --rm -it -p 127.0.0.1:8787:8787 -e VALET_CONSOLE_HOST=0.0.0.0 -e VALET_CONSOLE_PORT=8787 \
  valet npm run sandbox            # the web console: open the link it prints

Publish the same port number on both sides of -p: the console only answers requests addressed to its own port. CI runs typecheck, the unit tests and the demo on Ubuntu 24.04 for every push; the end-to-end tests run in a second workflow.

Try the oracle on real mainnet accounts

The counterparty check needs no vault, no account and no funds: it works on any account of the real network (public RPC and the Nearblocks API, read-only).

npm run lookup -- wrap.near
npm run lookup -- v2.ref-finance.near
npm run lookup -- wrap.nearr           # a lookalike of wrap.near that nobody registered

Captured on 2026-11-10. This reads live data, so what you see will drift:

This is the beginning of the README. Read the rest at the original. Read the full README ↗