Buyer guide · v0.9.0

Route approvals to your Telegram.

Bind an agent to your own Telegram chat so every review verdict arrives on your phone with Approve and Deny buttons.

Base URL https://api.clawinabox.xyz Bind code valid for 15 minutes Routing one agent → one chat

Unclaimed agent

Legacy open binding

No secret header is required. Use a private, unguessable agent_id because anyone who knows it shares its daily budget and can request a new bind code.

Claimed agent

Secret-protected binding

Send the matching X-Agent-Secret when requesting a bind code. Never place the secret in a URL or JSON body.

Official Telegram bot: @ClawInABoxBot. Verify this exact username before sending a bind code to avoid impersonators and scammers, then press Start. Telegram will not let a bot message a person who has never opened the chat.

Open the Telegram bot

Open @ClawInABoxBot, confirm the username matches exactly, and press Start. Leave the chat open; you will return with a one-time command in Step 3.

Request a one-time bind code

For an unclaimed agent:

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

For a claimed agent, protect the request with its secret:

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

The response contains a code valid for 900 seconds:

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

Send the code to the bot

Return to the Telegram chat and send the command exactly as shown:

/bind A1B2C3D4

Expected reply

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

Verify the route, then test it

Confirm that the newest binding points to the caller's Telegram chat:

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

caller means the binding is active. operator means the agent still falls back to the service operator.

Trigger a standard-policy review. If the agent is claimed and strict mode is enabled, include its secret; unclaimed agents omit that header.

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

An approval message with Approve and Deny buttons should appear on your phone. Tapping a button takes effect immediately.

What happens after binding

Expired code

Bind codes last 15 minutes. Request a fresh code and repeat the command.

Changing phones or chats

There is no separate unbind endpoint. Register again and complete a new /bind; the newest binding wins.

One destination per agent

Each agent_id routes to one Telegram chat at a time.

Unbound agents

Until binding completes, review requests continue to route to the service operator.

Security checklist

Use only @ClawInABoxBot; reject look-alike usernames and unsolicited bot messages.
Use a private, unguessable id when the agent is not claimed.
For a durable identity, claim the id through x402 and store the one-time secret safely.
Send X-Agent-Secret only as a request header—never in URLs, JSON bodies, screenshots or logs.
Confirm the agent id and amount before tapping Approve.

Prefer a visual workflow?

Use the Console's Telegram Binding page to request a code and check routing without assembling curl commands.

Open Console →