One terminal, every chain
txio is a multi-chain developer toolkit: a single CLI, a single backend, and a single command grammar for Sui, Ethereum, Solana, Aptos, and Soroban. This is the reference documentation for the CLI, the REST API behind it, and the dashboard.
$ Quickstart
Bring up the full stack locally with Docker, then point the CLI at it.
# 1. configure the backend cp .env.example backend/api/.env # set MONGO_INITDB_ROOT_USERNAME/PASSWORD, JWT_SECRET (32+ chars), # BREVO_API_KEY, and your chosen AI provider key # 2. start backend + dashboard + MongoDB docker-compose up -d # 3. authenticate the CLI cd cli && cargo run -- login # 4. make a call cargo run -- sui balance aliphatic.sui
| Requirement | Version |
|---|---|
| Rust toolchain | pinned via rust-toolchain.toml |
| Node.js | 20+ |
| Docker / Compose | any recent release |
Architecture
Five components share one backend. The CLI and dashboard are both clients of the same API; the ops bot is internal-only and never touches user data.
| Component | Path | Stack |
|---|---|---|
| CLI | cli/ | Rust, Clap |
| Backend | backend/api/ | Rust, Axum, MongoDB |
| Dashboard | frontend/ | Next.js, React, Tailwind |
| Desktop (paused) | desktop/ | Electron |
| Ops bot (internal) | Txio-telegram-bot/ | Node/TypeScript |
Adding a chain means implementing ChainAdapter (call_rpc, get_balance) in one new file under cli/src/chains/ and registering it in factory.rs — no changes to the parser or the other adapters.
Authentication
txio login runs an interactive flow and stores a JWT at ~/.txio/token. Every RPC call made while logged in is attributed to your account automatically — no extra flags needed.
txio keys create --scope read. Read-only keys can call balance and call for view methods; execute-scoped keys can also submit transactions.$ txio login ? Email: you@example.com ? Password: •••••••••• ✓ Logged in. Token stored at ~/.txio/token
CLI reference
Every command follows the same grammar:
txio [--network <net>] [--rpc-url <url>] <chain> <action> [args] [--pretty]
Per-chain commands
| Command | Description |
|---|---|
txio sui balance <address|.sui> | Balance lookup, resolves SuiNS names automatically |
txio eth balance 0x... | Ethereum balance. ENS resolution is not yet implemented |
txio solana balance <address> | Balance in lamports/SOL |
txio aptos balance <address> | Balance lookup |
txio soroban balance <address> | Balance lookup |
txio <chain> call --method <m> [--params '[...]'] | Raw JSON-RPC passthrough for any chain |
txio <chain> estimate [--method <m>] | New — unified gas/fee estimate across all five chains |
txio watch <address> --chain <c> | New — stream live balance and transaction updates |
txio portfolio | New — aggregate balances for a set of addresses across all chains |
txio run <script.yaml> | New — batch-execute a sequence of calls, CLI equivalent of the dashboard's Collection Runner |
Global flags
| Flag | Default | Notes |
|---|---|---|
--network, -n | mainnet | Also accepts testnet, devnet, localnet. Enum names aren't fully consistent across chains yet (tracked in #23) |
--rpc-url | public node | Point at your own infra or a local validator |
--pretty | off | Syntax-highlighted raw JSON instead of a table |
New in v0.9
| Command | Purpose |
|---|---|
txio context use <name> | Switch between named environments (network + keys + RPC URL) in one command, replaces the earlier ambiguous profile stub |
txio keys create --scope <read|execute> | Issue scoped API keys for CI/CD, separate from personal login tokens |
txio adapters install <crate> | Install a community ChainAdapter without rebuilding core — chains are now a plugin, not a PR |
API reference
All endpoints below are used by both the CLI and the dashboard. Requests and responses are JSON; authenticated routes expect Authorization: Bearer <jwt|api-key>.
Response envelope
Errors are always normalized to JSON-RPC 2.0-style error objects, regardless of whether the failure came from txio itself or from an upstream node:
{
"jsonrpc": "2.0",
"error": { "code": -32000, "message": "upstream node unreachable" },
"id": 1
}Exchanges email/password for a JWT.
curl -X POST https://api.txio.xyz/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"you@example.com","password":"••••••••••"}'{ "token": "eyJhbGciOi...", "expires_in": 3600 }Chain-agnostic RPC passthrough. :chain is one of sui, ethereum, solana, aptos, soroban. Any .sui name found anywhere in params — including nested inside Move type tags — is resolved before the call is forwarded.
| Body field | Type | Notes |
|---|---|---|
method | string | Chain-native RPC method name |
params | array | Passed through as-is after name resolution |
network | string | mainnet / testnet / devnet / localnet |
Standalone name resolution, useful for pre-checking an address before building a request client-side.
| Chain | Namespace | Status |
|---|---|---|
| Sui | SuiNS (.sui) | Live |
| Ethereum | ENS (.eth) | not implemented |
| Aptos / Soroban | — | roadmap |
Lists saved request collections for the authenticated user's active workspace. Backs both the dashboard's Collections sidebar and txio run.
New endpoint backing txio portfolio — aggregates balances for one or more addresses across the requested chains in a single call, so the dashboard and CLI don't have to fan out five separate requests client-side.
Error codes
| Code | Meaning |
|---|---|
-32000 | Upstream node unreachable or timed out |
-32001 | Name resolution failed |
-32002 | Internal txio error |
Guide: Name resolution
Instead of exact-matching a name string, the resolver runs a recursive scan (([a-zA-Z0-9-]+\.sui)) across the entire request body. This matters because developers often embed names inside Move type tags, e.g. 0x...::Coin<names.sui> — a flat match would miss it. Every occurrence, at any nesting depth, is resolved before the call goes out.
Guide: PTB builder
A node-based, infinite-canvas editor for Programmable Transaction Blocks. Current node types: Object (input coins/objects), SplitCoins, and Transfer. Every builder run supports Simulate, which dry-runs the transaction before you commit on-chain.
Guide: Collections & contexts
Collections group saved requests into folders and can be run end-to-end with the Collection Runner (pass/fail per request, live progress, timing). txio context mirrors this on the CLI side: named bundles of network, RPC URL, and key material you can switch between with one command, e.g. txio context use staging.
Security & hardening status
State of each item, checked against the code and covered by tests where noted. Nothing here is a claim that txio is production-hardened; open items are listed as open.
| Item | Status |
|---|---|
| Account endpoints require a session | Every route except sign-in, OTP, password reset and OAuth needs one; a test fails the build if a new handler forgets. Changing email or deleting the account also needs a one-time code. |
| Session storage | HttpOnly cookie for the browser (script cannot read it), CSRF header on writes, and logout, revoke and account delete end the session on the server. CLI and SDK use API keys. Needs COOKIE_* settings that match your domains. |
| OTP | Stored hashed; 5-minute validity enforced in code (10-minute Mongo TTL is cleanup); 60-second resend cooldown per email; locks after 5 wrong codes; per-IP limits. No hourly cap per email yet. |
| SSRF via custom rpc_url and webhooks | One shared guard blocks non-HTTPS, loopback, private, link-local, CGNAT and IPv4-in-IPv6, resolves DNS, and redirects are not followed. Open: DNS rebinding between check and connect (needs an egress proxy), so this is mitigated, not closed. |
| Backend container | Runs as a non-root user. The CLI is now built from a pinned commit (build arg TXIO_CLI_REF). |
| Public API | Scoped keys, per-key rate limits, signed webhooks with durable retries. Server-side simulation is not available (answers 501). |
| Open | No third-party security review. Rate limits are per instance (in memory). Spend-policy checks on API execute use a USD value of 0, so limits in USD do not apply there yet. |
Deprecated / removed
| Item | Why |
|---|---|
/terminal/execute | No legitimate host-exec use case in this product; removed rather than hardened |
txio db list-users | CLI holding DB credentials is itself the vulnerability; replaced by an authenticated admin API |
| Standalone sui_cli debug binary | Folded into txio sui call --raw |
| Gemini AI console path | Consolidated to a single provider to remove doc/config drift |
| Duplicate Sui SDKs in frontend | Consolidated to one dependency |
Changelog
| Version | Notes |
|---|---|
v0.9 | Added portfolio, watch, run, context, scoped API keys, plugin adapters. Removed /terminal/execute and db list-users. |
v0.8 | SuiNS recursive resolution, standardized JSON-RPC error envelope |
v0.7 | Initial five-chain CLI, Collection Runner, PTB builder (Sui) |