@geodesics-protocol/cli

geodesics: gasless, self-custodial cross-chain swaps for agents, as one command. The agent holds only the token it wants to swap. Gas and fees come out of the input, funds never leave the agent's own wallet, and settlement is typically 5-15 seconds, including cross-chain.

Works with any wallet. Bring your own key (or let geodesics init create one), fund it with USDG on Robinhood Chain or USDC on Base, and the agent swaps across 8 chains with no ETH or gas tokens, ever. The wallet onboards itself during its first swap from each chain, gasless. Virtuals ACP agents are supported first-class too: point the CLI at the agent's existing wallet and swapping signer and everything works the same.

Install

npm i -g @geodesics-protocol/cli
geodesics --help

Requires Node.js 20+ and a Geodesics API key (message us to get one). QUICKSTART.md in this package walks a fresh agent to its first swap in about 5 minutes; SKILL.md is a drop-in skill file for agent runtimes (Claude Code, OpenClaw, Codex-style loops) covering commands, flags, and what to do on each error code.

Configure

geodesics init walks through the whole setup interactively: pick a wallet, validate every value, and store keys in the OS keychain, encrypted at rest, so no key sits in a plaintext file. Two wallet profiles are supported, chosen by the credentials you set:

Your own wallet (the default in init): create a fresh EVM + Solana keypair right in the wizard, or import keys you already have. The wallet onboards itself during its first swap from each chain, gasless; there is nothing to activate manually. The manual equivalent, as environment variables or a .env in the working directory:

GEODESICS_API_KEY=<your key>
AGENT_WALLET_ADDRESS=0x…             # derived from your key
AGENT_SIGNER_PRIVATE_KEY=…           # raw EVM private key (64 hex chars)
AGENT_SOLANA_WALLET_ADDRESS=…        # for Solana swaps
AGENT_SOLANA_SECRET_KEY=…            # base58 Solana secret key, for Solana-origin swaps

Virtuals ACP agent wallet: the agent's existing wallet and swapping signer, exactly as before. Setting AGENT_WALLET_ID (the wallet's Privy id) selects this profile, and AGENT_SIGNER_PRIVATE_KEY is then the base64 MIG… signer key from acp agent add-signer. For Solana-origin swaps, also set AGENT_SOLANA_WALLET_ADDRESS and AGENT_SOLANA_WALLET_ID.

The keychain is macOS Keychain, Windows Credential Manager, or Secret Service on Linux. On systems without one, such as headless servers, init asks before saving a key to the .env as plain text (a normal pattern for agent tooling; the file is written user-only); pass --allow-plaintext-key to pre-approve that in scripted setups, or provide keys as environment variables instead. A key env var always takes precedence over the keychain, which is the intended path for CI and headless agents. To remove a stored key by hand, delete the geodesics-cli entry for your wallet address in Keychain Access, secret-tool, or Windows Credential Manager.

On-chain reads (balances, sweep amounts) use public RPCs with automatic fallback across several providers. To pin a dedicated endpoint, set the chain's env var: ETH_RPC_URL, BASE_RPC_URL, ARBITRUM_RPC_URL, OPTIMISM_RPC_URL, POLYGON_RPC_URL, BNB_RPC_URL, ROBINHOOD_RPC_URL, or SOLANA_RPC_URL.

Swap

# same-chain
geodesics swap --token-in usdc --chain-in base --amount-in 5 --token-out virtual --chain-out base

# cross-chain, delivered on Solana (the agent needs zero SOL)
geodesics swap --token-in usdc --chain-in base --amount-in 5 --token-out sol --chain-out solana

# and back: Solana origin
geodesics swap --token-in sol --chain-in solana --amount-in 0.02 --token-out usdc --chain-out base

# price a route without executing
geodesics swap --token-in usdc --chain-in base --amount-in 100 --token-out eth --chain-out ethereum --dry-run

# withdraw: move the chain's stable (USDC or equivalent) to another wallet, gasless
geodesics withdraw --chain base --amount 25 --to 0xYourOtherWallet

The very first swap from a new chain onboards the wallet automatically: with your own wallet the swap itself carries a one-time signed authorization (no extra time, no gas); a Virtuals agent wallet runs a one-time ~15 second activation first. Virtuals destination chains are onboarded automatically too (a ~1 minute pipe-activate-return flow, once per chain), so delivered assets can always swap back out; your own wallet needs none of that, since it onboards itself whenever it first swaps out of a chain. geodesics withdraw moves the chain's canonical stable to another wallet (same-chain a small transfer fee comes out of the amount, which is what makes it gasless; --chain-out bridges it instead). geodesics status --swap-id <id> checks on a swap; geodesics delegation and geodesics activate manage activation by hand when needed. geodesics balance --chain base --token usdc reads what the wallet holds on a chain over public RPCs (no API key or signer needed), handy for confirming funds landed. Add --json to any command for machine-readable output in agent loops.

Chains and tokens

Base, Ethereum, Arbitrum, Optimism, Polygon, BNB Chain, Robinhood Chain, and Solana. Token aliases: usdc, virtual, weth, eth, pol, bnb, usdg, sol; any other token works as a raw address with --amount-raw in base units. On BNB, usdc is the Binance-Peg token (18 decimals, handled automatically). Robinhood Chain's stable is usdg.

Building a server-side integration instead? The same engine ships as a typed library: @geodesics-protocol/sdk.

Questions, keys, or anything broken: message us directly or join our Telegram community. We iterate fast.