🐍 near-hydra

One NEAR account. Every chain. Every agent.

The unified CLI + MCP server for NEAR's chain-abstraction stack. Signs transactions across 10 chains from a single account. Built for AI agents and humans.

Try it right now (zero setup)

npx -y near-hydra account balance-all near

Returns ten real chain addresses + balances derived from the NEAR account near. No config file, no key, no signup. Defaults to read-only mainnet. Requires Node ≥ 20.

Latest release: v0.5.0 (agent key generator, message signing, MCP resources, ensure-gas).

What you can do, in two lines

$ hydra account balance-all near
# → ten chains, ten addresses, ten balances. From one NEAR account.

$ hydra swap execute --from nep141:eth-0xdac17...omft.near \
    --to nep141:sol.omft.near --amount 1000000 \
    --recipient <your-solana-addr> --broadcast
# → USDT on Ethereum becomes SOL on Solana. One MCP call. No bridge UI.

near-hydra makes NEAR's primitives feel like a single product:

• Chain Signatures — one NEAR account derives + signs on Bitcoin, Ethereum, Polygon, Arbitrum, Base, Optimism, BNB Chain, Avalanche, Aurora, Solana

• NEAR Intents — high-level cross-chain swaps via the 1Click API, auto-routed by origin asset

• NEAR-native — accounts, contracts, FTs, view + write

CLI for humans. MCP server for Claude Code, Cursor, OpenAI Agents SDK, anything that speaks Model Context Protocol.

Chain support matrix

Quickstart

From npm (recommended)

npm install -g near-hydra            # CLI: `near-hydra ...`
npx -y near-hydra account balance-all near    # ← real on-chain data, no setup

Or for the MCP server:

npm install -g near-hydra-mcp        # exposes `near-hydra-mcp` binary

From source

git clone https://github.com/nikshepsvn/near-hydra.git
cd near-hydra && npm install && npm run build
alias hydra="node $(pwd)/packages/cli/dist/index.js"
hydra account balance-all near

Requires Node ≥ 20. Defaults to mainnet, read-only.

Use from Claude Code (or any MCP client)

After npm install -g near-hydra-mcp, add to ~/.claude/settings.json:

{
  "mcpServers": {
    "near-hydra": {
      "command": "near-hydra-mcp",
      "env": { "NEAR_HYDRA_NETWORK": "mainnet" }
    }
  }
}

Or with npx (no global install):

{
  "mcpServers": {
    "near-hydra": {
      "command": "npx",
      "args": ["-y", "near-hydra-mcp"],
      "env": { "NEAR_HYDRA_NETWORK": "mainnet" }
    }
  }
}

Restart Claude Code. Try:

What's the Bitcoin address derived from near.near?

Claude calls hydra_address_derive and returns a real BTC address.

Your first cross-chain swap, step-by-step

Goal: swap 1 wNEAR for SOL on Solana, delivered to your derived Solana address.

# 1. Set up signing
export NEAR_HYDRA_READ_ONLY=false
export NEAR_HYDRA_ACCOUNT_ID=alice.near
export NEAR_HYDRA_PRIVATE_KEY="ed25519:..."

# 2. Find your Solana address
hydra address derive -c solana -p alice.near
# → "address": "vquhA...n4MB"

# 3. Dry-run the swap (verify the plan, no funds moved)
hydra swap execute \
  --from nep141:wrap.near --to nep141:sol.omft.near \
  --amount 1000000000000000000000000 --recipient vquhA...n4MB

# 4. Execute (this moves real money)
hydra swap execute \
  --from nep141:wrap.near --to nep141:sol.omft.near \
  --amount 1000000000000000000000000 --recipient vquhA...n4MB \
  --broadcast

# 5. Watch settlement
hydra swap status <depositAddress-from-step-4>

The same flow works EVM-origin: pass nep141:eth-0x...omft.near as --from and hydra auto-routes to a Chain-Signature-signed ERC-20 transfer on Ethereum.

Documentation

Examples / cookbook:

• Multi-chain identity in 30 seconds — derive addresses on every chain from one NEAR account.

• Wire into Claude Code — MCP setup, sample prompts, signing flow, safety levers.

• Your first cross-chain swap — NEAR-origin, EVM-origin, and SPL-origin walkthroughs.

• Troubleshooting — RPC rate limits, MPC contract changes, gas, ESM bug, common gotchas.

Reference:

• Concepts — Chain Signatures, NEAR Intents, account model, why this only works on NEAR.

• Tool reference — every MCP tool, every input field, every output shape.

Tools (21 total)

Read-only — safe by default

Signing — gated, dry-run by default

Every signing tool throws unless policy.readOnly = false, and defaults dry: true. See SECURITY.md.

How it works

┌─────────────────────────────────────────────────────────────┐
│  Claude Code / Cursor / Agents SDK / human in the terminal  │
└─────────────────────────────────────────────────────────────┘
                              │
                MCP (stdio)   │   CLI (commander)
                              ▼
        ┌───────────────────────────────────────┐
        │            near-hydra core            │
        │  ┌─────────────────────────────────┐  │
        │  │  policy │ config │ state cache  │  │
        │  └─────────────────────────────────┘  │
        └─────┬─────┬──────┬────────┬───────────┘
              │     │      │        │
              ▼          ▼            ▼              ▼
        @near-js/*   chainsig.js   1Click SDK   viem / @solana/web3.js
        (NEAR)       (MPC across   (Intents)    (chain RPCs)
                      every chain)

near-hydra doesn't reinvent any protocol. It composes the official libraries behind one config, one auth model, one tool surface — and adds the connective tissue (memoization, error mapping, policy, dry-run-by-default) that an autonomous agent actually needs.

Configuration

Defaults work out of the box. Override via ~/.near-hydra/config.json or env vars.

Most useful env vars

<CHAIN> is one of NEAR, ETHEREUM, POLYGON, ARBITRUM, BASE, OPTIMISM, BNB, AVALANCHE, AURORA, SOLANA, BITCOIN_MEMPOOL. When public endpoints rate-limit you, point at Alchemy / QuickNode / dRPC / your own infra.

Config file example

{
  "network": "mainnet",
  "account": {
    "id": "alice.near",
    "privateKey": "ed25519:..."
  },
  "policy": {
    "readOnly": false,
    "maxValueNear": "5"
  },
  "rpc": {
    "ethereum": "https://your-ethereum-rpc",
    "solana": "https://your-solana-rpc"
  },
  "oneClick": {
    "apiKey": "your-1click-partner-key"
  }
}

Architecture

core/        config • signers • Chain Signatures wrappers • 1Click client • policy
mcp-server/  exposes core as MCP tools (stdio transport)
cli/         exposes core as commander subcommands

Built on:

• chainsig.js — cross-chain MPC signing

• @defuse-protocol/one-click-sdk-typescript — NEAR Intents 1Click

• @near-js/accounts, /providers, /signers, /crypto, /utils — NEAR-native ops (modular packages, v2.x)

• viem — EVM client

• @solana/web3.js + @solana/spl-token — Solana + SPL token clients

• @modelcontextprotocol/sdk — MCP server

Roadmap

FAQ

How is this different from other NEAR tools?

We don't compete with these — we compose them. near-hydra-core depends on chainsig.js, the 1Click SDK, and the modular @near-js/* packages. The agent-ergonomic surface and the safety layer are what's new.

Is this affiliated with NEAR Foundation?

No. It's an unofficial open-source project built on top of NEAR's official libraries. We file upstream issues for bugs we find.

Why "hydra"?

Many heads, one body. Each chain is a head. The NEAR account is the body. The agent has many faces but one identity. Cut off a chain — derive again. The agent endures.

Does this expose my private key to the LLM?

No. Private keys live in your local config or env vars. The LLM calls MCP tools that pass through near-hydra, which signs locally with your key. The LLM never sees the key bytes. That said — a malicious or prompt-injected LLM that's been given signing permission can ask hydra to send funds. Use function-call access keys with capped allowances (see policy and SECURITY.md).

Can I add more chains?

Yes — any chain chainsig.js already supports (Cosmos, XRP, SUI, Aptos) just needs adapter wiring + RPC config. PRs welcome. Chains MPC doesn't yet support need protocol-level work.

How is this funded?

Self-funded; not seeking grants currently. If you want to support, contribute PRs or upstream chainsig.js fixes.

Contributing

Issues + PRs welcome. See CONTRIBUTING.md. The roadmap above is the priority list.

License

Apache-2.0 — security-related disclosures: SECURITY.md