<div align="center">

🐍 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.

<br>

</div>

---

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

Chain	View	Derive	Native send	Token send	As swap origin	As swap dest
NEAR	✅	n/a	✅	✅ NEP-141	✅	✅
Bitcoin	✅	✅	✅	n/a	✅	✅
Ethereum	✅	✅	✅	✅ ERC-20	✅	✅
Polygon	✅	✅	✅	✅ ERC-20	✅	✅
Arbitrum	✅	✅	✅	✅ ERC-20	✅	✅
Base	✅	✅	✅	✅ ERC-20	✅	✅
Optimism	✅	✅	✅	✅ ERC-20	✅	✅
BNB Chain	✅	✅	✅	✅ ERC-20	✅	✅
Avalanche	✅	✅	✅	✅ ERC-20	✅	✅
Aurora	✅	✅	✅	✅ ERC-20	✅	✅
Solana	✅	✅	✅	✅ SPL	✅ native + SPL	✅

---

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

Tool	What it does
hydra_config_show	Show the active configuration
hydra_account_view	NEAR account state — balance, storage, code hash
hydra_contract_view	Read-only contract view call
hydra_address_derive	Derive a foreign-chain address from a NEAR account via MPC
hydra_address_balance	Native-asset balance on a foreign chain
hydra_account_balance_all_chains	Derive + balance across every supported chain
hydra_swap_tokens	List 1Click-supported tokens
hydra_swap_quote	Get a cross-chain swap quote
hydra_swap_status	Check swap execution status
hydra_swap_submit_deposit	Notify 1Click of broadcast deposit tx

Signing — gated, dry-run by default

Tool	What it does
hydra_send_near	Send native NEAR
hydra_send_ft	Send a NEP-141 fungible token
hydra_contract_call	State-changing NEAR contract call
hydra_send_evm	Send on any EVM chain via Chain Signatures (native or ERC-20)
hydra_send_btc	Send BTC via Chain Signatures
hydra_send_solana	Send native SOL via Chain Signatures
hydra_send_spl	Send a Solana SPL token via Chain Signatures (auto-creates dest ATA)
hydra_swap_execute	End-to-end cross-chain swap, auto-routed by origin chain
hydra_create_agent_key	Mint scoped NEAR function-call access keys for an autonomous agent
hydra_sign_message	Sign EIP-191 / EIP-712 / Ed25519 messages from a derived address
hydra_ensure_gas	Top up a derived foreign-chain address with native gas via 1Click

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

Variable	Purpose
NEAR_HYDRA_NETWORK	mainnet or testnet
NEAR_HYDRA_ACCOUNT_ID	Your NEAR account
NEAR_HYDRA_PRIVATE_KEY	ed25519:... (only needed for signing)
NEAR_HYDRA_READ_ONLY	false to enable signing (default true)
NEAR_HYDRA_MAX_VALUE_NEAR	Cap a single NEAR transfer (e.g. "5")
NEAR_HYDRA_MAX_VALUE_WEI	Cap a single EVM native transfer in wei (does not cap ERC-20 transfers — those go through data not value)
NEAR_HYDRA_RPC_<CHAIN>	Override any chain's RPC
NEAR_HYDRA_MPC_CONTRACT	Override MPC contract (advanced)
NEAR_HYDRA_ONECLICK_API_KEY	1Click partner key (skips 0.2% fee)
NEAR_HYDRA_ONECLICK_BASE_URL	Override 1Click base URL (advanced)
NEAR_HYDRA_CONFIG	Path to alternate config file

<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

Version	Scope
v0.1	Read-only across 10 chains; 1Click swap discovery
v0.2	NEAR sends + contract writes; EVM send via Chain Signatures; NEAR-origin swap_execute; policy layer
v0.3	BTC + native-Solana sends; swap_execute auto-routes 4 origin chains
v0.4	Solana SPL token send (auto-creates dest ATA); SPL-origin swap_execute via real-mint lookup; Solana broadcast bug fix
v0.5 (latest, on npm)	Function-call access key generator (hydra_create_agent_key); arbitrary message signing (hydra_sign_message — EIP-191/712/Ed25519); MCP resources for chains/tokens/config/policy; auto-bootstrap gas via 1Click (hydra_ensure_gas)
v0.6	Raw NEAR Intents (custom intents, solver-relay); Omnibridge; nep245 multi-token bridges; Shade Agent deploy/whitelist; NEP-366 meta-transactions; opt-in ensureGas: true flag on existing send tools
v1.0	Per-tool confirmations; allowlist enforcement; hydra do "<natural language>" goal verb

---

FAQ

How is this different from other NEAR tools?

	Chain Signatures	NEAR Intents	Agent-native (MCP)	Scope
nearai/near-mcp	❌	❌	✅	NEAR-native + Ref Finance (23 tools)
IQAIcom/mcp-near-intents	❌	✅ 1Click only	✅	Intents quotes (5 tools)
Bitte Protocol make-agent	❌	❌	publishing-only	Agent registry + AI wallet
chainsig.js (lib)	✅	❌	❌	Cross-chain signing library
@defuse-protocol/intents-sdk (lib)	❌	✅	❌	Intents library
near-hydra	✅ 10 chains	✅ + auto-routing	✅ 21 tools + 4 resources	All of NEAR's stack, composed

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

---

<div align="center"> _{Built with love by people who think NEAR's chain abstraction deserves a worthy CLI.} </div>