01start here
Read any blockchain
from your terminal.
One tool for Ethereum, Solana, Bitcoin and Cosmos. Check what is in a wallet, look up what a transaction did, see what fees cost right now — and get the answer in the same shape no matter which chain it came from.
←→ move between panels · ` opens the console from anywhere · Esc closes whatever is in front.
02the payoff
Paste anything. Find out what it is.
A beginner's first problem is not installing a tool. It is that somebody sent them
0xd8dA…96045 and they have no idea whether that is a wallet, a receipt,
a token or a typo — or which of thirty-two chains it belongs to.
So start there. This box is the real tool, running for real, right now: it asks the same read-only service the command line asks, and it cannot ask for your keys because it has nowhere to put them.
Every number above arrives from a chain while you wait, so it will not match this page tomorrow — that is the point. If the endpoint is having a bad day it says so rather than showing you a stale answer.
Three ways to use this, pick one
The seven panels after this one cover three different jobs. Choosing a route does not hide anything — every panel stays one click away on the rail below — it just changes what the Next button means.
03the 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.
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.
It can read
- Balances of any public address
- What a past transaction did
- Current network fees
- Data stored in smart contracts
- Prepare an unsigned payment for you
It cannot
- Ask for, store, or read a private key
- Sign a transaction
- Send or broadcast anything
- Move a single coin, in any circumstance
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.
04the console
Run it without installing it.
This is not a video of a terminal. In Live mode every command you type really runs — any address, any of the thirty-two chains — through the same read-only service the installed tool uses. Type something wrong and it will tell you what it needed, the way the real thing does.
Replay mode exists for when a free public node is having a bad day, or you are reading this on a train. It shows answers recorded from earlier real runs, and labels them as recorded, because a stale number that looks current is the one failure this whole project is arranged against.
help lists every command
that really runs; clear wipes the screen. Try tx with any
transaction hash and watch it work out which chain the thing is on.
It follows you to every other panel, keeping its history — so you can try a command while reading how it works. ` opens and closes it from anywhere.
05setup
Put it on your machine.
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.
-
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:
v22.19.0Any number 20.10 or higher is fine.
-
Download the code
Cloning into 'Singularity-Agent'... -
Install and build
The first command downloads the libraries it depends on. The second turns the source code into something runnable.
added 214 packages in 18s -
Make
singularityavailable everywhereThis lets you type
singularityfrom any folder instead of the full path.added 1 package -
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.
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 … 32 chain(s).
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
| Part | What it is |
|---|---|
singularity | The tool itself. |
balance | What you want — the question you're asking. |
vitalik.eth | Who you're asking about. A name, an address, or a nickname you've saved. |
--chain ethereum | Which network to look on. -c is the short form. |
The answer has names in it too: the that pays Ethereum's fees, the balances underneath it, and the the amounts were scaled from. Any word underlined like those is one you can hover or tap for a one-line definition, anywhere on this page — no need to scroll away and lose your place.
Add --json to any command to get machine-readable output instead of a table.
06with claude
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 — nothing to install
The tools run on our server, so your machine needs no clone, no build and no Node.js. One URL is the whole setup.
✓ Added HTTP MCP server singularity
Twenty-three tools. Read-only. No account, no key, no credentials.
Or run it on your own machine
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)
/plugin install does not take a folder path
It expects a plugin-name@marketplace-name id. Handing it a path fails
with “Marketplace not found” — add the marketplace first, as above. Both commands
also work inside a session as /plugin marketplace add and
/plugin install.
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.”
Eight questions worth stealing
Each is a real command with real output. Open one to read it in full, then copy it.
07for developers
Build something on it.
Everything above asks one question and reads one answer. An application is different: it runs for weeks, asks the same question hundreds of times an hour, and sooner or later has to write. singularity-sdk is the package for that — a separate install, versioned separately, built on the same engine as the commands on this page.
✓ Created my-app from the "reader" template.
cd my-app
npm install
npm start
It reads public endpoints and needs no key to run.
reader, monitor, agent. All of them run on the first try.The same answers, in code
Set your defaults once, then ask. The result carries the same honesty the terminal output does — including the note about what a token list covers.
import { createSingularity } from 'singularity-sdk';
const sdk = createSingularity({ chain: 'ethereum', budget: { maxItems: 8 } });
const balance = await sdk.balance({ address: 'vitalik.eth', includeTokens: true });
balance.native.amount.formatted // '6.71259795'
balance.tokenCompleteness.kind // 'curated' — read this before the list
Watching, rather than asking again
Poll a balance, a chain's head, or one transaction until it's confirmed. These are polling loops and the SDK says so plainly — there's no push feed hiding underneath.
sdk.watch.balance({ address: 'vitalik.eth' }, ({ value, previous }) => {
if (!previous) return; // the first reading isn't a change
notify(previous.native.amount.formatted, value.native.amount.formatted);
}, { intervalMs: 15_000 });
Your keys stay yours — still
The tool on this page cannot sign, and neither can the SDK. But an app that can only read isn't much of an app, so the SDK defines the shape of a signer and ships none: you plug in the browser wallet, hardware device or key service you already use, and it never hands a secret to the library.
Until you do, the write methods don't exist — and your editor says so before you ever run anything.
const sdk = createSingularity({ chain: 'ethereum' });
await sdk.build.transfer({ to: 'vitalik.eth', amount: '0.1' }); // fine
await sdk.write.transfer({ to: 'vitalik.eth', amount: '0.1' });
~~~~~
Property 'transfer' does not exist on type 'SignerRequired'.
Full documentation, the signer guide and four runnable examples: singularity-sdk on GitHub.
08look it up
Everything else, when you need it.
The long material does not belong in your way. Each of these slides in over whatever panel you are on, and Esc puts it back.