io.github.h1-hunt/mintclub

Protocol-native Mint Club V2 tooling for humans and agents. Reads and direct Bond operations use the configured Mint Club contracts; routed trades use local RPC quotes and MCV2_ZapV2.

Tooling

All three adapters consume the published chain-registry.json from @mint.club/v2-cli. The registry is the shared source for chain keys, aliases, IDs, and capability flags; the CLI validates it against its full contract/token/RPC configuration at startup.

For application development, use the separate @mint.club/v2-sdk package and SDK documentation.

Package migration

Version 2.0 consolidates the public packages under the @mint.club npm organization:

The scoped names supersede the legacy SDK, CLI, and MCP package names. Existing users should migrate their install and configuration commands; package binaries remain mc and mintclub-mcp. @mint.club/v2-eliza-plugin is new—the earlier @elizaos/plugin-mintclub name was never published.

Quick start

npm install -g @mint.club/v2-cli
mc wallet --generate

mc --chain base info SIGNET
mc --chain arbitrum price 0xTOKEN
mc --chain robinhood wallet

The CLI and MCP server require Node.js 18 or later. The ElizaOS plugin and repository development require Node.js 22.13 or later. Generate a dedicated wallet with limited funds, or provide PRIVATE_KEY through a trusted secret manager; never paste a key into an agent conversation.

Financial writes are fail-closed: CLI writes require --yes (while create keeps its interactive prompt), MCP write tools require explicit chain/assets plus confirm: true and must remain behind the host's destructive-tool approval, and Eliza writes require one affirmative original-user Confirm: statement with exactly one explicit chain and all effective limits, slippage, assets, and royalties.

Protocol operations

Example ZapV2 syntax:

mc --chain arbitrum zap-buy 0xMINT_CLUB_TOKEN \
  --input-token USDT \
  --input-amount 10 \
  --slippage 1 \
  --yes

mc --chain unichain zap-sell 0xMINT_CLUB_TOKEN \
  --amount 100 \
  --output-token USDC \
  --slippage 1 \
  --yes

Both ERC-20 and ERC-1155 Mint Club tokens can be direct Bond or Zap targets. Routed input and output assets must be native currency or ERC-20 tokens. ZapV2 is deployed on every supported chain listed below. Blast is intentionally unsupported because it is outside the official Uniswap deployment set used by this integration.

Local routing model

Routing does not call the Uniswap Trading API, Smart Order Router, Mint Club route services, or any API-key quote service. It uses chain RPC calls only:

1. Enumerate direct paths and paths with one configured wrapped-native or stablecoin intermediary.
2. Quote homogeneous Uniswap V2, V3, and V4 candidates where configured for the selected chain.
3. Isolate expected missing-pool reverts while surfacing transport failures.
4. Choose the highest exact-input output with deterministic tie-breaking.
5. Encode only the selected path with @uniswap/universal-router-sdk.

The encoder uses Universal Router V2.0 commands with router-balance payment (payerIsUser = false) and the ZapV2 contract as recipient. It rejects Permit2 ingress commands and settles any unused routed input directly back to the caller.

Deliberate limits: no split routes, mixed-protocol paths, arbitrary-length graph search, dynamic-fee V4 pools, or hooked V4 pools. V4 discovery checks only canonical hookless fee/tick-spacing pairs. This repository does not expose a general-purpose swap command.

MCP tools

The MCP server exposes nine tools:

token_info · token_price · wallet_balance · buy_token · sell_token · zap_buy · zap_sell · send_token · create_token

Read tools accept an optional canonical chain key and default to Base. Write tools require an explicit chain. See the MCP reference for schemas and safe client configuration.

Architecture

AI agent / user
      │
      ├── mc CLI
      ├── MCP server ────── argv ──┐
      ├── ElizaOS plugin ── argv ──┤
      └── Agent skill ─────────────┤
                                   ▼
                          @mint.club/v2-cli
                                   │
                  ┌────────────────┼─────────────────┐
                  ▼                ▼                 ▼
             MCV2_Bond        local RPC quotes   DefiLlama API
            mint/burn/create   V2 / V3 / V4       USD pricing
                                   │
                                   ▼
                        Universal Router encoding
                                   │
                                   ▼
                              MCV2_ZapV2

MCP and Eliza invoke the CLI with argument arrays rather than shell-interpolated commands.

Supported chains

See the CLI reference for command options, routing details, and contract configuration.

Development

The three publishable packages share one npm workspace lockfile:

npm ci
npm run check
npm test
npm run test:integration
npm run test:fork
npm run build
npm run audit:production
npm run audit:full
npm run test:release

Repository development requires Node.js 22.13 or later. CI separately verifies the published CLI and MCP runtime paths on Node.js 18. The default tests are deterministic and offline. test:integration performs read-only deployment and immutable checks across all supported networks plus live route quotes where a stable intermediary is configured. test:fork runs write flows against a pinned local Base fork and requires Anvil.

For releases, update all three package versions, the CLI dependency ranges, and mcp/server.json, then commit and push the changes to main. After the main CI run passes, use the repository release command:

npm run release

The command requires authenticated npm and git sessions. It runs the release gates, publishes the CLI first, waits for npm availability, publishes MCP and ElizaOS, verifies that every package records the current commit as its gitHead, and pushes the matching vX.Y.Z tag. The tag-triggered GitHub workflow then creates the GitHub Release automatically. Already-published packages from the same commit are skipped safely, so a partially completed npm release can be resumed. If npm publishing and the tag push succeed but the GitHub workflow fails, rerun that workflow from GitHub Actions.

License

MIT. Published packages include the project LICENSE; bundled CLI and MCP dependencies are covered by generated THIRD_PARTY_NOTICES.md files. The CLI build keeps only the ABIs from imported Uniswap contract artifacts and excludes their bytecode. See SECURITY.md for the dependency audit policy.