txio/ docs
Introduction

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.

~/txio
$ 
SuiEthereumSolanaAptosSoroban
Pre-1.0, not security audited. Read for what has been checked and what is still open before you expose a deployment to an untrusted network.

Quickstart

Bring up the full stack locally with Docker, then point the CLI at it.

bash
# 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
RequirementVersion
Rust toolchainpinned via rust-toolchain.toml
Node.js20+
Docker / Composeany 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.

ComponentPathStack
CLIcli/Rust, Clap
Backendbackend/api/Rust, Axum, MongoDB
Dashboardfrontend/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.

Scoped API keys: for CI/CD and headless scripts, generate a scoped key instead of reusing a personal login token — see txio keys create --scope read. Read-only keys can call balance and call for view methods; execute-scoped keys can also submit transactions.
bash — interactive login
$ txio login
? Email: you@example.com
? Password: ••••••••••
✓ Logged in. Token stored at ~/.txio/token

CLI reference

Every command follows the same grammar:

grammar
txio [--network <net>] [--rpc-url <url>] <chain> <action> [args] [--pretty]

Per-chain commands

CommandDescription
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 portfolioNew — 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

FlagDefaultNotes
--network, -nmainnetAlso accepts testnet, devnet, localnet. Enum names aren't fully consistent across chains yet (tracked in #23)
--rpc-urlpublic nodePoint at your own infra or a local validator
--prettyoffSyntax-highlighted raw JSON instead of a table

New in v0.9

CommandPurpose
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
Removed: txio db list-users and any other command that talks to MongoDB directly with database credentials. Admin actions now go through authenticated, RBAC'd backend endpoints — the CLI never holds DB creds. See .

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:

json
{
  "jsonrpc": "2.0",
  "error": { "code": -32000, "message": "upstream node unreachable" },
  "id": 1
}
POST/auth/login

Exchanges email/password for a JWT.

request
curl -X POST https://api.txio.xyz/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"••••••••••"}'
200 response
{ "token": "eyJhbGciOi...", "expires_in": 3600 }
POST/rpc/:chain/call

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 fieldTypeNotes
methodstringChain-native RPC method name
paramsarrayPassed through as-is after name resolution
networkstringmainnet / testnet / devnet / localnet
GET/resolve?name=aliphatic.sui

Standalone name resolution, useful for pre-checking an address before building a request client-side.

ChainNamespaceStatus
SuiSuiNS (.sui)Live
EthereumENS (.eth)not implemented
Aptos / Soroban—roadmap
GET/collections

Lists saved request collections for the authenticated user's active workspace. Backs both the dashboard's Collections sidebar and txio run.

GET/portfolio?addresses[]=...&chains[]=sui,eth

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

CodeMeaning
-32000Upstream node unreachable or timed out
-32001Name resolution failed
-32002Internal 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.

ItemStatus
Account endpoints require a sessionEvery 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 storageHttpOnly 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.
OTPStored 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 webhooksOne 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 containerRuns as a non-root user. The CLI is now built from a pinned commit (build arg TXIO_CLI_REF).
Public APIScoped keys, per-key rate limits, signed webhooks with durable retries. Server-side simulation is not available (answers 501).
OpenNo 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

ItemWhy
/terminal/executeNo legitimate host-exec use case in this product; removed rather than hardened
txio db list-usersCLI holding DB credentials is itself the vulnerability; replaced by an authenticated admin API
Standalone sui_cli debug binaryFolded into txio sui call --raw
Gemini AI console pathConsolidated to a single provider to remove doc/config drift
Duplicate Sui SDKs in frontendConsolidated to one dependency

Changelog

VersionNotes
v0.9Added portfolio, watch, run, context, scoped API keys, plugin adapters. Removed /terminal/execute and db list-users.
v0.8SuiNS recursive resolution, standardized JSON-RPC error envelope
v0.7Initial five-chain CLI, Collection Runner, PTB builder (Sui)
pre-1.0, actively developed
GitHub© 2026 txio