REST API

The REST API is the lowest-level way to integrate Geodesics. It is the same wire the CLI and the TypeScript SDK are built on; reach for it when you are building your own client in another language, or you want full control over retries, batching, and signing. Every endpoint is specified in the interactive API Reference. This walkthrough swaps 10 USDC on Base → USDC on Arbitrum from an EVM agent wallet. The wallet needs no ETH on either chain; gas comes out of the input USDC.

You need an API key, sent as the x-api-key header, and a one-time wallet delegation on the origin chain. See Authentication and Gasless delegation.

1. Quote

Price the swap. Amounts are in the token’s smallest unit: USDC has 6 decimals, so 10 USDC = 10000000.

curl -X POST https://api.geodesics.ai/swap/quote \
  -H "x-api-key: $GEODESICS_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "originChain": 8453,
    "destinationChain": 42161,
    "inputToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "outputToken": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    "amount": "10000000",
    "walletAddress": "0xYourAgentWallet"
  }'

{
  "geoQuoteToken": "…",
  "origin": "evm",
  "output": "9.87",
  "feeBps": 12.5,
  "inputUsd": "10.00",
  "outputUsd": "9.87",
  "priceImpactBps": -130,
  "expiresAt": "2026-07-13T12:00:30.000Z"
}

The geoQuoteToken carries the quote to the build call; echo it back verbatim. It expires 30 seconds after issue; if it lapses, just re-quote. When the origin wallet holds enough $GEO, the response also carries a feeDiscount object with the earned tier, the discountPercent, and the undiscounted baseFeeBps. The feeBps value already reflects the discounted fee. When the venue can price both sides in USD, the quote carries indicative inputUsd and outputUsd values and priceImpactBps: the all-in value change between them in basis points, signed the way swap UIs display impact (negative = the output is worth less; includes price impact, network costs, and the fee, i.e. what executing this quote actually gives up). Slippage protects execution against the quote; priceImpactBps tells you when the quote itself is expensive, before anything is signed. Past the server’s threshold the response also carries a warnings entry with code HIGH_PRICE_IMPACT. Warnings are always non-fatal: the swap can proceed regardless, so gate on them client-side where your integration decides.

2. Build

Turn the quote into the exact 32-byte hash your agent signs:

curl -X POST https://api.geodesics.ai/swap/build-geo-op \
  -H "x-api-key: $GEODESICS_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "geoQuoteToken": "…" }'

{
  "geoOpHash": "0x…",
  "geoOpToken": "…"
}

If the wallet isn’t delegated yet, this returns 409 NEEDS_DELEGATION, a one-time setup per chain. A wallet signing with its own key onboards itself by attaching a one-time authorization to this very call; see First swap from a new wallet below and Gasless delegation.

3. Sign and submit

Sign geoOpHash with the agent wallet using an EIP-191 personal_sign over the raw 32 bytes; the server assembles and submits the final operation. Post the signature:

import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY);
const signature = await account.signMessage({ message: { raw: geoOpHash } });

const submitResponse = await fetch("https://api.geodesics.ai/swap/submit", {
  method: "POST",
  headers: { "x-api-key": process.env.GEODESICS_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({
    geoOpToken,
    signature,
  }),
});
const { swapId, status } = await submitResponse.json();

Submit is idempotent per quote: retrying the same submit request returns the existing swap instead of double-spending.

4. Poll status

curl https://api.geodesics.ai/swap/status/$SWAP_ID \
  -H "x-api-key: $GEODESICS_API_KEY"

{
  "swapId": "…",
  "status": "settled",
  "originTxHash": "0x…",
  "deliveryTxHash": "0x…"
}

The endpoint long-polls server-side for up to ~15 seconds per request, until the swap is terminal: settled, failed, or refunded. Loop until you get one of those; see Swap lifecycle.

First swap from a new wallet

A wallet signing with its own key needs no separate activation step: its first swap from a chain carries a one-time EIP-7702 authorization, and the swap that carries it onboards the wallet, gasless. The loop grows one read and one extra signature: First, read the wallet’s delegation state. When the wallet is not yet delegated, the response carries the two fields to sign over:

curl https://api.geodesics.ai/swap/delegation/8453/0xYourAgentWallet \
  -H "x-api-key: $GEODESICS_API_KEY"

{
  "chainId": 8453,
  "walletAddress": "0xYourAgentWallet",
  "delegated": false,
  "originReady": false,
  "delegationTarget": "0x…",
  "accountNonce": 0
}

Sign an authorization over exactly those fields with the wallet key, and pass it on the build call:

import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY);
const signed = await account.signAuthorization({
  contractAddress: delegationTarget,
  chainId: 8453,
  nonce: accountNonce,
});

const buildResponse = await fetch("https://api.geodesics.ai/swap/build-geo-op", {
  method: "POST",
  headers: { "x-api-key": process.env.GEODESICS_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({
    geoQuoteToken,
    authorization: {
      chainId: 8453,
      address: delegationTarget,
      nonce: accountNonce,
      yParity: signed.yParity === 1 ? 1 : 0,
      r: signed.r,
      s: signed.s,
    },
  }),
});

Sign and submit exactly as in steps 3 and 4; the swap that settles also activates the wallet, and every later swap on that chain skips straight through with no authorization. Two errors are specific to this branch:

409 INVALID_AUTHORIZATION: the authorization went stale because the account’s nonce moved between signing and execution. Re-read the delegation state, sign a fresh authorization at the new nonce, and rebuild; nothing was executed.
422 UNSUPPORTED_DELEGATION: the wallet is already delegated to another provider on this chain. Geodesics never replaces an existing delegation; this is permanent for that wallet on that chain, so use a different wallet there.

Solana origin?

Same loop, different build/submit pair: POST /swap/build-solana-tx returns a base64 unsigned transaction; your agent signs it and posts it to POST /swap/submit-solana. Details in Solana swaps.

Rather not run this loop yourself?

Agent skill & CLI

The whole loop as one command, with automatic activation and onboarding.

TypeScript SDK

The same wire as a typed library: swap() runs quote to settlement in one call.

Get Started

Integrations

Concepts

Guides

1. Quote

2. Build

3. Sign and submit

4. Poll status

First swap from a new wallet

Solana origin?

Rather not run this loop yourself?

Agent skill & CLI

TypeScript SDK

​1. Quote

​2. Build

​3. Sign and submit

​4. Poll status

​First swap from a new wallet

​Solana origin?

​Rather not run this loop yourself?

Agent skill & CLI

TypeScript SDK

1. Quote

2. Build

3. Sign and submit

4. Poll status

First swap from a new wallet

Solana origin?

Rather not run this loop yourself?