Agent Skill

Topaz for AI agents

The official Topaz Dex agent skill. Lets any AI agent quote, build, and reason about swaps, pools, gauges, bribes, veNFTs, and rewards on BNB Chain — safely and accurately. Read it from a URL, clone the full repo, or drop it into your agent's native skill system.

Version: v2.4.0
License: MIT
Chain: BNB Smart Chain (56)
Repository: topazdex/agent-skill

View on GitHub Read SKILL.md View manifest →Read the docs →

Quick Start

Three ways to load Topaz into your agent

Pick the path that matches your runtime. All three point at the same canonical skill.

URL prompt

Best for browser & chat agents

If your agent can fetch URLs, give it this prompt:

Read the official Topaz Dex agent skill at
https://topazdex.com/skill.md and follow it
when working with Topaz Dex swaps, pools,
gauges, bribes, veNFTs, rewards, quotes,
routes, or integrations.

Git clone

Best for coding & CLI agents

Full package — references, examples, scripts, evals:

bash

git clone https://github.com/topazdex/agent-skill.git <dest>
cd <dest>/scripts
cp .env.example .env
yarn install --immutable
yarn validate && yarn smoke

One-line installer

Auto-detects your skills dir

Detects ~/.claude/skills, ~/.config/opencode/skills, or ~/.hermes/skills and installs there. Falls through to ~/.local/share/topaz-skill if none are found. Prints its chosen destination before cloning.

bash

curl -fsSL https://raw.githubusercontent.com/topazdex/agent-skill/main/install.sh | bash

# or pick your own path
curl -fsSL https://raw.githubusercontent.com/topazdex/agent-skill/main/install.sh \
  | bash -s -- ~/some/other/path

Entry Points

Stable URLs you can point any agent at

These endpoints stay stable across versions. Bookmark them, hard-code them in agent configs, ship them in prompts.

Skill file (markdown)

→

Stable bootstrap markdown. Point any URL-reading agent here.

topazdex.com/skill.md

Manifest (JSON)

→

Machine-readable metadata: version, install, verify, compatibility.

topazdex.com/skill.json

GitHub repository

→

Canonical source of truth — references, examples, scripts, evals.

github.com/topazdex/agent-skill

Latest release

→

Tagged versions of the skill, packaged for reproducible installs.

releases/latest

Changelog

→

Every shipped change. Diff this against your installed version.

CHANGELOG.md

Discovery

→

Tiny .well-known endpoint for agent runtimes that auto-discover skills.

.well-known/agent-skill.json

Consumption Modes

Works with how your agent already loads context

Not every agent has the same skill system. The Topaz skill is designed to plug into all of them.

Read from URL

Best for browser agents, chat agents, and anything with a web-fetch tool. Point it at skill.md and you're done.

https://topazdex.com/skill.md

Clone the full package

Best for coding agents, CLI agents, and anything that runs scripts. Includes references/, examples/, evals/, and TypeScript helpers.

git clone github.com/topazdex/agent-skill

Copy into a native skill system

If your agent has its own skills, rules, memory, or custom-instructions concept, drop SKILL.md into that system and point at the repo for references.

<runtime>/skills/topaz

Use as project context

For coding agents, add the skill to your project rules or agent memory so Topaz-specific behavior applies while you work in your repo.

.cursor/rules · .claude/CLAUDE.md · etc.

Runtime Examples

Conventional locations per runtime

These are examples, not requirements. The canonical source is the GitHub repo — point your agent at whichever path it reads from.

Runtime	Conventional location
Claude Code (user-wide)	~/.claude/skills/topaz
Claude Code (project-local)	<your-project>/.claude/skills/topaz
Hermes	~/.hermes/skills/defi/topaz
OpenCode	~/.config/opencode/skills/topaz
Codex / Cursor / Continue / Aider / generic	any path — point the agent at it explicitly
Browser-only / URL-loading agents	read https://topazdex.com/skill.md directly

Generic URL-reading agents

Load https://topazdex.com/skill.md and use it as your operating guide for Topaz Dex tasks.

Git-capable coding agents

Clone https://github.com/topazdex/agent-skill and follow SKILL.md. Use references, examples, and scripts from the cloned repo when available.

Claude Code

Read https://topazdex.com/skill.md. If more detail is needed, clone https://github.com/topazdex/agent-skill into ~/.claude/skills/topaz (or .claude/skills/topaz for project-local) and follow SKILL.md as guidance for Topaz Dex tasks.

OpenAI Codex / generic code agents

Use https://topazdex.com/skill.md as the Topaz Dex protocol guide. For full references and scripts, clone https://github.com/topazdex/agent-skill.

Capabilities

What agents can do with Topaz

Every workflow on the Topaz dapp, available as agent-ready instructions and helpers.

Swaps & quotes

v2 volatile, v2 stable, v3 concentrated, and mixed routes with slippage modeling.

Built calldata

Wallet-ready swap and LP transactions. Never broadcast unless the user explicitly asks.

Liquidity positions

v2 LP and Slipstream v3 NFT positions — open, close, inspect, rebalance plans.

Gauges & emissions

TOPAZ emissions per gauge, gauge state, APR math, weekly epochs.

veTOPAZ & voting

Lock duration, voting power, vote allocations, reset, and re-vote flows.

Bribes & rewards

Emissions, trading fees, bribes, rebase — claimable across veNFTs and LPs.

Integrations

Quote widgets, swap calldata for bots, dashboards, and subgraph queries.

Debugging

Diagnose failed quotes, broken routes, stuck approvals, and reverted txs.

Safety

Quote, build, simulate — never broadcast by default

The skill makes agents safe by default. Funds never move unless the user explicitly asks and signing credentials are configured.

Every agent output must carry one of four labels so the user always knows what just happened:

quote

Read-only price/route preview. Nothing on-chain.

built calldata

Transaction bytes ready for the user's wallet. Not broadcast.

approval-needed

Allowance or veNFT delegation must happen before the next step.

broadcast tx-hash

Only after the user explicitly authorizes and signing is configured.

✓Quote before building transactions
✓Simulate or dry-run when possible
✓Clearly report slippage assumptions
✓Clearly report approval requirements
✓Build calldata without broadcasting by default
✓No fund movement unless the user explicitly asks

Update & Verify

Keep your installation current

Compare versions against /skill.json, pull updates, and verify the full package boots cleanly.

Update

If installed as a git repository:

bash

git -C <dest> pull --ff-only
# or use the wrapper:
bash <dest>/update.sh

Check whether an update is available without applying it:

bash

cd <dest>
bash tools/check_update.sh
# exit 0 = up to date, 10 = update available

Verify

Full-repo install — node >= 20, yarn@4 (corepack enable):

bash

cd <dest>/scripts
yarn install --immutable
yarn validate
yarn build
yarn test
yarn smoke

yarn smoke is a live read against BSC mainnet — set BSC_RPC_URL in scripts/.env. No PRIVATE_KEY needed for reads.

Versioning

Current: v2.4.0

The repo validator enforces that SKILL.md frontmatter version matches skill.json at every release. Compare your local version against the manifest to decide whether to update.

Latest release →Changelog →

Report Issues

Stale data? Unsafe behavior?

If you find outdated protocol data, broken helpers, incorrect docs, or an agent behaving unsafely, open an issue. The skill is maintained alongside the protocol — every report ships back into the next release.

Open an issue