Quickstart

Geodesics gives your agent gasless, self-custodial swaps across EVM chains and Solana with one command. The agent holds only the token it wants to swap: gas and fees come out of the input, and funds never leave the agent’s own wallet. Settlement is typically 5-15 seconds, including cross-chain. Any wallet works: geodesics init can create a fresh one for the agent, you can bring your own key, or a Virtuals ACP agent plugs in the wallet it already has. The fastest path is one prompt. If you drive an AI coding agent such as Claude Code or Cursor, paste this and let it run the setup end to end:

Setup Geodesics swaps. Use https://geodesics.ai/llms.txt as reference

The assistant reads this quickstart through that reference and runs the steps below for you, pausing only when it needs a value from you. Prefer to do it by hand? The rest of this page is the manual walkthrough. Building a server-side platform integration instead? Jump to the TypeScript SDK, or drop to the REST API for the raw wire.

Prerequisites

Node.js 20 or newer
A Geodesics API key, created self-service in the console
Only for the Virtuals path: an agent with an ACP wallet; new to Virtuals? See Set up a Virtuals agent

Install

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

Set up

geodesics init

The guided setup first asks which wallet the agent swaps with:

Its own wallet (default)
A Virtuals ACP agent wallet

Create a fresh EVM + Solana keypair right in the wizard, or import keys you already have. The addresses are derived from the keys, so there is nothing to copy from anywhere, and the wallet onboards itself during its first swap from each chain, gasless: nothing to activate, no other signups.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 characters)
AGENT_SOLANA_WALLET_ADDRESS=…        # for Solana swaps
AGENT_SOLANA_SECRET_KEY=…            # base58 secret key, for Solana-origin swaps

One-time dashboard prep first: open the agent’s Wallet tab, find the Signers section, and Add Key. Copy the private key shown at creation: a long base64 value starting MIG. It is shown only once; afterwards the dashboard displays only its public half, which will not work in the config. The full Virtuals-side walkthrough is in Set up a Virtuals agent.

Give that signer No Policy, or, for production, a custom allowlist scoped to the swap contracts. Under the default “Virtuals Only” policy, every swap pauses for manual owner approval, so a headless agent cannot swap unattended.

The manual equivalent; setting AGENT_WALLET_ID is what selects this profile:

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 signer's private key (starts MIG…)

For swaps to or from Solana, also set AGENT_SOLANA_WALLET_ADDRESS; Solana-origin swaps additionally need AGENT_SOLANA_WALLET_ID, a different id than the EVM one, shown on EconomyOS under the agent’s Wallet > Signers tab.

Either way, init validates every value, stores wallet keys in the OS keychain, encrypted at rest, and saves the rest to a .env in this project, or to ~/.geodesics/.env for all your projects if you choose, then shows the wallet to fund. On a system without a keychain, such as a headless server, it asks before saving a key to the .env; in CI, provide keys as shell environment variables instead. It finishes by asking which AI tools you use and drops the SKILL.md agent skill in the right place and format for each: Claude Code, Cursor, Codex/AGENTS.md, or a custom path. Running any command before you’re set up launches init automatically. A working-directory .env takes precedence over ~/.geodesics/.env, and real environment variables override both; the full variable reference is on the CLI page.

Fund the wallet

Before the first swap, fund the agent’s wallet with USDG on Robinhood Chain or USDC on Base. That is all it needs: no gas token on any chain, ever, Solana included. The one exception is a same-chain Solana swap, which needs ~0.005 SOL for network fees; the agent can get that gaslessly with the routes below.Confirm the funds landed. This is a public-RPC read and needs no API key:

geodesics balance --chain robinhood --token usdg
geodesics balance --chain base --token usdc

Swap

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

The very first swap from a new chain onboards the wallet automatically. With the agent’s 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, then swaps. Expected output ends with status settled and the origin and delivery transaction hashes.

Routes to try next

# 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

# into Robinhood Chain (its stable is USDG)
geodesics swap --token-in usdc --chain-in base --amount-in 5 --token-out usdg --chain-out robinhood

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

# move stables out of the agent wallet, still gasless
geodesics withdraw --chain base --amount 5 --to 0xRecipient

Geodesics covers Base, Ethereum, Arbitrum, Optimism, Polygon, BNB, Robinhood Chain, and Solana; the full chain, token, and alias reference is in Supported chains. Any token can be passed as a raw address; for tokens without a built-in alias, pass --amount-raw in base units. On BNB, usdc is the Binance-Peg token with 18 decimals, handled automatically. Robinhood Chain’s stable is usdg, both directions live. With the agent’s own wallet, first-time destination chains need no preparation: whatever lands there can always swap back out, because the wallet onboards itself whenever it first swaps out of a chain. A Virtuals agent wallet swapping into a new EVM chain runs a one-time activation flow automatically instead; it takes about a minute (~1 unit of the origin’s stable pipes over, the chain activates, the remainder returns), so keep ~1 USDC or USDG spare on the origin chain for it. Add --json for machine-readable output in agent loops; a swap result may include a warnings array with a follow-up command worth running.

If something goes wrong

Symptom	Fix
Swap pauses for approval (Virtuals)	The signer policy is still “Virtuals Only”: see the Virtuals tab in Step 2
`NEEDS_DELEGATION`	Virtuals: run `geodesics activate --chain <origin>` and retry; the swap normally does this itself. Own wallet: should not occur; retry the swap once
”delegated to another provider” / `UNSUPPORTED_DELEGATION`	The wallet is already delegated elsewhere on that chain, and Geodesics never replaces an existing delegation: use a different wallet there
”Activation … rejected by the gas sponsor”	The wallet holds no stable on that chain: fund it per Step 3 and retry
”AGENT_SIGNER_PRIVATE_KEY looks like …”	The key does not match the profile: a raw hex key with no `AGENT_WALLET_ID` for the agent’s own wallet, the `MIG…` key with `AGENT_WALLET_ID` for a Virtuals agent
”controls 0x…, not the configured …”	The saved key and `AGENT_WALLET_ADDRESS` disagree: re-run `geodesics init`
”Privy returned an empty signature”	`AGENT_SOLANA_WALLET_ID` is missing or is the EVM id
`NEEDS_LARGER_SIZE`	The amount is too small for that route: raise it
Swap comes back `refunded`	Price moved past slippage: retry with `--slippage-bps 300`, or set it once with `geodesics config set slippage 300`
Still `pending` at timeout	`geodesics status --swap-id <id>`: it usually settles moments later

Every error comes back with a code and a plain-language message; the Agent skill page documents what an agent should do for each code.

Go deeper

Agent skill

The one-prompt setup, --json mode for agent loops, and the full error table.

CLI

Every command, flag, and configuration variable.

TypeScript SDK

The same engine as a typed library: runnable walkthroughs for any raw key and for Virtuals ACP agents.

REST API

The raw wire: quote, build, sign, submit, and poll with any HTTP client.

Get Started

Integrations

Concepts

Guides

Prerequisites

Routes to try next

If something goes wrong

Go deeper

Agent skill

CLI

TypeScript SDK

REST API

​Prerequisites

​Routes to try next

​If something goes wrong

​Go deeper

Agent skill

CLI

TypeScript SDK

REST API

Prerequisites

Routes to try next

If something goes wrong

Go deeper