circuit.toml, DESCRIPTION.md, AGENTS.md, index.ts, package.json, and the generated circuit-sdk.d.ts and circuit-settings.d.ts.
Agents export run(agent) for triggers and optional unwind(agent) for requested exits. Both receive AgentContext and return no value.
DESCRIPTION.md
Users review this description before Start. Required sections are## Summary, ## What it is, ## How it works, ## Strategy, and ## Risks. Name assets, protocols, sizing, exits and material risks concretely. What it is uses these labels:
circuit.toml
Runcircuit new to generate the complete project and its required identity fields. Configure its schedule, starting asset and optional settings using the contracts below.
agentId owns permanent identity; uploads replace its runnable content. circuit check rejects duplicate IDs across a workspace.
Account readiness
Circuit infers startup account requirements fromstartingAsset: HyperCore assets require an existing Hyperliquid account in unified mode; Polymarket assets require a usable selected account. Controlled Deposit Wallets require deployment regardless of starting asset. Owners complete missing setup through reviewed operations. No additional configuration declaration is needed.
Starts, resumes and hosted execution admission check readiness. The heuristic does not predict a different venue chosen later by the strategy; transaction preparation checks the actual action and returns ACCOUNT_SETUP_REQUIRED before submission when necessary. Failed reads block execution, and setup never grants signing authority.
[[triggers]] Section
Each schedule has type = "schedule", an everyMs duration in integer milliseconds divisible by 60000 (one minute), and align = "rolling" or "fixed". rolling starts after the last run; fixed aligns to clock
boundaries and must divide one hour. A price trigger uses venue hyperliquid, an exact canonical perp
asset, and condition cross, abs_move, or pct_move. Position triggers name their asset (a
Hyperliquid perp or a Polymarket outcome token id); fill triggers may omit it to match any fill. A
resolution trigger with venue polymarket fires on outcome resolution and names no asset.
The cross and abs_move conditions require a positive decimal thresholdUsd (USD mark price or USD price movement). pct_move requires positive decimal thresholdPercent: "0.5" means 0.5%, with no % or bps suffix. cooldownMs is the minimum interval between reactive firings, default zero, at most 2147483647 milliseconds (the stored integer range).
[backtest] Section
Backtestable agents declare every data and execution dependency in requirements. "hyperliquid.perp" replays stored Hyperliquid markets and perpetual orders from simulated HyperCore USDC; "onchain.swap", "x.posts" and "external.http" are explicit live-only dependencies and make historical replay unavailable. [[backtest.markets]] declares each market with venue = "hyperliquid" and either a literal symbol or a string-valued setting key. Market-scoped Hyperliquid triggers also contribute their asset. Circuit derives the replay universe from these declarations and rejects missing, mismatched or unsupported dependencies instead of guessing a market.
[startingAsset] Section
network is solana, ethereum:<chainId>, or hypercore. asset identifies the contract or native token: EVM 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee, Solana 11111111111111111111111111111111, or HyperCore index 0 for Core USDC.
minimumAmountRaw is an integer string in the asset’s smallest unit; Core USDC uses eight decimals. Arc (ethereum:5042) starting USDC uses the native EVM sentinel and 18 decimals; the 6-decimal ERC-20 interface is the same balance and is rejected as starting inventory.
For an existing HyperCore perpetual, set asset to its exact coin (for example "BTC" or "xyz:GOLD") and expectedSide to "long" or "short"; quantities use eight decimals. For an existing Polymarket outcome, use network = "ethereum:137", asset = "0x4d97dcd97ec945f40cf65f87097ace5ea0476045", and the decimal outcome tokenId; quantities use six decimals. Start assigns only the selected unallocated quantity. Kraken trade agents use "0" because their capital is the venue allocation.
[settings] Section
Each key defines one setting (maximum 20). Types are text, boolean, single_select, integer,
number, percentage, and address. Every setting carries a same-type default; users override
it when they start a session. single_select alone requires up to 20 unique options, including
its default. Percentages range from 0 through 100. integer, number and percentage alone may
declare an inclusive min, max, or both, where min must not exceed max; the default and every
session override must satisfy them. Addresses must match walletVmFamily. Resolved
defaults and session overrides are available through settings.
[exchangeCredentials] Section
One venue may be declared. read defaults true; trade defaults false and requires reads.
Trading requires a positive minimumAllocation, for example { asset = "USD", amount = "25" }. Supported assets are USD and USDC. Circuit asks the user to pick
the credential and allocation, scopes the runtime permit to them, and never exposes the secret or
credential id to agent code. Private Kraken methods use the attachment automatically.
circuit.toml has no version field, and Circuit rejects unknown fields. Upload content is hashed
and versioned by Circuit. Keep runtime assets inside the agent directory; share code through a
multi-agent workspace. The CLI applies one
fixed source exclusion policy to checks,
local runs, and uploads. .circuit is reserved for CLI state.