<img src="https://raw.githubusercontent.com/stakeme-team/contributing-projects/master/files/zetachain-logo.png" alt="ZetaChain" width="96" height="96">

# ZetaChain Agent Kit

**One TypeScript workspace for ZetaChain's EVM and Cosmos — built for AI agents and developers.**

Chain exploration · wallet utilities · unsigned transfers · EVM signing · contract deployment preparation · Cosmos staking preparation.

[![MCP](https://img.shields.io/badge/MCP-Streamable_HTTP-003f35)](https://zetachain.exploreme.pro/api/mcp)
[![ZetaChain](https://img.shields.io/badge/ZetaChain-Mainnet_7000-005345)](https://zetachain.exploreme.pro)
[![Node.js](https://img.shields.io/badge/Node.js-22%2B-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)

**Works with** [Claude Code](docs/claude-code-setup.md) · [Cursor](docs/cursor-setup.md) · [Codex](docs/codex-setup.md) · [Vercel AI SDK](docs/prompts.md)

[Quick start](#start-with-your-mcp-client) · [CLI & SDK](#cli-and-sdk-setup) · [Wallets](#wallet-and-transfers) · [Transaction guide](docs/transactions.md) · [Explorer](https://zetachain.exploreme.pro)

> **MCP compatibility:** the official SDK requires object-shaped tool schemas. The explorer gateway normalizes the Solidity/Vyper verification schema while preserving its validation constraints.

## Why ZetaChain Agent Kit

**Two chain interfaces, one workspace.** Explore EVM blocks, transactions, contracts and tokens alongside Cosmos validators and staking data. The live MCP catalog supplies the current tool schemas.

**Start in chat or in code.** Use your MCP-capable client, run the CLI without an AI key, or build a programmatic agent with Anthropic or OpenAI through the AI SDK.

**Keep execution explicit.** The SDK agent can read data and prepare transactions. EVM signing and broadcasting are separate terminal commands requiring your confirmation; Cosmos signing uses an external wallet.

## How it works

```text
Claude Code / Cursor / Codex        TypeScript AI agent / CLI
              |                              |
              +-------- ZetaChain MCP -------+
                        EVM + Cosmos
                             |
                    Unsigned transaction
                             |
                 Review in your terminal
                             |
            Local EVM signer / external Cosmos wallet
                             |
                    Explicit broadcast
```

## Included workflows

| Workflow | What is included |
| --- | --- |
| Explore | Live tools, network identity, blocks, accounts and transaction queries |
| Wallet | Create a local EVM wallet or use an existing public address |
| Transfer | Prepare native transfers; use live schemas for ERC-20 and contract calls |
| Deploy | Prepare EVM contract creation from compiled bytecode |
| Verify | Use the explorer or its available verification MCP tools |
| Stake | Prepare Cosmos delegation; sign with an external Cosmos wallet |
| Automate | AI SDK agent with read/preparation tools and configurable model/provider |

## Network

- MCP: `https://zetachain.exploreme.pro/api/mcp` (Streamable HTTP)
- Network: ZetaChain mainnet, EVM chain ID **7000**
- Native currency: **ZETA**, 18 decimals; Cosmos base denom **azeta**
- Explorer: https://zetachain.exploreme.pro

The server's live catalog is the source of truth. The kit verifies the server identity and active EVM network on every CLI/SDK connection. Read-only demos require no wallet or AI API key. The SDK agent can read data and prepare unsigned transactions; it has no signing or broadcast tool.

## Start with your MCP client

Clone the workspace, then open it in your client:

```bash
git clone https://github.com/stakeme-team/zetachain-agent-kit.git
cd zetachain-agent-kit
```

You can also download the workspace as a ZIP from the explorer's [/mcp page](https://zetachain.exploreme.pro/mcp).

- **Claude Code:** the included `.mcp.json` configures the HTTP server. Approve the project server when prompted. [Setup](docs/claude-code-setup.md)
- **Cursor:** use the included `.cursor/mcp.json`. [Setup](docs/cursor-setup.md)
- **Codex:** use the included project `.codex/config.toml`, or run `codex mcp add zetachain --url https://zetachain.exploreme.pro/api/mcp`. [Setup](docs/codex-setup.md)

Try: “Show the current ZetaChain network and latest EVM blocks.” MCP access itself does not require an API key; your chosen AI client may require a subscription or credits.

The repository includes `/wallet`, `/send`, `/deploy`, and `/stake` Claude Code skills plus a shared ZetaChain skill for Codex. Preparation does not execute a transaction. Local signing and broadcasting are separate commands that you run in an interactive terminal.

## CLI and SDK setup

Node.js **22+** is required. From the extracted folder:

```bash
npm ci
cp .env.example .env
npm run demo:network
npm run tools
```

On PowerShell, use `Copy-Item .env.example .env` instead of `cp` if needed. Config files are shipped in the archive; enable hidden-file display when browsing it.

For a programmatic AI agent, set `AI_PROVIDER=anthropic` or `AI_PROVIDER=openai`, `AI_MODEL` to a model available to your account, and the corresponding API key in `.env`:

```bash
npm run agent -- "Summarize the ZetaChain network using live tools."
```

Only the programmatic agent needs an AI provider key. See [SDK usage and prompts](docs/prompts.md).

## Wallet and transfers

For an optional local development wallet:

```bash
npm run wallet
npm run wallet -- address
```

The first command creates `.wallet/private-key` without overwriting an existing key, and prints **only the public address and file path**. Put the public address in `WALLET_ADDRESS`. The private key is an unencrypted local file with owner-only permissions on POSIX; on Windows, protect it with your account's filesystem permissions. For funded accounts, you can use an external wallet instead. Do not share the key or `.env` with an AI client. [Signing guide](docs/signing.md)

Prepare a transfer to an address you choose:

```bash
npm run demo:send -- 0xYOUR_RECIPIENT 0.001
npm run kit -- sign prepared-transfer.json signed-transfer.json
npm run kit -- broadcast signed-transfer.json
```

Replace `0xYOUR_RECIPIENT` with a real EVM address. Review chain, sender, recipient, value, calldata, nonce, gas and fees before typing `SIGN` or `BROADCAST`. These commands use mainnet and real ZETA. Existing output files are not overwritten. A signed file is authorization to execute its transaction; keep it private.

## Deploy, verify and stake

- `npm run demo:deploy -- bytecode.txt` prepares a contract creation from compiled creation bytecode, including any encoded constructor arguments. Review, sign and broadcast as above, then use the explorer's [contract verification](https://zetachain.exploreme.pro/contracts/verify) or an available verification MCP tool. No automatic compiler or verification credentials are bundled.
- `npm run demo:stake -- zeta1YOUR_ADDRESS zetavaloper1VALIDATOR 1000000000000000000` prepares a **1 ZETA** Cosmos delegation. Choose the actual addresses first. Sign with your Cosmos wallet; the local EVM signer does not sign Cosmos messages.
- For any supported tool: `npm run kit -- call TOOL arguments.json result.json`. The file is a JSON object matching the tool's live `inputSchema`. Mutating tools require interactive `EXECUTE` confirmation. `npm run tools` prints full schemas.

See [transaction workflows](docs/transactions.md) for ERC-20 transfers, contract calls and Cosmos signing.

## Verify the kit

```bash
npm run check-types
npm test
npm run smoke
```

Unit tests sign only deterministic offline fixtures. Smoke connects to the live server, checks the catalog and network, and never signs or broadcasts.

## Layout

`src/mcp.ts` owns HTTP transport, identity checks, catalog pagination and Zeta response parsing. `src/agent.ts` adapts read/preparation tools to the AI SDK. `src/wallet.ts` validates EVM signing fields. `src/cli.ts` keeps signing and broadcast explicit. `examples/` contains network, transfer, deployment and Cosmos delegation entry points.

## References

- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [AI SDK tool calling](https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling)
- [viem local accounts](https://viem.sh/docs/accounts/local)

This kit follows the Stakeme explorer Agent Kit layout, adapted to ZetaChain's deployed tool schemas. Source is maintained in [stakeme-team/zetachain-agent-kit](https://github.com/stakeme-team/zetachain-agent-kit). The explorer download is generated from the same workspace.

Maintainers can regenerate the download and rendered-guide assets with `python3 scripts/package.py /path/to/frontend/public/agent-kit`. The exporter includes only kit source/configuration directories and produces a SHA-256 manifest; dependencies and local wallet/environment files are excluded.