Integrate

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.

Start here

Run the stack

Node 22.13 or later and pnpm. Everything runs on public testnets with test tokens.

Terminal
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 :3100
@leash/guard

SDK: 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.

Set up · TypeScript
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));
Pay · TypeScript
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;
}
Dry runs and explanations · TypeScript
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
Configuration
FieldWhat it does
agentLabel for this agent's ledger, approvals and audit messages
hederaAccount, hederaKeyThe paying wallet. The key signs payments and the agent's reports
ownerAddressThe only wallet whose signature can release an escalated payment
arkivAccessKey, namespaceThe registry to read and write
policy or policyProfileproduction (default) or a tuned live clock
limitsOverride the per-call ceiling, budgets, thresholds or replay window
hcsTopicIdOptional audit topic
proberAddressesArkiv addresses whose probes count
modeenforce (default) or observe: decide and log, never block
awaitApprovalMsWait this long for the owner before throwing LeashEscalated
autoReportFile 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.

@leash/mcp

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.

Claude Desktop: claude_desktop_config.json · JSON
{
  "mcpServers": {
    "leash": {
      "command": "pnpm",
      "args": ["--dir", "/path/to/Leash", "exec", "tsx", "packages/mcp/src/server.ts"],
      "env": { "LEASH_MCP_AGENT": "C" }
    }
  }
}
Claude Desktop on Windows: the same entry, through cmd · JSON
"command": "cmd",
"args": ["/c", "pnpm", "--dir", "C:/path/to/Leash", "exec", "tsx", "packages/mcp/src/server.ts"]
Claude Code · Terminal
claude mcp add leash -e LEASH_MCP_AGENT=C -- pnpm --dir /path/to/Leash exec tsx packages/mcp/src/server.ts
Tools
ToolInputReturns
leash_pay_requesturl, method, maxUsd, idempotencyKey?paid (with an untrusted body), pending_approval, denied, no_payment, unconfirmed, failed
leash_check_merchantkey: ENS name, domain or accountstanding, factors, strikes, block and hold ends, rebuttal
leash_explain_decisiondecisionIdthe stored decision: reasons, factors, limits, latency
leash_report_outcometxId, outcomequeued, already-filed or refused; reports are filed automatically
leash_list_pending_approvalsnonestructured cards: merchant, standing, amount, score, reasons
leash_await_approvalapprovalId, timeoutMs (up to 55 s)approved, rejected, expired or still_pending; it cannot approve
leash_get_budgetnonesession 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.

Be recognised

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.

Text records, example: the weather merchant
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
x402 route config · TypeScript
// 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.

Arkiv

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.

Terminal
npx tsx apps/demo/src/arkiv-query.ts mumbai-prod 0.0.11323813

Schema: arkiv/schema.md. How the decision uses it: proof of payment.