Skip to main content

​
CLI Issues

circuit: command not found The CLI is not installed globally. Install with: 
bun install -g @circuitorg/agent-cli
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: 
circuit run --hosted engine
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: 
const result = await agent.swap.quote({...});
if (result.success && result.data) {
  // Safe to use result.data
} else {
  await agent.log(result.error || "Request failed", { error: true });
}
Memory values are not persisting Memory values must be strings. If you’re storing numbers or objects, serialize them first: 
// Wrong
await agent.memory.set("count", 5);

// Correct
await agent.memory.set("count", "5");
await agent.memory.set("config", JSON.stringify({ threshold: 0.05 }));
Holdings don’t update after a transaction agent.portfolio is a snapshot taken at the start of execution and does not refresh mid-cycle. Track the changes you make in Memory if you need updated state within the same run.

​
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 "BTC/USDC" for perps — that format is for spot only. Unknown spot pair error Spot coins must include the quote: "BTC/USDC", "ETH/USDC". Do NOT use just "BTC" for spot. Rate limiting Hyperliquid rate-limits aggressively. Avoid calling balances() or positions() in loops. Call them once at the start of your run function and reuse the results. stop or take_profit order fails Stop and take-profit orders require a triggerPrice parameter. This is separate from the price parameter (which acts as a slippage limit).

​
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: 
import requests

def check_order_book_liquidity(token_id: str, side: str, min_usd: float) -> bool:
    response = requests.get(
        "https://clob.polymarket.com/book",
        params={"token_id": token_id},
        timeout=10,
    )
    if not response.ok:
        return False
    book = response.json()
    orders = book.get("asks" if side == "BUY" else "bids", [])
    total_usd = sum(float(o["price"]) * float(o["size"]) for o in orders)
    return total_usd >= min_usd
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: 
response = agent.sign_and_send({
    "network": "ethereum:1",
    "request": {
        "to_address": "0x...",
        "data": "0x",
        "value": "100000000000000",
    }
})
if response.success and response.data:
    agent.log(f"Sent: {response.data.tx_hash}")

​
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 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 runtimeIntervalMinutes reasonable — too frequent runs may hit rate limits on external APIs