Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.circuit.org/llms.txt

Use this file to discover all available pages before exploring further.

​
CLI Issues

circuit: command not found The CLI is not installed globally. Install with: 
bun install -g @circuitorg/agent-cli
circuit dev run --hosted 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 dev run --hosted
In non-interactive environments, pass --wallet / -w with the hosted wallet address or name shown in the app. circuit dev 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 }));
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.

​
Swap 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 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 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 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:
    print(response.data.tx_hash)

​
General Tips

  • Test locally first with circuit dev 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