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 fails with “No wallet found” Import a wallet first: 
circuit wallet import
Then run with --wallet / -w specifying the wallet address. circuit run fails immediately Ensure dependencies are installed before running:
  • TypeScript: bun install
  • Python: uv sync or pip install -e .
circuit publish --dry-run succeeds but circuit publish fails Check that you are signed in (circuit whoami) and that your circuit.toml has all required fields (name, tagline, walletType, allowedExecutionModes, runtimeIntervalMinutes, version, startingAsset).

​
SDK Issues

result.data is undefined Always check success before accessing data: 
const result = await agent.swidge.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 }));
Positions don’t update after a transaction agent.currentPositions is a snapshot taken at the start of execution. After transactions, call getCurrentPositions() for updated balances. Note that indexing may lag by chain — use hasPendingTxs to detect this. errorMessage / error_message is undefined These fields are deprecated. Use the error field instead: 
// Old (deprecated)
await agent.log(result.errorMessage);

// New
await agent.log(result.error);

​
Swap and Bridge Issues

Quote returns NO_COMPATIBLE_ENGINES 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 returns PRICE_IMPACT_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 (6 decimals) = "1000000", not "1". Omit fromToken/toToken for native tokens — don’t pass the zero address.

​
Hyperliquid Issues

Unknown perp asset error Perp symbols 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 symbols 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() after market expiry.

​
Python-Specific Issues

from keyword conflict in swidge.quote() Python’s from is a reserved keyword. When passing a dict, use the string key "from" — it works because dict keys are strings. When using Pydantic models directly, use from_ (with underscore): 
# Dict approach (recommended)
quote = agent.swidge.quote({
    "from": {"network": "ethereum:137", "address": addr},
    ...
})

# Pydantic model approach
from agent_sdk.types.swidge import SwidgeQuoteRequest, SwidgeWallet
quote = agent.swidge.quote(SwidgeQuoteRequest(
    from_=SwidgeWallet(network="ethereum:137", address=addr),
    ...
))
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:
    print(response.data.tx_hash)

​
General Tips

  • Test locally first with circuit run before publishing
  • 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