Put your agent on a leash
Wrap an x402 client with the SDK, or let an LLM pay only through the MCP server. Merchants declare themselves in ENSv2 to be recognised.
Run the stack
Node 22.13 or later and pnpm. Everything runs on public testnets with test tokens.
git clone https://github.com/arijitroy667/Leash
cd Leash && pnpm install
pnpm test # engine, guard and MCP tests, no network
cp .env.example .env # funders, Arkiv key, Sepolia wallets
pnpm wallets:create && pnpm wallets:fund && pnpm wallets:check
pnpm hcs:create && pnpm ens:setup
pnpm --filter @leash/dashboard dev # this site, with the owner console, on :3100SDK: guard a real x402 client
The guard hooks the client's payment creation, decides before anything is signed, and files a signed report after delivery. Use guardedFetch so the guard knows the real origin; a call around it has none, and always escalates.
import { wrapFetchWithPayment } from "@x402/fetch";
import { createLeashGuard, rawClient, LeashDenied, LeashEscalated } from "@leash/guard";
const guard = createLeashGuard({
agent: "agent-a", // a label for this agent's ledger and audit trail
hederaAccount: process.env.AGENT_A_ACCOUNT!,
hederaKey: process.env.AGENT_A_KEY!, // signs payments and the agent's own reports
ownerAddress: process.env.LEASH_OWNER_ADDRESS as `0x${string}`,
arkivAccessKey: process.env.ARKIV_ACCESS_KEY!,
namespace: "mumbai-1", // which shared registry to read and write
hcsTopicId: process.env.HCS_TOPIC_ID, // optional audit trail on Hedera Consensus Service
});
// A real x402 client for Hedera. Its own spend controls are off: the guard decides everything.
const client = rawClient(process.env.AGENT_A_ACCOUNT!, process.env.AGENT_A_KEY!);
guard.attach(client);
const paidFetch = guard.guardedFetch(wrapFetchWithPayment(fetch, client));try {
const res = await paidFetch("https://leash-merchant-weather.vercel.app/forecast");
console.log(res.leash); // { decisionId, txId, delivered }
} catch (e) {
if (e instanceof LeashEscalated) {
// The owner signs in the console. Retry the same URL once approved.
await guard.waitForApproval(e.approvalId, 120_000);
} else if (e instanceof LeashDenied) {
console.log(e.decision.reasons); // e.g. ["blocked"] or ["declared-mismatch"]
} else throw e;
}const d = await guard.check({ url, requirements }); // a dry run: the verdict, nothing paid
guard.explain(d.id); // factors, limits, reasons, latency
await guard.merchant("0.0.11323814"); // a payee's verified standing| Field | What it does |
|---|---|
agent | Label for this agent's ledger, approvals and audit messages |
hederaAccount, hederaKey | The paying wallet. The key signs payments and the agent's reports |
ownerAddress | The only wallet whose signature can release an escalated payment |
arkivAccessKey, namespace | The registry to read and write |
policy or policyProfile | production (default) or a tuned live clock |
limits | Override the per-call ceiling, budgets, thresholds or replay window |
hcsTopicId | Optional audit topic |
proberAddresses | Arkiv addresses whose probes count |
mode | enforce (default) or observe: decide and log, never block |
awaitApprovalMs | Wait this long for the owner before throwing LeashEscalated |
autoReport | File reports after each paid call (default true) |
A developer can still call the raw client, so the SDK does not prevent bypass. The MCP server does.
MCP server: the LLM pays only through Leash
The server holds the signer. There is no approve tool, results carry structured fields only, and the body of a paid call comes back length-capped and marked untrusted: true. It speaks MCP over stdio and logs to stderr.
pnpm --dir starts the server in the repo, so it finds .env and shares the console's database: an approval you sign there reaches the server.
{
"mcpServers": {
"leash": {
"command": "pnpm",
"args": ["--dir", "/path/to/Leash", "exec", "tsx", "packages/mcp/src/server.ts"],
"env": { "LEASH_MCP_AGENT": "C" }
}
}
}"command": "cmd",
"args": ["/c", "pnpm", "--dir", "C:/path/to/Leash", "exec", "tsx", "packages/mcp/src/server.ts"]claude mcp add leash -e LEASH_MCP_AGENT=C -- pnpm --dir /path/to/Leash exec tsx packages/mcp/src/server.ts| Tool | Input | Returns |
|---|---|---|
leash_pay_request | url, method, maxUsd, idempotencyKey? | paid (with an untrusted body), pending_approval, denied, no_payment, unconfirmed, failed |
leash_check_merchant | key: ENS name, domain or account | standing, factors, strikes, block and hold ends, rebuttal |
leash_explain_decision | decisionId | the stored decision: reasons, factors, limits, latency |
leash_report_outcome | txId, outcome | queued, already-filed or refused; reports are filed automatically |
leash_list_pending_approvals | none | structured cards: merchant, standing, amount, score, reasons |
leash_await_approval | approvalId, timeoutMs (up to 55 s) | approved, rejected, expired or still_pending; it cannot approve |
leash_get_budget | none | session and daily budget, and spend per merchant |
On pending_approval, call leash_await_approval, then leash_pay_request again with the same URL. The owner signs in the console.
Merchants: declare yourself in ENSv2
Set leash.* text records on your name's resolver, and name yourself in each 402. Without a declaration every payment to you asks the agent's owner; with one, a NEW merchant can take micro payments straight away, and a 402 that contradicts it is denied as a spoof.
leash.payTo 0.0.11323813
leash.network hedera:testnet
leash.asset 0.0.429274
leash.maxPrice 0.25
leash.domains https://leash-merchant-weather.vercel.app
leash.schema city,tempC,conditions
leash.probeUrl https://leash-merchant-weather.vercel.app/forecast
leash.policyVersion 1793897963// In the merchant's x402 route config: name yourself in the 402.
price: { asset: "0.0.429274", amount: "5000", extra: { leashEns: "leash-weather.eth" } }To file rebuttals, grant ROLE_SET_TEXT for only the leash.rebuttal key to the wallet that will sign them. A rebuttal never unblocks by itself: it buys one paid probe of your leash.probeUrl, which must return what leash.schema declares.
Read the registry yourself
The registry is public. Anyone can read it with no key or wallet, and anyone can write to it, which is why every reader re-verifies each row against Mirror Node before it counts.
npx tsx apps/demo/src/arkiv-query.ts mumbai-prod 0.0.11323813Schema: arkiv/schema.md. How the decision uses it: proof of payment.