> ## 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.

# Build contract

# Circuit agent build contract

Circuit agents are TypeScript programs that run financial strategies against self-custodial
wallets. Export `run(agent)` for recurring work and `unwind(agent)` to close positions. The runtime
provides `circuit:sdk`; never install a separate SDK package.

[SDK](https://docs.circuit.org/agent-developers/sdk-reference/sdk-quick-reference),
[CLI](https://docs.circuit.org/agent-developers/cli-references/cli-quick-reference),
[configuration](https://docs.circuit.org/agent-developers/getting-started/circuit-toml-reference), and
[examples](https://docs.circuit.org/agent-developers/examples/basic-agent).

## Non-negotiable money rules

1. Verify identifiers against an authoritative live source; plausible values can lose funds.
2. Read a live venue mid or executable quote immediately before every price decision.
3. Size from exact `agent.allocation` amounts or a live quote. Unknown data fails the decision;
   never substitute `0`, `[]`, memory, or a guess. Whole-wallet reads are not the session budget.
4. Preserve smallest-unit quantities as `bigint` or decimal strings. Never use floats.
5. SDK failures throw `ApiError`; stop on ambiguity and surface every non-secret detail.
6. `unwind()` closes only the session-attributed positions the strategy can open.
7. Use `agent.log()` for user-facing decisions and outcomes.

## Agent shape

```typescript theme={null}
import type { AgentContext } from "circuit:sdk";

export async function run(agent: AgentContext): Promise<void> {
  await agent.log(`Reviewing ${agent.allocation.balances.length} balances`);
}

export async function unwind(agent: AgentContext): Promise<void> {
  await agent.log(`Reviewing ${agent.allocation.positions.length} positions to unwind`);
}
```

`allocation.balances` is fungible inventory; `allocation.positions` is open exposure. This snapshot
is the autonomous budget; SDK methods do not enforce it. `agent.wallet` and Terminal may affect the
full wallet; Terminal overrides allocation. Track effects locally and re-observe next run.

## Response and execution contract

SDK calls return resources directly and throw `ApiError`. The SDK assigns every money write a
run-scoped idempotency identity and submits it once. Never retry an ambiguous write.

## Venue rules

* Swaps use `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` on EVM and
  `11111111111111111111111111111111` on Solana for native assets and re-quote at execution. Never
  widen slippage to force a route. Prefer typed resources for exact accounting; arbitrary
  transactions and signatures carry no additional constraint.
* Hyperliquid orders need at least 10 USDC at `size × price`, except `reduceOnly` for the wallet's
  exact whole position. Derive the bounded price from a live midpoint; size spot from allocated USDC
  or the spot asset; copy position size strings when reducing. Pass catalog `asset` unchanged to
  midpoint reads and orders, including `xyz:` builder-DEX prefixes; a spot market is its readable pair
  from `spotMarkets.list()` (`HYPE/USDC`), never the venue's `@<index>`.
* Polymarket trading requires a grandfathered wallet. Resolve exact tokens through events; BUY uses
  `spendPusd` and SELL uses `shares`; account-wide redemption is not an AgentContext method.
* Kraken credentials are implicit. Size from allocation and discover exact pairs and limits.
  Order listing, retrieval, and cancellation are restricted to the current session's order ids.

## Configuration

Every project has `circuit.toml` and `DESCRIPTION.md` sections `Summary`, `What it is`, `How it
works`, `Strategy`, and `Risks`. Copy configuration forms from the reference. A Hyperliquid agent's
`[startingAsset]` is Core USDC: `network = "hypercore"`, `asset = "0"`, and `minimumAmountRaw` in
eight decimals (`"1000000000"` is 10 USDC).

## Development workflow

Run `circuit check`, then test `run` and `unwind` with real allocation before `circuit upload`.
`circuit check` validates and bundles without executing agent code. Before upload, verify live
identifiers and prices, allocation sizing, loud failures, venue limits, exit liquidity, unwind
paths, and agreement between strategy, config, description, and logs.