Skip to main content

CLI Issues

circuit: command not found The CLI is not installed globally. Install with:
circuit run --hosted engine fails with “No wallet found” Hosted runs select wallets from your Circuit account, not from the local keystore. Create or import a wallet in the Circuit app first, then rerun:
In non-interactive environments, pass --wallet with the hosted wallet address or name shown in the app. circuit run fails immediately Ensure dependencies are installed before running:
  • TypeScript: bun install
  • Python: uv sync

SDK Issues

result.data is undefined Always check success before accessing data:
Memory values are not persisting Memory values must be strings. If you’re storing numbers or objects, serialize them first:
Holdings don’t update after a transaction agent.allocation is intentionally fixed for the invocation. Track changes made by dependent steps in local variables; the next trigger receives a fresh context from committed allocation state. Do not cache balances in memory across invocations. Engine call fails with an EDGE_502 / EDGE_504 code The request died at the network edge before reaching Circuit’s engine (a gateway interstitial page, e.g. a Cloudflare 502/504). The SDK raises an ApiError whose wireCode is EDGE_<status> and whose message is a single sentence; the interstitial’s HTML is never surfaced. These are transient infrastructure failures — retry the call. Non-HTML error bodies pass through verbatim, and real engine error envelopes are unaffected.

Swap Issues

Quote fails with “no routes found” The token pair or route is not supported by any routing engine. Verify:
  • Token addresses are correct for the specified network
  • Network identifiers are valid (e.g., "ethereum:137" not "polygon")
  • The route exists (some token pairs have no liquidity)
Quote fails with “Price impact is too high” The swap amount is too large relative to available liquidity. Reduce the amount or increase slippage tolerance. Circuit automatically filters quotes with >100% price impact. Swap amounts seem wrong Amounts are in smallest units (wei, lamports, etc.), not formatted values. For example, 1 USDC on typical EVM token contracts (6 decimals) = "1000000", not "1". For Hyperliquid hypercore:perp starting-asset USDC, Circuit uses 8 decimal places (e.g. 1 USDC = "100000000"); see Hyperliquid. Omit fromToken/toToken for native tokens - don’t pass the zero address.

Hyperliquid Issues

Unknown perp asset error Perp coins are just the base asset: "BTC", "ETH". Do NOT use a pair like "UBTC/USDC" for perps - that format is for spot only. Unknown spot pair error Spot coins are the full live listing pair name, and bridged majors are Unit assets with a U prefix: "UBTC/USDC", "UETH/USDC", "USOL/USDC" (Hyperliquid-native tokens use their plain ticker: "HYPE/USDC", "PURR/USDC"). "BTC/USDC" and bare "BTC" are both rejected - the error message lists every valid pair; copy the exact name from it. Rate limiting Hyperliquid rate-limits aggressively. Avoid calling midpointPrice in tight loops - fetch a coin’s mid once per decision and reuse it. Invocation-start collateral and open positions are in agent.allocation. Limit, post-only, stop, or take_profit order fails Circuit supports immediate non-post-only Hyperliquid market orders only. Set type: "market" and omit postOnly or set it to false; omitted, resting, and triggered order types are rejected on every Circuit surface, including manual-mode approvals and direct wallet-owner operations.

Polymarket Issues

market_order returns “Something went wrong” This usually means the order book has insufficient liquidity for your order size. The CLOB’s calculateBuyMarketPrice throws a generic error when there aren’t enough asks (for buys) or bids (for sells), which surfaces as a 500 error. Fix: Always check order book liquidity before placing orders:
Also filter out markets with extreme prices (below 0.10 or above 0.90) - these typically have thin liquidity. No orderbook exists for the requested token id The tokenId is invalid or the market doesn’t exist. Verify the token ID from Polymarket’s API. Dust positions after selling Polymarket has different decimal precision for buys and sells, which can leave small residual positions. Clean these up with redeemPositions({ tokenIds }) after market expiry.

Python-Specific Issues

from keyword conflict in swap.quote() See Swap: Python from Parameter for the full workaround. Python SDK uses snake_case Use snake_case keys when passing dicts to SDK methods. The SDK converts to camelCase internally when calling the API:

General Tips

  • Test locally first with circuit run before uploading
  • Use debug: true / debug=True for verbose logging that won’t appear in the user-facing UI
  • Check executionMode (TypeScript) / execution_mode (Python) if your agent behaves differently in auto vs manual mode
  • Pin dependency versions in pyproject.toml / package.json to avoid breaking changes on deploy
  • Keep the schedule trigger’s every reasonable - too frequent runs may hit rate limits on external APIs