TypeScript SDK

• Any wallet works: a raw key from any stack, an embedded wallet, or a Virtuals ACP agent wallet. The signer is just callbacks; nothing about your wallet setup is assumed.
• The agent holds only the token it wants to swap. Gas and fees come out of the input, so the agent never needs ETH or any gas token.
• Self-custodial: the server builds every operation, your agent signs one hash with the signer it already has, and funds never leave the agent’s own wallet.
• Chain onboarding is automatic: a signer with signAuthorization onboards the wallet inside its first swap from each chain, gasless; a Virtuals-style signer with sendTransaction runs the one-time activation instead, same as the CLI.
• Zero runtime dependencies, ESM, fully typed and runtime-validated responses.

​

Install

npm i @geodesics-protocol/sdk

​

One call

import { createGeodesicsClient } from "@geodesics-protocol/sdk";

const geodesics = createGeodesicsClient({
  baseUrl: "https://api.geodesics.ai",
  apiKey: process.env.GEODESICS_API_KEY ?? "",
});

const result = await geodesics.swap(
  {
    originChain: 8453, // Base
    destinationChain: 42161, // Arbitrum
    inputToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
    outputToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", // USDC on Arbitrum
    amount: "5000000", // 5 USDC, in base units (6 dp)
    walletAddress: agentWalletAddress,
    slippageBps: 300, // optional; defaults per route (tight for stables, wider for volatile)
  },
  // One EIP-191 signature over the raw 32-byte hash per swap. The other callbacks are
  // optional capabilities: signAuthorization (own wallet, gasless first-swap onboarding),
  // sendTransaction (Virtuals-style activation), signSolanaTransaction (Solana origin).
  // Runnable versions of both wallet kinds are below.
  {
    signMessage: (geoOpHash) => agentSigner.signMessage(geoOpHash),
  },
);
// result: { swapId, status: 'settled', originTxHash, deliveryTxHash, output, feeBps }

​

Any wallet: bring a raw key

import { createGeodesicsClient } from "@geodesics-protocol/sdk";
import { privateKeyToAccount } from "viem/accounts";

const geodesics = createGeodesicsClient({
  baseUrl: "https://api.geodesics.ai",
  apiKey: process.env.GEODESICS_API_KEY ?? "",
});
const account = privateKeyToAccount(process.env.AGENT_SIGNER_PRIVATE_KEY);

const result = await geodesics.swap(
  {
    originChain: 8453,
    destinationChain: 8453,
    inputToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
    outputToken: "0x0b3e328455c4059EEb9e3f84b5543F74E24e7E1b", // VIRTUAL on Base
    amount: "3000000", // 3 USDC
    walletAddress: account.address,
  },
  {
    signMessage: (geoOpHash) => account.signMessage({ message: { raw: geoOpHash } }),
    // The wallet's first swap from a chain carries this one-time EIP-7702 authorization and
    // onboards the wallet inside the same swap, gasless. Every later swap skips it.
    signAuthorization: async ({ chainId, address, nonce }) => {
      const signed = await account.signAuthorization({ contractAddress: address, chainId, nonce });
      return { chainId, address, nonce, yParity: signed.yParity === 1 ? 1 : 0, r: signed.r, s: signed.s };
    },
  },
);

​

Withdraw

const result = await geodesics.withdraw(
  {
    chain: 8453, // Base
    amount: "5000000", // 5 USDC, in base units
    walletAddress: agentWalletAddress,
    to: recipientWalletAddress,
  },
  { signMessage: (geoOpHash) => agentSigner.signMessage(geoOpHash) },
);
// result: { swapId, status: 'settled', originTxHash, deliveryTxHash, output, feeBps }

​

Step-by-step methods

​

Virtuals ACP agents: plug in the signer you already have

npm i @geodesics-protocol/sdk @virtuals-protocol/acp-node-v2 @account-kit/infra

import { base } from "@account-kit/infra";
import { createGeodesicsClient } from "@geodesics-protocol/sdk";
import { PrivyAlchemyEvmProviderAdapter } from "@virtuals-protocol/acp-node-v2";

const geodesics = createGeodesicsClient({
  baseUrl: "https://api.geodesics.ai",
  apiKey: process.env.GEODESICS_API_KEY ?? "",
});

// The agent's ACP wallet + swapping signer key (the base64 value starting "MIG" shown once at
// signer creation). The signer service signs remotely; no key material lives in your process.
const walletAddress = process.env.AGENT_WALLET_ADDRESS ?? "";
const agent = await PrivyAlchemyEvmProviderAdapter.create({
  walletAddress,
  walletId: process.env.AGENT_WALLET_ID ?? "",
  signerPrivateKey: (process.env.AGENT_SIGNER_PRIVATE_KEY ?? "").replace(/^0x/, ""),
  chains: [base],
});

const result = await geodesics.swap(
  {
    originChain: 8453,
    destinationChain: 8453,
    inputToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
    outputToken: "0x0b3e328455c4059EEb9e3f84b5543F74E24e7E1b", // VIRTUAL on Base
    amount: "3000000", // 3 USDC
    walletAddress,
  },
  {
    // sign on the origin chain id (8453 here); the hash is the same EIP-191 flow ACP trades use
    signMessage: (geoOpHash) => agent.signMessage(8453, { raw: geoOpHash }),
    sendTransaction: (chainId, call) => agent.sendTransaction(chainId, call),
  },
);

​

Chain onboarding: first swap from or into a new chain

• First swap FROM a chain: the SDK fetches the signing fields from the API, collects the wallet’s one-time authorization, and the swap that carries it onboards the wallet, gasless, in the same settlement. Progress reports { stage: 'authorizing' }. If the authorization goes stale between signing and execution because the account’s nonce moved, the server rejects it with INVALID_AUTHORIZATION and the SDK automatically refreshes the state, re-collects one signature, and retries once.
• Delivery INTO any chain needs no preparation. Whatever lands there can always swap back out, because the wallet onboards itself whenever it first swaps out of that chain.
• A wallet that is already delegated to another provider on a chain cannot be onboarded there: Geodesics never replaces an existing delegation, and the API refuses with UNSUPPORTED_DELEGATION. Use a different wallet on that chain.

• First swap FROM a chain: swap() fetches the prepared activation call from the API, sends it, waits for the delegation to land, and continues with a fresh quote. The call is a tiny self-transfer of the chain’s stable, paid from that balance. Progress reports { stage: 'activating' }.
• First swap INTO a chain: the destination is onboarded before the main swap so the delivered assets can always swap back out. If the swap itself delivers the chain’s stable, activation simply runs after settlement. If the wallet already holds the stable there, it activates up front. Otherwise swap() pipes ~1 unit of the origin chain’s stable over, activates, and returns the remainder; keep ~1 unit spare on the origin for this. It adds about a minute, once per chain. Progress reports { stage: 'onboarding' }; anything non-fatal that could not run lands in result.warnings. Opt out with swap(request, signer, { onboardDestination: false }).

​

Slippage

​

Errors

• GeodesicsApiError with status, code, and a plain-language message. Notable codes: NEEDS_DELEGATION and INVALID_AUTHORIZATION, covered under Chain onboarding above (the latter is retried once automatically); UNSUPPORTED_DELEGATION, when the wallet is already delegated to another provider on that chain, which Geodesics never replaces; NEEDS_SOL_TOPUP, when a same-chain Solana swap needs ~0.005 SOL for network fees; and NEEDS_LARGER_SIZE, when the amount is too small for that route.
• GeodesicsTimeoutError with swapId and lastStatus when polling hits its deadline; the swap usually still settles, so check status(swapId).

​

Apps with end-user wallets

• Your backend holds the API key and makes every Geodesics call: quote, build, submit, status. The key never ships to a browser or app client.
• The user’s wallet contributes only signatures. Your backend hands the geoOpHash to the client; the user’s wallet signs it (EIP-191 over the raw 32 bytes) and, once per chain, the one-time onboarding authorization; the backend passes both back through swap()’s signer callbacks or the step-by-step methods. The sealed geoQuoteToken / geoOpToken are opaque and safe to hold server-side; nothing in them needs the client.
• Onboard at signup if you prefer: call onboard() per user when they join, so the first swap is indistinguishable from every later one. With signature-only wallets it reports onboarding: 'first-swap' and the first swap handles it, gasless, automatically.
• Nothing assumes one wallet per API key: any number of users’ wallets can swap behind one key, and the wallet that spends is always the one whose key signed.

​

Supported chains

​

Prefer a ready-made agent skill?