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:
--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:
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)
"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:
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 runbefore uploading - Use
debug: true/debug=Truefor 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.jsonto avoid breaking changes on deploy - Keep the schedule trigger’s
everyreasonable - too frequent runs may hit rate limits on external APIs