Overview

You are an agent. Increasingly, agents hire other agents, call paid APIs, and move money. The common shortcut — hand a sub-agent your full credentials and hope — fails in three familiar ways: scope creep (the helper ends up with more power than the task needs), zombie access (nobody remembers what was handed out, so nothing gets cleanly withdrawn), and confused deputies (a token leaks and whoever holds it is believed).

Claw-in-a-Box makes the safe pattern the easy pattern, across two capabilities:

1 · Delegatable capability tokens

Mint a root capability, then delegate attenuated children offline (macaroon-style HMAC chaining). A child can never hold a scope its parent lacks, never outlive its parent, and is bound to a single audience. Revoke any token and every descendant dies with it — by construction, not bookkeeping.

2 · Spend-policy verdicts

Before acting, ask POST /v1/guard/check and get back allow review deny with the exact rules that fired. Four policy primitives: per-transaction and daily spend limits, destination allowlists, human-approval thresholds, and time windows.

Quickstart

Sixty seconds, copy-paste. Everything is a plain JSON POST — no SDK, no auth for the demo deployment.

# 0) set the base URL and confirm the service is up
BASE=https://api.clawinabox.xyz
curl -s $BASE/healthz

# 1) check a spend BEFORE doing it
curl -s -X POST $BASE/v1/guard/check \
  -d '{"agent_id":"my-agent","action":"transfer","amount":150,"destination":"0xabc"}'
# -> {"verdict":"review","triggered_rules":["require_approval"],...}

# 2) mint a root capability, then delegate a NARROWER child
ROOT=$(curl -s -X POST $BASE/v1/tokens \
  -d '{"subject":"my-agent","scopes":["read","write","pay"]}' | jq -r .token)

curl -s -X POST $BASE/v1/tokens/delegate \
  -d "{\"parent_token\":\"$ROOT\",\"audience\":\"worker-1\",\"scopes\":[\"read\"],\"ttl_seconds\":600}"

# 3) revoke the root — every child dies with it, transitively
curl -s -X POST $BASE/v1/tokens/revoke -d "{\"token\":\"$ROOT\"}"

How it works

The design thesis is that bounded authorization — a grant that can only shrink as it moves, and dies with its ancestors — is one abstraction that should be enforced wherever an agent acts.

Attenuation is enforced, not requested

Tokens are HMAC-chained: each child's signature is keyed by its parent's. That makes three properties hold on every verify, on the server, with no way for a client to forge or broaden them without the secret:

Cascading revocation

Revoke any token and every token delegated under it fails verification from that moment, transitively, with revoked_ancestor. Revoke the root to kill the entire tree. This is cryptographic, not a lookup table you have to keep in sync.

One idea, three enforcement surfaces

The same four policy primitives compile to different surfaces; what changes is who enforces them.

Guarantees & limits

Read this before pointing anything important at the hosted demo.

Concretely:

API reference — Spend guard

Send the action you intend to take; get back a verdict and the rules that fired.

Request fields

Response

{
  "verdict": "allow | review | deny",
  "triggered_rules": ["spend_limit.per_tx"],
  "reasons": ["amount 999 exceeds per-tx limit 200"],
  "policy_used": "standard",
  "spent_today_after": 150,
  "evaluated_at": "2026-07-09T12:00:00.000Z"
}

Interpreting the verdict

deny always wins over review.

Policies

Presets

Inline policy schema — four primitives

{
  "name": "my-policy",
  "rules": [
    {"type": "spend_limit", "per_tx": 200, "daily": 1000},
    {"type": "allowlist", "field": "destination", "values": ["0xgood"]},
    {"type": "require_approval", "when_amount_over": 100},
    {"type": "time_window", "allow_utc_hours": [[9, 18]]}
  ]
}

Issue a root capability

{"subject": "my-agent", "scopes": ["read", "write", "pay"], "ttl_seconds": 3600}

Returns {"token": "<base64url>"}. ttl_seconds defaults to 3600.

Delegate an attenuated child

{"parent_token": "<token>", "audience": "worker-1", "scopes": ["read"], "ttl_seconds": 600}

Returns {"token": "<child token>"}. The service enforces:

Any token holder can delegate. Chains can be arbitrarily deep; every hop attenuates.

Verify a presented token

{"token": "<token>", "presenter": "worker-1"}

presenter is optional but recommended: when present, the service also checks the token is being presented by its bound audience. Success:

{
  "valid": true,
  "context": {
    "subject": "worker-1", "scopes": ["read"],
    "expires_at": 1760000000,
    "chain_tids": ["a1b2...", "c3d4..."], "depth": 2
  }
}

Failures return HTTP 400/403 with {"valid": false, "verdict": "deny", "error": "<code>", "detail": "<human readable>"}.

Revoke with cascade

{"token": "<token>"}

Returns {"revoked_tid": "...", "cascades": true}. Every token delegated under the revoked one fails verification from this moment, transitively, with revoked_ancestor. Revoke the root to kill the entire tree.

Error codes

Verify and delegate failures use a stable error code:

Route review approvals to your own Telegram

By default, when your agent trips a review rule, the approval request goes to the service operator. You can instead bind your own Telegram so every review for your agent lands on your phone with Approve / Deny buttons.

curl -X POST https://api.clawinabox.xyz/v1/operators/register \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"YOUR_AGENT_ID"}'

{
  "agent_id": "YOUR_AGENT_ID",
  "bind_code": "A1B2C3D4",
  "expires_in_seconds": 900,
  "instructions": "Open Telegram, message the bot, and send: /bind A1B2C3D4"
}

✅ Bound. Review requests for agent YOUR_AGENT_ID will now come to this chat.

curl -s https://api.clawinabox.xyz/v1/operators/YOUR_AGENT_ID
# -> {"agent_id":"YOUR_AGENT_ID","routing":"caller"}

curl -X POST https://api.clawinabox.xyz/v1/guard/check \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"YOUR_AGENT_ID","amount":150}'

Self-hosting

Zero dependencies, Node.js >= 18. No npm install. State (revocations, daily totals) is in-memory by design at this stage.

cd service
GUARD_SECRET=$(openssl rand -hex 32) PORT=8787 node server.js
node test.js   # 12-case smoke suite, exits 0 on success

Full source is on GitHub under Apache-2.0. The agent-facing API doc is also served live at /skill.md.