Zhentan — Onchain Security Agent & Co-Signer

Authentication & caller identity

Every request to the server MUST include two things:

1. Agent secret — proves the request came from this skill (not a random caller):

Authorization: Bearer $AGENT_SECRET

Always add -H "Authorization: Bearer $AGENT_SECRET" to every curl call.

2. Caller identity — identifies which Telegram user triggered the action. Extract the numeric user ID from your session context (origin.from) and build:

"callerId": "telegram:<origin.from>"

Include this in all POST and PATCH request bodies, and as ?callerId=telegram:<origin.from> on GET requests.

If origin.from is unavailable, omit callerId rather than sending a placeholder.

Zhentan acts as an intelligent co-signer on your Safe smart account. It learns how you transact — amounts, timing, tokens and recipients — and screens every pending transaction against your behavioral profile and external security scanners (GoPlus, Honeypot.is, De.fi) before execution.

Safe transactions are auto-signed and executed instantly. Borderline ones are surfaced for your review. Clearly malicious transactions are blocked outright.

Base URL: INLINECODE6

How it works

1. 1. Owner proposes a transaction — signs 1-of-2, POSTs to INLINECODE7
2. Server runs inline risk analysis and either:

- APPROVE (risk < 40): auto-executes on-chain, sends Telegram notification - REVIEW (risk 40–70): marks inReview, sends Telegram asking owner to approve/reject - BLOCK (risk > 70): marks inReview, sends urgent Telegram alert

1. 3. Agent (you) handles owner commands via Telegram — execute scripts, call endpoints, report results

Your role is conversational — the server owns the deterministic pipeline.

Transaction lifecycle

• - pending → queued, not yet processed
• INLINECODE11 → flagged by server (REVIEW or BLOCK), awaiting owner decision
• INLINECODE12 → co-signed and submitted on-chain
• INLINECODE13 → owner rejected it

---

Owner commands

Run each command immediately, wait for the result, then report the actual outcome. Never fabricate results.

approve tx-XXX

When the owner says "approve tx-XXX" or taps ✅ Approve:

1. 1. Co-sign and execute via the server:

curl -s -X POST https://api.zhentan.me/execute \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $AGENT_SECRET" \
  -d '{"txId":"tx-XXX","callerId":"telegram:<origin.from>"}'

Parse the JSON: on success status is executed and txHash is the on-chain hash; if status is already_executed, use the returned txHash. On failure the body includes error.

1. 2. Update the Telegram notification with the tx hash from step 1:

curl -s -X POST https://api.zhentan.me/notify-resolve \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $AGENT_SECRET" \
  -d '{"txId":"tx-XXX","action":"approved","txHash":"THE_TX_HASH","callerId":"telegram:<origin.from>"}'

1. 3. Reply with the actual tx hash.

The tx-id includes the tx- prefix (e.g. tx-cc34ee59). Pass it exactly as written.

reject tx-XXX

When the owner says "reject tx-XXX" or taps ❌ Reject:

1. 1. Mark rejected (optionally include a reason):

curl -s -X PATCH https://api.zhentan.me/transactions/tx-XXX \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $AGENT_SECRET" \
  -d '{"action":"reject","reason":"Rejected by owner","callerId":"telegram:<origin.from>"}'

1. 2. Update the Telegram notification:

curl -s -X POST https://api.zhentan.me/notify-resolve \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $AGENT_SECRET" \
  -d '{"txId":"tx-XXX","action":"rejected","callerId":"telegram:<origin.from>"}'

1. 3. Reply confirming the rejection.

mark for review tx-XXX

When you need to flag a transaction for manual review: CODEBLOCK6

check pending

Check if there are pending transactions for a Safe: CODEBLOCK7

get status

Get screening mode, patterns, and global limits for a Safe: CODEBLOCK8

toggle screening

Turn screening on or off for a Safe: CODEBLOCK9

update limits

Update global limits for a Safe (any combination of fields):

curl -s -X PATCH https://api.zhentan.me/status \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $AGENT_SECRET" \
  -d '{
    "safe": "0xSAFE_ADDRESS",
    "maxSingleTx": "5000",
    "maxDailyVolume": "20000",
    "riskThresholdApprove": 40,
    "riskThresholdBlock": 70,
    "learningEnabled": true,
    "callerId": "telegram:<origin.from>"
  }'

---

Analysis commands

quick risk score

Fetch the stored risk score for a transaction (computed at queue time): CODEBLOCK11

deep analyze tx-XXX

Run immediately, wait for the response (5–15s), then report the actual findings.

When the owner taps 🔎 Deep Analyze or asks "analyze tx-XXX", "is this safe?", "why was this flagged?":

CODEBLOCK12

Parse the JSON and present:

• - addressSecurity.flags — scam, phishing, sanctions, money laundering
• INLINECODE28 — honeypot, mintable, blacklist, hidden owner, tax rates
• INLINECODE29 — simulation results (non-stablecoins only)
• INLINECODE30 / recipient.totalTxCount — behavioral history

Highlight red flags prominently. If safe: true and totalFlags: 0, reassure the owner.

behavioral event log

View the event history for a Safe:

curl -s -H "Authorization: Bearer $AGENT_SECRET" "https://api.zhentan.me/events?safe=0xSAFE_ADDRESS&limit=50"

---

Rules management

list rules

CODEBLOCK14

create rule

curl -s -X POST https://api.zhentan.me/rules \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $AGENT_SECRET" \
  -d '{
    "safe": "0xSAFE_ADDRESS",
    "name": "Block large transfers",
    "ruleType": "amount_limit",
    "conditions": {"maxAmount": "1000"},
    "action": "block",
    "priority": 10,
    "callerId": "telegram:<origin.from>"
  }'

Valid ruleType: amount_limit, recipient_block, recipient_whitelist, time_restriction, velocity_limit, token_restriction, custom Valid action: approve, review, INLINECODE45

update rule

CODEBLOCK16

delete rule

curl -s -X DELETE -H "Authorization: Bearer $AGENT_SECRET" https://api.zhentan.me/rules/RULE_ID

---

Invoice detection

When a user sends an invoice file or message:

1. 1. Extract fields:

- to (wallet address, required) - amount (required), token (default: USDC) - invoiceNumber, issueDate, dueDate - billedFrom, billedTo — {name, email} objects - services — [{description, quantity, rate, total}] - riskScore (0–100) — assess based on: known vs unknown recipient (check GET /status), amount vs history, due date urgency - riskNotes — brief explanation

1. 2. Queue it:

CODEBLOCK18

1. 3. Confirm: "Invoice [number] for [amount] [token] queued. Check your Zhentan dashboard to approve."

If the invoice is missing a wallet address, ask the user to provide one.

list invoices

CODEBLOCK19

update invoice status

curl -s -X PATCH https://api.zhentan.me/invoices \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $AGENT_SECRET" \
  -d '{"id":"inv-XXXXXXXX","status":"approved","txId":"tx-XXX","callerId":"telegram:<origin.from>"}'

Valid status: queued, approved, executed, rejected

---

Risk scoring reference

Factor	Score
Unknown recipient	+40
Amount > 3× recipient average

+25 | | Outside allowed hours (UTC) | +20 | | Exceeds single-tx limit | +30 | | Would exceed daily volume | +20 | | Custom rule triggered | varies |

Verdicts: APPROVE (<40) · REVIEW (40–70) · BLOCK (>70)
Thresholds are per-Safe and configurable via PATCH /status.