Read any blockchain from your terminal.

The idea

One tool instead of four

A blockchain is a public ledger. Anyone can read it — you do not need an account, a password, or anyone's permission. What you normally do need is the right tool for the right chain: one for Ethereum, a different one for Solana, another for Bitcoin. Each has its own address format, its own vocabulary, and its own way of telling you the same thing.

Singularity-Agent is one tool for all of them. You ask a question, it goes and reads the ledger, and it answers in a consistent format. A Bitcoin balance and a Cosmos balance come back with the same field names, so you only have to learn them once.

It works in two places: as a command you type in a terminal, and as a plugin for Claude, so you can ask questions in plain English instead. Both run exactly the same code.

Safety

What it can and can't do

Every crypto wallet is controlled by a private key — a long secret that acts like the password to your money. Anyone who has it can spend everything. The single most important thing to know about this tool is that it never touches yours.

The practical consequence: the worst thing a bug in this tool can do is give you a wrong answer. It cannot lose your funds, because it was never able to reach them.

Setup

Install it

This takes about two minutes. You'll be typing into a terminal — Terminal on macOS, PowerShell or Git Bash on Windows, or any shell on Linux.

1. Install Node.js

   Singularity runs on Node.js version 20.10 or newer. Get it from nodejs.org if you don't have it, then check it worked:

   $ node --version Copy

   v22.19.0

   Any number 20.10 or higher is fine.

2. Download the code

   $ git clone https://github.com/DarkStarMatters/Singularity-Agent.git && cd Singularity-Agent Copy

   Cloning into 'Singularity-Agent'...

3. Install and build

   The first command downloads the libraries it depends on. The second turns the source code into something runnable.

   $ npm install && npm run build Copy

   added 214 packages in 18s

4. Make singularity available everywhere

   This lets you type singularity from any folder instead of the full path.

   $ npm link Copy

   added 1 package

5. Check that it works

   This lists every network it knows about. No lookup, no account, no API key — if you see a table, you're ready.

   $ singularity chains Copy

     ID          NAME          FAMILY  CHAIN ID     ASSET  ALIASES
     ethereum    Ethereum      evm     1            ETH    eth, mainnet, l1
     base        Base          evm     8453         ETH
     arbitrum    Arbitrum One  evm     42161        ETH    arb, arbitrum-one
     solana      Solana        svm     —            SOL    sol
     bitcoin     Bitcoin       utxo    —            BTC    btc
     cosmoshub   Cosmos Hub    cosmos  cosmoshub-4  ATOM   cosmos, atom, gaia
     …
   
     23 chain(s).

Getting started

Your first real command

Let's look inside a wallet. This one belongs to Vitalik Buterin, a co-founder of Ethereum — it's public, like every address on a blockchain.

ethereum
────────
  6.71259795 ETH  (native)

  37.192124   USDC  0xA0b86991…06eB48
  290.368219  USDT  0xdAC17F95…831ec7
  4.57207827  DAI   0x6B175474…271d0F
  1.46189817  WETH  0xC02aaA39…756Cc2

  EVM chains cannot be enumerated without an indexer, so this covers a curated
  list of major tokens only. Pass `tokens` with contract addresses to check others.
  https://etherscan.io/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

Reading the command

Add --json to any command to get machine-readable output instead of a table.

The other way to use it

Ask Claude instead of typing commands

MCP (Model Context Protocol) is a standard way to give an AI assistant real tools. Without it, an assistant answering “what's in this wallet?” is recalling something from training data — possibly years stale, possibly invented. With it, Claude runs the same commands you would and reads the actual, current answer off the chain.

The quickest way

One command, run from anywhere. Use the full path to wherever you cloned the repo, and make sure you've run npm run build first.

✓ Added stdio MCP server singularity

Or install it as a proper plugin

The repo doubles as its own single-plugin marketplace, so this is two steps. Run the first one from the folder containing Singularity-Agent — the path has to be in ./name or absolute form, and a bare . is rejected.

✓ Successfully added marketplace: singularity

✓ Successfully installed plugin: singularity-agent@singularity (scope: user)

Check it landed with claude plugin list.

Then just ask

• “What's in vitalik.eth right now?”
• “What did transaction 0xc29d744… actually do?”
• “Is it cheap to send Bitcoin at the moment?”
• “Prepare a transfer of 25 USDC on Base to this address.”

The ten tools Claude gets

Every one of them is marked read-only, and build_transfer returns a payload plus a list of warnings that Claude is instructed to show you before you sign anything.

Recipes

What you can ask it

Each of these is a real command with real output. Copy any of them and run it.

  Input    vitalik.eth
  Kind     name
  Address  0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
  Name     vitalik.eth
  Family   evm
  Chains   ethereum

  Resolves through ENS on Ethereum mainnet; the resulting address works on
  every EVM chain.

Portfolio for 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
──────────────────────────────────────────────────────
  Queried 5 chain(s).

ethereum
────────
  6.71259795 ETH  (native)
  37.192124   USDC

base
────
  0.04182 ETH  (native)

  Empty on: arbitrum, optimism, polygon

base  success
─────────────
  Hash      0xc29d74412da1bec4e662a7978c3ef993beed7833219d3362a2abca09700fdaa5
  From      0xdeaddeaddeaddeaddeaddeaddeaddeaddead0001
  To        0x4200000000000000000000000000000000000015
  Value     0 ETH
  Block     51344342
  Time      2026-09-15T13:13:51.000Z

  0xdead…0001 -> 0x4200…0015 on Base.

  https://basescan.org/tx/0xc29d744…

Fees on bitcoin
───────────────
  Simple transfer  ~0.00000054 BTC

  nextBlock      1.1 sat/vB
  within6Blocks  0.4 sat/vB
  within24Hours  0.3 sat/vB
  assumedTxSize  141 vB (1 input, 2 outputs, P2WPKH)

  Bitcoin fees are per-vbyte, so cost depends on how many UTXOs you spend,
  not on the amount sent.

{
  "selector": "0xa9059cbb",
  "signature": "function transfer(address to, uint256 amount) returns (bool)",
  "name": "transfer",
  "args": [
    { "name": "to",     "type": "address", "value": "0xd8dA6BF2…aA96045" },
    { "name": "amount", "type": "uint256", "value": "1000000" }
  ]
}

Unsigned transaction — base
───────────────────────────
  Send 25.5 USDC (0x8335…2913) to 0xd8dA…6045 on Base.

  Payload
    {
      "to":      "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "value":   "0x0",
      "data":    "0xa9059cbb000000000000000000000000d8da…01851960",
      "chainId": 8453
    }

  How to sign
    This calls transfer() on the token contract. `to` is the TOKEN address, not
    the recipient — the recipient is encoded in `data`. Sign with your own wallet.

  Warnings
    ! This transaction is unsigned. Review every field before signing.
    ! Verify the token address belongs to the asset you mean. Fake tokens
      reuse real symbols.

  Singularity holds no keys and has not signed or broadcast anything.

Endpoint health
───────────────
  ok  ethereum   440ms
  ok  base       216ms
  ok  arbitrum   212ms
  ok  solana     190ms
  ok  bitcoin    21403ms
  ok  cosmoshub  516ms
  ok  osmosis    513ms
  ok  celestia   723ms

  All endpoints reachable.

Coverage

23 chains, four families

A family is a group of chains that work the same way underneath. Learn one member and you have effectively learned the rest. You can add any chain that isn't listed here yourself — see Configuration.

You can refer to a chain by its id, a nickname, or its numeric id — eth, ethereum, mainnet and 1 all mean the same thing. Get it wrong and it suggests what you probably meant.

Plain English

Words you'll see

Crypto has a lot of jargon. Here is the subset you actually need to use this tool.

Address

A public account identifier — like a bank account number. Safe to share; that is what it is for. Every chain family writes them differently.

Private key

The secret that controls an address. Never share it, never type it into anything. Singularity never asks for one.

Transaction hash txid · signature

The receipt number for something that happened on-chain. Paste one into tx to see what it did.

Native token

The coin a chain runs on, used to pay fees — ETH on Ethereum, SOL on Solana, BTC on Bitcoin, ATOM on Cosmos Hub.

Token

Anything else living on that chain, like USDC. Identified by a contract address, which differs on every chain — the same-named token has a different address on Ethereum and Base.

Base units wei · satoshi · lamport

Chains store whole numbers only, so amounts are held in tiny units. 1 ETH is 10¹⁸ wei; 1 BTC is 100,000,000 satoshi. Singularity shows you both, and refuses to quietly round.

Gas / fee gwei · sat/vB

What you pay the network to process your transaction. It fluctuates with demand, which is why fees exists.

RPC endpoint

The server Singularity asks for data. Free public ones are included; they are slow and rate-limited. See Configuration.

ENS name

A human-readable name for an Ethereum address, like vitalik.eth. Use it anywhere an address is accepted.

Unsigned transaction

A prepared but unsigned instruction. Harmless on its own — it does nothing until a private key signs it, which happens in your wallet, not here.

Smart contract

A program stored on a chain. read_contract reads data out of one; it never writes to one.

Going further

Configuration

Faster connections

The bundled public servers need no signup, which is why they're the default — but they are throttled and sometimes just disappear. Providers like Alchemy and Infura give free API keys with far better limits. Point Singularity at one:

# The name is SINGULARITY_RPC_ + the chain id, uppercased, with - becoming _
# So base-sepolia becomes SINGULARITY_RPC_BASE_SEPOLIA
# Comma-separate several for automatic failover.

Nicknames and custom chains

Create ~/.singularity/config.json to save addresses under names you'll remember, and to add chains that aren't built in:

{
  "addressBook": {
    "savings": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
  },
  "portfolioChains": ["ethereum", "base", "solana"],
  "chains": [
    {
      "id": "my-rollup",
      "family": "evm",
      "chainId": 123456,
      "nativeCurrency": { "name": "Ether", "symbol": "ETH", "decimals": 18 },
      "rpc": ["https://rpc.my-rollup.example"]
    }
  ]
}

Now singularity balance savings -c base works, and my-rollup is a chain like any other.

Troubleshooting

If something goes wrong

Errors from this tool carry a code and a hint. The hint is usually the fix.

  INVALID_ADDRESS  "cosmos1qypqx…lzv7xu" is not a valid address on Osmosis.
  That is a "cosmos" address. It is the same account on Osmosis, re-encoded:
  osmo1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5helwsw

Honesty

What it deliberately won't do

These are real boundaries, not bugs. They're listed here, and in the tool's own output, because a confident wrong answer is worse than a clear “I can't”.

• Ethereum token lists aren't complete. Listing every token an address holds requires a paid indexing service. Without one, the tool checks a curated set of major tokens and says so. Solana and Cosmos can list everything, and do.
• No prices. It reports quantities, not dollar values.
• IBC tokens show as hashes. On Cosmos, a transferred token appears as ibc/3EF74C…. Identifying it needs a per-token lookup, so it shows the hash rather than guessing.
• Cosmos fees are an estimate. Gas prices there are set by individual validators, not the chain. Your wallet will usually re-quote.
• No CosmWasm contract queries. Contract reads cover Ethereum-style chains and Solana.
• It cannot send anything. By design, permanently.