@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.

Built for Virtuals ACP agents: point it at the agent's existing wallet and swapping signer, fund some USDC on Base, and it swaps across 8 chains with no ETH or gas tokens, ever.

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, validates every value, and writes the .env. The manual equivalent, as environment variables or a .env in the working directory:

GEODESICS_API_KEY=<your key>
AGENT_WALLET_ADDRESS=0x…             # the agent's EVM wallet
AGENT_WALLET_ID=…                    # the wallet's Privy id
AGENT_SIGNER_PRIVATE_KEY=…           # the swapping signer's key

For Solana-origin swaps, also set AGENT_SOLANA_WALLET_ADDRESS and AGENT_SOLANA_WALLET_ID.

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

The very first swap from a new chain runs a one-time ~15 second activation automatically, then swaps. First-time destination chains are onboarded automatically too (a ~1 minute pipe-activate-return flow, once per chain), so delivered assets can always swap back out. geodesics status --swap-id <id> checks on a swap; geodesics delegation and geodesics activate manage activation by hand when needed. 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.