Agents

Safety Model

DeFi mistakes are expensive and irreversible. The Topaz skill is engineered so an agent quotes, explains, builds, and simulates by default — and only moves funds when the user has explicitly authorized the move and signing credentials are configured.

Default posture

✓Quote before building — the agent always returns a quote first, with route, price impact, and slippage assumptions visible.
✓Build without broadcasting — transaction calldata is generated wallet-ready but not submitted unless the user explicitly says "broadcast."
✓Surface approvals explicitly — if an allowance or veNFT delegation is required, the agent raises it as a separate step, not a silent precondition.
✓Label every output — the user always knows whether they're looking at a read, a built transaction, an approval requirement, or a broadcast result.

The four output labels

Every agent response carries one of four labels. The label tells you exactly how much has happened.

Parameter	Value	Description
quote	read-only	Price, route, or state preview. Nothing on-chain. Re-runs are free.
built calldata	wallet-ready, not submitted	A transaction object ready for the user's wallet. Not broadcast. Re-runs may produce identical or refreshed calldata.
approval-needed	precondition	Allowance or veNFT delegation must happen before the next step. The agent should show what needs approving and why.
broadcast tx-hash	on-chain	Only produced after explicit user authorization AND configured signing credentials. The response includes the transaction hash so the user can verify.

When broadcasting is appropriate

Broadcasting requires two conditions, both of which must be true:

The user has explicitly asked the agent to broadcast — not merely "swap" or "do it," but a clear instruction to submit to the chain.
Signing credentials are configured in the agent's environment (e.g. PRIVATE_KEY in scripts/.env for the bundled helpers, or the runtime's wallet integration).

⚠Ambiguous requests stop at calldata

If the user says "swap 5 WBNB for USDT", the right behavior is to quote and build, then ask whether to broadcast. Implicit broadcast is never correct.

Slippage & approvals

Slippage

The agent must report assumed slippage in every quote and built calldata response. The default is conservative (typically 0.5%); users can override per-call. If the user requests an unusually loose tolerance, the agent should flag the risk (sandwich exposure) before building.

Approvals

ERC-20 swaps and LP deposits require token allowances. veNFT voting and managed locks require veNFT approval to the right contract. The agent should:

✓Check current allowance / approval before building.
✓Surface needed approvals as approval-needed outputs separate from the swap calldata.
✓Prefer exact-amount approvals over infinite allowance, and flag if the user explicitly asks for infinite approval.

Enforcing read-only mode

For environments that must never broadcast (CI checks, analytics agents, public-facing copilots), enforce read-only at the environment level:

bash

# don't expose any signing credential
unset PRIVATE_KEY
# verify with the bundled smoke test, which only does reads
cd <skill>/scripts && yarn smoke

Without signing credentials configured, the skill cannot produce a broadcast tx-hash output regardless of what the user asks. The worst it can do is build calldata — which the user still has to take to a wallet themselves.

What the agent should never do

✓Broadcast a transaction the user didn't explicitly authorize, even if context strongly implies they want it.
✓Silently widen slippage tolerance to make a transaction succeed.
✓Combine multiple operations (e.g. approve + swap + claim) into a single "just do it" flow without labeling each step.
✓Use private keys, mnemonics, or session tokens that weren't supplied through a configured signing path.
✓Move user funds to any address other than what the user has named in the request.

Reporting unsafe behavior

If an agent using the Topaz skill behaves unsafely — broadcasts without consent, silently widens slippage, mishandles approvals — open an issue at github.com/topazdex/agent-skill/issues with the prompt, the response, and the runtime. Safety bugs are the highest-priority issues we accept.