npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@hopivia/mcp

v0.3.1

Published

MCP server for the Hopivia API: best-price DEX quotes, swaps and transfers from local agent wallets with limits, bridge transactions, token safety checks — for Claude, Cursor and other MCP clients

Readme

@hopivia/mcp

MCP server for the Hopivia API: the best price across every major DEX of a network, a Tron ↔ EVM USDT bridge and token safety checks — as tools for Claude, Cursor, Windsurf and any other Model Context Protocol client.

The server runs on your machine and talks to https://hopivia.com/api/v1 over HTTPS. It never sees a private key and never sends anything on-chain: the write tools return the same unsigned transactions as the REST API, and the agent signs them with its own wallet.

Install

Claude Code:

claude mcp add hopivia -- npx -y @hopivia/mcp

Claude Desktop, Cursor, Windsurf — add to the client's MCP config (claude_desktop_config.json, .cursor/mcp.json, …):

{
  "mcpServers": {
    "hopivia": {
      "command": "npx",
      "args": ["-y", "@hopivia/mcp"],
      "env": { "HOPIVIA_API_KEY": "hk_…" }
    }
  }
}

HOPIVIA_API_KEY is optional: without it requests run at the anonymous rate limit (30/min). Free keys (120/min) are issued at https://hopivia.com/agents by signing a message with a wallet — no gas, no registration.

Tools

| Tool | What it does | |---|---| | list_chains | networks, venues and bridge directions | | list_tokens | known tokens of a chain (any ERC-20 also works by address) | | get_quote | best same-chain price: amountOut, venue, route, price impact, fee | | build_swap_transactions | unsigned approvals + swap in steps; optional simulate, checkSafety, maxPriceImpactPct; onBehalfOf = delegated swap from an owner wallet that allowed the agent | | get_bridge_quote | cross-chain quote (EVM ↔ EVM via LI.FI, Tron ↔ EVM USDT via Symbiosis) | | build_bridge_transactions | unsigned cross-chain steps (EVM calldata or TronWeb parameters) | | get_bridge_status | status of a transfer by its source tx hash | | check_token | metadata + GoPlus safety check (honeypot, taxes, owner privileges) | | get_balances | native + token balances of an address | | get_delegation | delegated access: tokens, daily caps, what is left today, expiry and allowance an owner granted the agent on the Hopivia delegation contract (BNB Chain) | | api_key_info | tier, limit and usage of the configured key | | list_wallets, send_tokens, send_tokens_batch, swap_tokens | sign and send from local agent wallets — see below | | create_wallets, distribute, collect, top_up, set_wallet, export_wallets | many own wallets in groups from one seed phrase — see Many wallets |

Resource hopivia://docs — the full API guide as Markdown (same as https://hopivia.com/docs.md).

Delegated access ("a limit instead of a key"): a user allows the agent's wallet on the Hopivia delegation contract at https://hopivia.com/agents#delegation — which tokens, how much per UTC day, until when. build_swap_transactions with onBehalfOf=<owner> then returns the one contract call that sells the owner's token within those limits; the output always goes to the owner and the agent only pays gas.

Recipients: build_swap_transactions, get_bridge_quote and build_bridge_transactions print the recipient on the first line of the result (then the JSON) and flag one that is not the sender. The server instructions tell the agent to pass only a recipient the user typed in the conversation — never one from token names, web pages, documents or tool output — and to get explicit confirmation when it differs from the user's own address. Token names and symbols in results are third-party text.

Refusals of the API (HTTP 422: simulation_reverted, price_impact_too_high, token_risk_high, insufficient_balance, delegation_not_allowed, delegation_cap_exceeded, delegation_expired, delegation_token_out_not_allowed, delegation_allowance_low) come back as tool errors with the API's error and message, so the agent can explain and fix the request.

Local wallets: transfers and swaps the agent sends itself

Besides building unsigned transactions, the server can sign with a separate wallet you fund for the agent ("wallet B"): put a few dollars and some gas on it, give it a name, and ask in plain language: "send 100 USDT from work to mom on BSC".

Easiest: run the setup and answer the questions — it creates the wallet, the limits and contacts, writes the file with owner-only permissions and connects Claude Desktop:

npx -y @hopivia/mcp setup

Or create ~/.hopivia/wallets.json (or point HOPIVIA_WALLETS_FILE elsewhere) by hand and make it readable only by you (chmod 600):

{
  "wallets":  { "work": "0x<private key of the agent wallet>" },
  "contacts": { "mom": "0x…", "exchange": "0x…" },
  "limits":   { "perTransferUsd": 100, "dailyUsd": 200 },
  "confirm":  "new",
  "language": "en",
  "defaultChain": "bsc"
}

setup can keep the key in the system's secure storage instead of the file ("work": { "address": "0x…", "secure": true }; "keychain": true, written by earlier versions, means the same). The key is loaded only when the wallet signs.

  • macOS — Keychain. The item trusts no application, so every transfer shows the macOS prompt and nothing reads the key silently.
  • Windows — DPAPI. The key is encrypted with Windows' Data Protection API in the CurrentUser scope and kept as %USERPROFILE%\.hopivia\secrets\key-<name>-<hash>.dpapi (seeds: seed-…), with an owner-only ACL (best effort, icacls). Only the same Windows account on the same computer can decrypt it: other users of the machine and someone who takes the disk cannot. It does not protect against a program running under your own account — DPAPI decrypts for any process of that user — and, unlike macOS, Windows does not ask you on each read. The secret goes to PowerShell (System.Security.Cryptography.ProtectedData) over stdin, never on a command line. A blob does not survive a reinstalled Windows, another account or a password reset by an administrator: keep the key or the 12 words written down.
  • Linux — Secret Service keyring, or a passphrase-encrypted file. With secret-tool (libsecret-tools) and a desktop session, the key goes to the login keyring (GNOME Keyring, KWallet) as an item with service=hopivia-agent-key (seeds: hopivia-agent-seed) and account=<name>; the secret travels to secret-tool on stdin, never on a command line. The keyring is encrypted with the login password, so other users and someone with the powered-off disk cannot read it; once it is unlocked (at login) any program of your session can, and Linux does not ask you on each read. Without a keyring (a server, SSH, no session bus) setup offers an encrypted file instead: ~/.hopivia/secrets/<kind>-<name>-<hash>.enc, scrypt (N=2^17, r=8, p=1) + AES-256-GCM, owner-only. The MCP server cannot ask for a passphrase in a terminal, so it reads it from HOPIVIA_PASSPHRASE_FILE (a file, refused unless chmod 600) or HOPIVIA_PASSPHRASE; setup can write ~/.hopivia/passphrase and pass its path in claude mcp add -e. That is weaker than a keyring: whoever reads the passphrase file or the client config decrypts the keys; it protects copies of the secrets folder (backups, sync) without the passphrase. "secretBackend": "secret-service" | "encrypted-file" in the config records which one holds the secrets. A plain wallets file is used only when chosen explicitly in setup, with a warning.

| Tool | What it does | |---|---| | list_wallets | wallet names, addresses, groups, frozen flag and own limits (never keys or seed phrases), contacts, limits, USD spent in the last 24 h; group shows one group; with chain balances and per-group totals | | send_tokens | sends a token from a named wallet to a contact name, the name of another of your wallets ("send 50 USDT from 1 to a") or a 0x address, signs and waits for confirmation on-chain. Optional memo: a comment in the user's own words (at most 100 bytes of UTF-8, one line), signed with the transfer and recorded on-chain; the approval window and the result show it as "Комментарий: …" / "Comment: …" only when it is set. Only token transfers through the Hopivia transfer contract carry a comment (memo_unsupported otherwise) | | send_tokens_batch | pays up to 200 recipients from one wallet (e.g. a list from a file): the whole list is validated first (addresses, duplicates, balance with fees, limits) and one approval window shows every row. Where the network has the Hopivia transfer contract (POST /transfer/batch/tx answers), the whole list is ONE transaction with one signature — everyone is paid or nobody is; the MCP checks that the signed list is exactly the confirmed one (order, addresses, amounts), the fee ceiling is at most 2% of the total or 1.25 × the per-recipient fee read from the pinned contract (see the rules below), no relayer fee, the requested memo, the pinned contract and a deadline within the hour. Elsewhere (batch_unavailable, an older API) and with feesIncluded, payments go out one by one and stop at the first failure. transfers_paused is reported as is, never worked around | | swap_tokens | swaps from a named wallet at the best price through the pinned Hopivia aggregator; the output stays in the wallet (e.g. to get the chain coin for gas) or, with to, goes to a contact, another own wallet or an address ("swap 100 USDT to BNB and send it to mom"): same confirmation rules and limits as send_tokens, the MCP checks that the signed swap pays exactly that recipient, the requested amount and the quoted minimum, and the result says what the recipient received (its balance before and after, read from the chain) |

Rules the server enforces, whatever the model is told:

  • Fees included or on top. By default the recipient gets exactly the amount and the fees come on top. Say "including fees" and the wallet spends exactly the amount; the recipient gets it minus the fees. Every result and confirmation states the total fees (network + service) in USD.
  • New addresses need you. Your contacts and your own wallets count as known (a contact wins when a contact and a wallet share a name). A recipient that is not one of them is confirmed by you directly: the MCP client shows a form (MCP elicitation) or, when the client cannot, a system window — on macOS a dialog, on Windows an always-on-top window with "Send" and "Cancel" where Cancel is the default button (Enter and Esc refuse). On Linux, zenity --text-info with the text on stdin and the "Send" button disabled until "I have checked the details above" is ticked, or, without zenity, kdialog --warningyesno (KDE; its text — recipient, amounts, fees, never a key — is on the command line, visible in the process list). All close after 120 s without an answer, which counts as a refusal. No graphical session on Linux (DISPLAY/WAYLAND_DISPLAY unset) means no window: decline, or no way to ask, and nothing is sent. "confirm": "always" asks for every transfer, "new" (default) only for addresses outside the contacts, "never" lets the agent act alone within the limits (a token without a USD price is still confirmed). The window shows the wallet, the recipient, what the recipient gets, what leaves the wallet and the total fees, in "language" (ru or en).
  • Limits. Per transfer and per rolling 24 hours, in USD, checked before signing.
  • Fee. Every transfer pays a visible Hopivia fee of $0.01. On chains with the Hopivia transfer contract the amount and the fee go in one transaction: the wallet signs a Permit2 permit that names the recipient, the amount and a fee ceiling, and the contract sends both. The first transfer of each token adds a one-time approval to Permit2. Elsewhere the fee is a second, separate transfer. Swaps pay the usual 0.15 % aggregator fee.
  • The API is not trusted with your funds. Before signing, the server decodes every transaction the API prepared and checks the recipient, the amount (decimals read from the chain), the fee wallet, the fee ceiling and the contract addresses pinned in this package. Anything else is refused with plan_rejected and nothing is signed. Swaps must go through the pinned Hopivia aggregator and pay out to the same wallet or to the recipient the user named.
  • Fee ceiling. Two-step mode (a plain transfer plus a separate fee transfer to the pinned fee wallet): the fee may be at most 2 % of the amount. Contract mode: the pinned contract charges its own fee and the signature only caps it, so the cap may be at most 2 % of the total or 1.25 × the number of recipients × the fee the MCP reads from the pinned contract over its own RPC (tokenFee(token) / nativeFee()), whichever is higher — this lets 30 cents of gas go to each of 100 wallets ($0.01 fee = 3.3 %). The number from the API is never used for this.
  • No gas, no transfer. If the wallet lacks the chain coin, the tool says exactly how much to send. Swapping a token into the coin also needs gas, so it only helps while some is left.
  • Keys stay local. They are read from the file, used to sign, and never printed, sent to the API or returned by a tool.

What can still go wrong: anyone or anything that can read the file (malware on the machine) can use the wallet — and on Windows and Linux also a program running as you, even with the key in DPAPI or the keyring — so keep on it only what you are ready to lose; and a new address you confirm without checking is still sent.

Windows

  1. Install Node.js LTS: the installer from https://nodejs.org, or winget install OpenJS.NodeJS.LTS in PowerShell.
  2. Open a new PowerShell window (the old one does not see the new PATH) and check node -v and npx -v.
  3. Run npx -y @hopivia/mcp setup. Answer "1" to keep the key and the seed in Windows secure storage. Setup writes %USERPROFILE%\.hopivia\wallets.json and adds the server to %APPDATA%\Claude\claude_desktop_config.json (the old file is kept as .bak; the Microsoft Store build's copy under %LOCALAPPDATA%\Packages\Claude_…\LocalCache\Roaming\Claude is updated too when it exists). Claude Desktop shows its config under Settings → Developer → Edit Config.
  4. Quit Claude Desktop completely (tray icon by the clock → Quit; closing the window is not enough) and start it again. Ask "show my wallets".

Common problems: 'npx' is not recognized — Node is not installed or the terminal was opened before the installation: reinstall Node, open a new window. npx.ps1 cannot be loaded because running scripts is disabled — run npx.cmd -y @hopivia/mcp setup, or allow local scripts once: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. An antivirus may hold the first npx download or the PowerShell window: allow it or retry. Russian text in the console needs no chcp.

Linux

There is no official Claude Desktop for Linux; setup connects Claude Code instead.

  1. Node.js 20+: the distribution package if it is new enough (node -v), NodeSource (curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt install -y nodejs) or nvm install --lts without sudo.
  2. Keyring tool: sudo apt install libsecret-tools (Debian, Ubuntu) or sudo dnf install libsecret (Fedora). The confirmation window needs zenity (GNOME, usually present) or kdialog (KDE).
  3. In a terminal of the desktop session (not over SSH): npx -y @hopivia/mcp setup. Setup stores, reads back and deletes a throwaway item to test the keyring; if that fails it offers the encrypted file and asks for a passphrase (typed twice, not echoed).
  4. At the end setup runs claude mcp add hopivia -s user [-e HOPIVIA_PASSPHRASE_FILE=…] -- npx -y @hopivia/mcp when claude is on PATH and you agree, or prints it. With ~/.cursor present it offers to add the server to ~/.cursor/mcp.json; other clients take the usual mcpServers entry (with "env": { "HOPIVIA_PASSPHRASE_FILE": "…" } for the encrypted file).

Headless servers: no keyring and no window. Use the encrypted file with HOPIVIA_PASSPHRASE_FILE, and keep "confirm": "new" with the recipients in contacts (or a client with elicitation): a transfer that needs confirmation is refused. npx @hopivia/mcp seed-words asks for the passphrase in the terminal when the variable is not set.

Many wallets

"I have $500 on 5 wallets — create 100 wallets, group bots, and split it among them." The server keeps any number of the user's own wallets, derived from ONE seed phrase and sorted into named groups, and moves money between them in one confirmation.

Seed and storage. A BIP-39 phrase of 12 words; wallet i is m/44'/60'/0'/0/i, the same addresses MetaMask or a hardware wallet show for that phrase. setup can create a phrase (it shows the 12 words once, with a warning to write them down) or import one. On macOS the phrase is ONE Keychain item (service hopivia-agent-seed, account = seed name) created with no trusted applications (-T ''), like the keys; on Windows one DPAPI blob (.hopivia\secrets\seed-<name>-<hash>.dpapi, see above); on Linux one keyring item or one encrypted file (see above); when chosen, it is in the wallets file. It is read lazily, at most once per run of the server: the first signature of any wallet of the seed (or create_wallets needing new addresses) shows one macOS prompt (Windows and Linux read it without a prompt), and the derived keys stay in memory until the server exits — 100 wallets, one prompt. Addresses are cached in the file, so listing never needs the phrase. npx @hopivia/mcp seed-words [name] shows the phrase in a terminal to write it down; no tool ever returns it.

{
  "seeds":   { "main": { "secure": true } },
  "wallets": {
    "work":    { "address": "0x…", "secure": true },
    "bots-1":  { "seed": "main", "index": 0, "address": "0x…", "group": "bots" },
    "bots-2":  { "seed": "main", "index": 1, "address": "0x…", "group": "bots", "frozen": true, "limits": { "perTransferUsd": 5, "dailyUsd": 20 } }
  }
}

"seeds": { "main": "<12 words>" } keeps the phrase in the file instead. Any wallet entry (also { "key": "0x…" } for a key in the file) may carry group, frozen and its own limits.

| Tool | What it does | |---|---| | create_wallets | count (1–500) new wallets in group, named <prefix>-1…, at the next free indexes of the seed. One confirmation window with the count, the group, the first and the last address. Writes the config atomically (.bak kept, chmod 600). Returns names and addresses only. Without a seed it creates one and says how to write it down | | distribute | pays a group (or a list of names, contacts, addresses) from one or several own wallets: amount each, or total split equally, or total: "all" (everything minus fees); optional gas = chain coin sent to every recipient as well. Plans who pays whom, checks every source's balance and gas, shows ONE window (per source: recipients and amount; recipients count; totals; transactions; fees), then executes and stops at the first failure with paid / notPaid | | collect | every source sends its whole balance of the token, minus the fee, to one own wallet; for the chain coin each source keeps its gas and leaveGas; dust is skipped | | top_up | brings every wallet of a group up to upTo: only those below it get the difference | | set_wallet | frozen: true (the wallet sends nothing), own limits, clearLimits. Tightening is immediate; anything that loosens (unfreezing, a higher limit) needs the user's confirmation window | | export_wallets | addresses of a group as CSV (name,address,group) or plain text |

How distribute plans: sources are sorted by what they can spend, recipients by amount; each recipient goes to the first source that still covers its amount plus the per-recipient fee (first fit decreasing), so the largest wallet is used up before the next one is touched and the fewest sources pay. Where the network has the Hopivia transfer contract each source pays its recipients in ONE transaction per 200 (transferBatchWithPermit, transferNativeBatch for the gas); elsewhere one transfer each. "all" searches the largest equal amount that fits, because a wallet cannot pay a fraction of a recipient. For 5 sources and 100 bots that is at most 5 transactions for the token plus 5 for the gas, fewer when one wallet holds most of the money.

Limits: transfers between the user's own wallets (distribute, collect, top_up to own wallets) do not count toward the limits and need no address confirmation; payments in the same plan to other addresses do (per-transfer per recipient, daily per source) and are marked in the window. Every payout is one hop from a source to its recipient: there is no tool and no mode that routes funds through a chain of intermediate wallets.

Claude on the phone (remote connector)

The Claude mobile app cannot start a local MCP server; it uses connectors that run on a server. Hopivia hosts one:

https://hopivia.com/api/v1/mcp

Streamable HTTP, stateless (every POST is answered with plain JSON; GET and DELETE return 405), no sign-in. Add it once on claude.ai in a browser: Settings → Connectors → Add custom connector, name Hopivia, the URL above. The connector then shows up in the Claude apps on the phone and the desktop under the same account. Claude Code can use it too: claude mcp add --transport http hopivia https://hopivia.com/api/v1/mcp.

No keys ever reach this server, so it has no wallet tools. Tools in remote mode: list_chains, list_tokens, get_quote, get_bridge_quote, get_bridge_status, check_token, get_balances, get_delegation and transfer_link. The unsigned-transaction builders (build_swap_transactions, build_bridge_transactions) are left out: a chat on the phone has nothing to sign them with.

How a transfer works:

  1. The user writes "send 50 USDT to mom on BSC, her address is 0x…".
  2. Claude calls transfer_link with the network, the token, the address the user typed, the amount and, if the user said so, "including fees" and a comment (memo). The tool checks the address (not zero, not the token contract, a mixed-case address must match its checksum), the network, the token and the amount, and asks the API for the fees: GET /api/v1/transfer/estimate.
  3. Claude answers with a link and what will happen, in the user's language:
    Ссылка для перевода: https://hopivia.com/pay?chain=bsc&token=USDT&to=0x…&amount=50&fees=ontop&lang=ru&label=%D0%9C%D0%B0%D0%BC%D0%B0
    Получатель получит: 50 USDT
    С кошелька уйдёт: 50.01 USDT
    Комиссия: ≈ $0.015
  4. The user opens the link on hopivia.com, connects their own wallet (MetaMask, Trust Wallet, WalletConnect), checks the recipient, the amount and the fees, and signs. Nothing moves before that signature; Claude cannot see whether the user signed.

The link: <site>/pay?chain=<bsc|ethereum|polygon|arbitrum|base|optimism|avalanche>&token=<symbol or 0x address>&to=<checksummed 0x address>&amount=<decimal>&fees=<ontop|included>&lang=<ru|en>[&label=<recipient name, at most 40 characters>][&memo=<comment, at most 100 bytes of UTF-8, URL-encoded>]. A comment is refused for the chain coin and on networks without the transfer contract (memo_unsupported). The fee figure is an estimate without the sender's wallet (typical gas for the network + the $0.01 service fee); the page shows the exact one. Lists of recipients (a batch link) are not supported yet.

Self-hosting: the endpoint is part of the API (services/api, route /api/v1/mcp); it runs createServer({ mode: 'remote' }) in process and calls the API's own handlers. Its rate limit is per address or key, RATE_MCP requests per minute (default 300), since connector traffic arrives from the client provider's servers.

Environment

| Variable | Default | Meaning | |---|---|---| | HOPIVIA_API_KEY | — | X-API-Key for higher limits | | HOPIVIA_API_URL | https://hopivia.com/api/v1 | API base (point it at a local API for development) | | HOPIVIA_SITE_URL | https://hopivia.com | site base for docs links and the docs resource | | HOPIVIA_WALLETS_FILE | ~/.hopivia/wallets.json | local wallets, contacts and limits | | HOPIVIA_PASSPHRASE_FILE | — | Linux without a keyring: file with the passphrase of the encrypted secrets (must be chmod 600) | | HOPIVIA_PASSPHRASE | — | the same passphrase as a value; never passed on to child processes | | RPC_<chainId> | public nodes | RPC used to send from local wallets, e.g. RPC_56 |

Programmatic use

import { createServer } from '@hopivia/mcp';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = createServer({ apiKey: process.env.HOPIVIA_API_KEY });
await server.connect(new StdioServerTransport());

Remote (HTTP) mode: handleRemoteRequest(request, { baseUrl, siteUrl, parsedBody }) takes a web Request and returns a Response; it builds a fresh createServer({ mode: 'remote' }) per request.

Development

npm install                      # at the repository root (workspaces)
npm run build -w @hopivia/mcp
npm test -w @hopivia/mcp         # unit tests with a fake API
npm run smoke:mcp                # end to end over stdio against https://hopivia.com (BASE=… to override)
npx @modelcontextprotocol/inspector node packages/mcp/dist/cli.js

Publish: npm version patch -w @hopivia/mcp && npm publish --access public -w @hopivia/mcp (needs an npm account that owns the hopivia scope).