# Authentication
Source: https://docs.circuit.org/agent-developers/cli-references/authentication

CLI commands for authenticating with Circuit.

### Sign In

Authenticate with Circuit.

```bash theme={null}
circuit signin
```

Opens a browser to authenticate. If you don't have an account, one will be created.

**How it works:**

1. The CLI generates a unique auth ID via the Circuit API
2. Opens your browser to the Circuit login page with the auth ID
3. The CLI polls the API for the session token while you authenticate
4. Once authenticated, the token is stored in `~/.config/circuit/auth-<environment>.json` (e.g. `auth-staging.json`)

The login flow has a 300-second timeout. If authentication is not completed in time, the CLI exits.

**Stored credentials:**

```json theme={null}
{
  "sessionToken": "...",
  "refreshToken": "...",
  "timestamp": "2025-01-01T00:00:00.000Z",
  "user": {
    "name": "...",
    "email": "..."
  }
}
```

### Sign Out

Sign out from Circuit.

```bash theme={null}
circuit signout
```

**Behavior:**

* Clears the stored session token from `~/.config/circuit/auth-<environment>.json` for the current environment
* No parameters required

### Logged In User Info

Show current authenticated user.

```bash theme={null}
circuit whoami
```

**Flags:**

* `--show-auth` / `-a`: Display a base64-encoded auth token for CI/CD use.

**Output:**

* Displays your Circuit username
* Shows authentication status
* With `--show-auth`: prints an auth token for non-interactive environments


# Development
Source: https://docs.circuit.org/agent-developers/cli-references/development

CLI commands for developing and testing agents locally.

### Create New Agent

Create a new agent project from a template.

```bash theme={null}
circuit new
```

**Flags:**

* `--language <lang>` / `-l <lang>`: Project language (`typescript` or `python`). Skips the language prompt.
* `--name <name>` / `-n <name>`: Agent name. Skips the name prompt.
* `--template <template>` / `-t <template>`: Template to use (`basic`, `yield`, `polymarket`, `hyperliquid`). Skips the template prompt.

**Prompts (interactive mode):**

1. Template selection (basic, yield, polymarket, hyperliquid)
2. Language selection (TypeScript or Python)
3. Agent name (used to generate the directory name)

**Creates:**

* A new directory named after the agent name
* Agent code template (`index.ts` or `main.py`)
* Configuration file (`circuit.toml`)
* Description file (`DESCRIPTION.md`)
* Dependency file (`package.json` or `pyproject.toml`)
* AI coding assistant context (`AGENTS.md` and `CLAUDE.md`)

**Output:**

* Prints project directory path and next steps

***

### Run Agent Locally

Test your agent locally by executing the `run` function.

<Warning>Make sure all required packages are installed via `uv sync` (Python) or `bun install` (TypeScript) before running.</Warning>

```bash theme={null}
circuit run
```

**Flags:**

* `--path <path>` / `-p <path>`: Run from a specific agent directory instead of the current directory.
* `--wallet <address>` / `-w <address>`: Specify the wallet address to use instead of being prompted.
* `--mode <mode>` / `-m <mode>`: Set the execution mode (`auto` or `manual`). Defaults to the first entry in `allowedExecutionModes`.
* `--amount <amount>` / `-a <amount>`: Token amount to allocate in smallest unit (should be greater than `minimumAmount`).
* `--env KEY=VALUE` / `-e KEY=VALUE`: Override/add env vars for this run (repeatable). Merged with `.env` file; CLI flags take precedence.
* `--local-sdk-dependencies` / `-l`: Skip automatic dependency installation before running.

**How it works:**

1. Loads environment variables from `.env` and `--env` overrides
2. Prompts you to select a wallet from your imported wallets (or uses `--wallet` flag)
3. Uploads your latest agent code (soft publish)
4. Checks for an existing session or creates a new one
5. Validates starting asset balance
6. Starts the agent server locally with env vars injected
7. Sends an execute request with session data
8. Streams logs to your terminal
9. Stops the server process after execution completes

**Soft publish:** Step 2 uploads your code to Circuit for the dev session only. Unlike `circuit publish`, a soft publish does not create a new versioned release — it temporarily makes your latest code available for the local execution.

For details on how `run` and `unwind` functions are called, see [Execution Model](../concepts/execution-model).

***

### Unwind Agent

Execute your agent's `unwind` function on a running session, then end the session.

```bash theme={null}
circuit unwind
```

**Flags:**

* `--path <path>` / `-p <path>`: Run from a specific agent directory instead of the current directory.
* `--wallet <address>` / `-w <address>`: Specify the wallet address to unwind instead of being prompted.
* `--env KEY=VALUE` / `-e KEY=VALUE`: Override/add env vars for this unwind (repeatable). Merged with `.env` file; CLI flags take precedence.
* `--local-sdk-dependencies` / `-l`: Skip automatic dependency installation before running.

**How it works:**

1. Loads environment variables from `.env` and `--env` overrides
2. Fetches your imported wallets that have active sessions for this agent
3. Prompts you to select a wallet (or uses `--wallet` flag)
4. If multiple sessions exist for the wallet, prompts you to select one
5. Fetches current positions for the session
6. Starts the agent server locally with env vars injected
7. Sends an unwind request with session data and positions
8. Streams logs to your terminal
9. Ends the session after unwind completes

***

### Check Agent Project

Validate your agent project configuration and files offline — no authentication required.

```bash theme={null}
circuit check
```

**Flags:**

* `--json` / `-j`: Output results as JSON.
* `--path <path>` / `-p <path>`: Path to agent project directory (defaults to current directory).
* `--env KEY=VALUE` / `-e KEY=VALUE`: Override/add env vars for validation (repeatable). Merged with `.env` file; CLI flags take precedence.

**Checks performed:**

* Config structure (valid `circuit.toml`)
* Entry point exists (`index.ts` or `main.py`)
* Handler export (`agent.getExport()` or `agent.get_handler()`)
* SDK version pinning
* Environment variable cross-referencing
* Files to upload listing

***

### Global Flags

The CLI parser supports these global flags:

* `--path <path>` / `-p <path>`: Path to agent project directory (defaults to current directory).
* `--json` / `-j`: Output results as JSON (most useful on `check`, `publish`, and `whoami`).
* `--help` / `-h`: Show help for the command.


# Publishing
Source: https://docs.circuit.org/agent-developers/cli-references/publishing

CLI commands for publishing agents to Circuit.

### Publish Agent

Publish your agent to Circuit infrastructure.

```bash theme={null}
circuit publish
```

**Flags:**

* `--path <path>` / `-p <path>`: Publish from a specific agent directory instead of the current directory.
* `--env KEY=VALUE` / `-e KEY=VALUE`: Override/add env vars for this publish (repeatable).

**What happens:**

1. Validates your project and `circuit.toml` against the selected stage (including `startingAsset` and deployment-region rules)
2. Collects project files based on exclusion patterns
3. Reads environment variables from `.env` in the agent root (if present)
4. Applies `--env KEY=VALUE` overrides (CLI flags take precedence)
5. Generates a content hash (SHA-256) of your project files and env vars
6. Uploads code to Circuit infrastructure
7. Encrypts env vars at rest and stores them separately from code artifacts
8. Syncs `id` and `version` back to `circuit.toml` (on first publish, writes the new agent `id`)
9. Polls publish status until complete
10. Returns agent ID, version, and a link to the agent page

**Requirements:**

* Must be authenticated (`circuit signin`)
* Valid `circuit.toml` configuration
* All dependencies installed

### Deployment Regions

If you set `deploymentRegionOverride` in `circuit.toml`, the allowed values are:

| Allowed values              | Default when omitted |
| --------------------------- | -------------------- |
| `us-east-1`, `eu-central-1` | `us-east-1`          |

**File exclusion:**

The CLI automatically excludes these patterns from uploads:

* Version control: `.git/**`, `.svn/**`
* Dependencies: `node_modules/**`, `dist/**`, `venv/**`, `__pycache__/**`
* Secrets: `*.key`, `*.pem`
* IDE files: `.vscode/**`, `.idea/**`, `*.swp`
* Build artifacts: `coverage/**`, `.pytest_cache/**`, `.cache/**`
* Lock files: `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
* Other: `Dockerfile`, `docker-compose.yml`, `*.md`, `*.sh`, `*.log`, `.DS_Store`

Additional patterns can be added via `filesToExclude` in your agent config.

> **Note:** `DESCRIPTION.md` is not uploaded as a file — its content is sent as agent metadata during publish.

**Content deduplication:**

Circuit calculates a content hash of your uploaded files on the server. If the hash matches a previously published version, a new version is not created and the existing version is reused. Files are still uploaded on each publish — deduplication applies to versioning only.

### Environment Variables

All commands that touch agent code (`run`, `unwind`, `check`, `publish`) load environment variables from `.env` files and support `--env` overrides. For `run` and `unwind`, env vars are injected into the locally spawned agent process. For `publish`, they are encrypted and stored for deploy-time injection.

**Source and precedence:**

* Base source: `.env` in the project root
* Overrides: `--env KEY=VALUE`
* If the same key exists in both, the CLI flag value wins

Example Argument usage:

```bash theme={null}
circuit publish --env KEY="value" --env KEY2="value2"
```

**Security model:**

* Env vars are encrypted before being stored in Circuit's infrastructure.
* Plaintext .env values are not stored in the uploaded source bundle or visible in the source code viewer.
* At deploy time, env vars are decrypted and injected into the agent's environment.
* Your code reads them normally with `process.env` (TypeScript) or `os.getenv()` (Python).

**Important limits and behavior:**

* Environment variables have a **4 KB total limit** (including system vars).
* Changing env vars changes the publish content hash, so a new version is created.
* To rotate env vars, republish your agent.


# Quick Reference
Source: https://docs.circuit.org/agent-developers/cli-references/quick-reference

All CLI commands, flags, and behavior at a glance.

### Commands

| Command                 | Description                                                               |
| ----------------------- | ------------------------------------------------------------------------- |
| `circuit signin`        | Authenticate via browser ([details](./authentication#sign-in))            |
| `circuit signout`       | Clear stored session ([details](./authentication#sign-out))               |
| `circuit whoami`        | Show current user ([details](./authentication#logged-in-user-info))       |
| `circuit new`           | Create new agent project ([details](./development#create-new-agent))      |
| `circuit run`           | Execute agent locally ([details](./development#run-agent-locally))        |
| `circuit unwind`        | Unwind positions and end session ([details](./development#unwind-agent))  |
| `circuit check`         | Validate project offline ([details](./development#check-agent-project))   |
| `circuit publish`       | Publish to Circuit infrastructure ([details](./publishing#publish-agent)) |
| `circuit wallet list`   | List available wallets ([details](./wallets#list-wallets))                |
| `circuit wallet import` | Import a test wallet ([details](./wallets#import-wallet))                 |

### Global Flags

Available on all commands:

| Flag            | Short | Description                                          |
| --------------- | ----- | ---------------------------------------------------- |
| `--path <path>` | `-p`  | Agent project directory (default: current directory) |
| `--json`        | `-j`  | Output results as JSON                               |
| `--help`        | `-h`  | Show command help                                    |

### `circuit new` Flags

| Flag         | Short | Values                                        | Description          |
| ------------ | ----- | --------------------------------------------- | -------------------- |
| `--language` | `-l`  | `typescript`, `python`                        | Skip language prompt |
| `--name`     | `-n`  | any string                                    | Skip name prompt     |
| `--template` | `-t`  | `basic`, `yield`, `polymarket`, `hyperliquid` | Skip template prompt |

### `circuit run` Flags

| Flag                       | Short | Description                                                    |
| -------------------------- | ----- | -------------------------------------------------------------- |
| `--wallet <address>`       | `-w`  | Wallet address (skips prompt)                                  |
| `--mode <mode>`            | `-m`  | `auto` or `manual` (default: first in `allowedExecutionModes`) |
| `--amount <amount>`        | `-a`  | Token amount in smallest unit                                  |
| `--env KEY=VALUE`          | `-e`  | Set/override env var (repeatable)                              |
| `--local-sdk-dependencies` | `-l`  | Skip automatic dependency installation                         |

### `circuit unwind` Flags

| Flag                       | Short | Description                            |
| -------------------------- | ----- | -------------------------------------- |
| `--wallet <address>`       | `-w`  | Wallet address (skips prompt)          |
| `--env KEY=VALUE`          | `-e`  | Set/override env var (repeatable)      |
| `--local-sdk-dependencies` | `-l`  | Skip automatic dependency installation |

### `circuit check` Flags

| Flag              | Short | Description                                      |
| ----------------- | ----- | ------------------------------------------------ |
| `--env KEY=VALUE` | `-e`  | Set/override env var for validation (repeatable) |

### `circuit publish` Flags

| Flag              | Short | Description                       |
| ----------------- | ----- | --------------------------------- |
| `--env KEY=VALUE` | `-e`  | Set/override env var (repeatable) |

### `circuit whoami` Flags

| Flag          | Short | Description                       |
| ------------- | ----- | --------------------------------- |
| `--show-auth` | `-a`  | Print base64 auth token for CI/CD |

### `circuit check` Output

Validates offline (no auth required):

* Config structure (valid `circuit.toml`)
* Entry point exists (`index.ts` or `main.py`)
* Handler export (`agent.getExport()` or `agent.get_handler()`)
* SDK version pinning
* Environment variable cross-referencing

### File Exclusion (Publish)

Automatically excluded from uploads:

| Category        | Patterns                                                                 |
| --------------- | ------------------------------------------------------------------------ |
| Version control | `.git/**`, `.svn/**`                                                     |
| Dependencies    | `node_modules/**`, `dist/**`, `venv/**`, `__pycache__/**`                |
| Secrets         | `*.key`, `*.pem`                                                         |
| IDE             | `.vscode/**`, `.idea/**`, `*.swp`                                        |
| Build artifacts | `coverage/**`, `.pytest_cache/**`, `.cache/**`                           |
| Lock files      | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`                       |
| Other           | `Dockerfile`, `docker-compose.yml`, `*.md`, `*.sh`, `*.log`, `.DS_Store` |

Additional patterns via `filesToExclude` in `circuit.toml`.

### Environment Variables

* **Source**: `.env` in project root + `--env` CLI flags (flags take precedence)
* **Supported commands**: `run`, `unwind`, `check`, `publish`
* **Local execution** (`run`, `unwind`): Env vars are injected into the spawned agent process
* **Publish**: Encrypted at rest, decrypted at deploy time
* **Access**: `process.env.KEY` (TypeScript) / `os.getenv("KEY")` (Python)
* **Limit**: 4 KB total (including system vars)
* **Rotation**: Republish to update

### Auth Storage

Credentials stored at `~/.config/circuit/auth-<environment>.json` (e.g. `auth-staging.json`) after `circuit signin`.


# Wallets
Source: https://docs.circuit.org/agent-developers/cli-references/wallets

CLI commands for managing test wallets.

### List Wallets

List your available wallets.

```bash theme={null}
circuit wallet list
```

**Output:**

| Column  | Description            |
| ------- | ---------------------- |
| Name    | Wallet name (if set)   |
| Balance | Total USD value        |
| Type    | `ethereum` or `solana` |
| Address | Wallet address         |

<Info>When running `circuit run`, wallets are filtered by your agent's `walletType` configuration. Only compatible wallets are shown.</Info>

### Import Wallet

Import a wallet for testing.

```bash theme={null}
circuit wallet import
```

**Prompts:**

1. **Wallet type**: Select Ethereum or Solana
2. **Wallet name**: A label to identify this wallet
3. **Private key**: Entered as a password field (not echoed to terminal)

**Behavior:**

* Validates the wallet credentials
* Stores the wallet on Circuit servers via the API
* The wallet becomes available for `circuit run`

**Security:**

* Private keys are entered via a masked password prompt (never visible in terminal)
* Wallets are stored on Circuit servers using the same secure storage as the web interface
* Private keys are encrypted and stored securely via Circuit's KMS (Key Management Service)
* Private keys never leave the KMS after import — only signed transactions are returned


# Agent Context
Source: https://docs.circuit.org/agent-developers/concepts/agent-context

Session data and SDK methods available in your agent functions.

`AgentContext` is passed to your `run` and `unwind` functions. It has session data and all SDK methods.

### Session Data

* `sessionId` (number): Unique session identifier
* `sessionWalletAddress` (string): Wallet address for this session
* `currentPositions` (array): Assets allocated to the agent at the start of execution
* `executionMode` (string): `"auto"` or `"manual"`

### SDK Methods

<Tabs>
  <Tab title="Python">
    * `log()`: Send messages to users and log locally
    * `memory`: Session-scoped key-value storage
    * `platforms`: Platform integrations (Polymarket, Hyperliquid)
    * `swidge`: Cross-chain swap and bridge operations
    * `sign_and_send()`: Sign and broadcast transactions
    * `sign_message()`: Sign messages (EVM only)
    * `transactions()`: Get transaction history
    * `get_current_positions()`: Get live positions
    * `clear_suggested_transactions()`: Clear pending suggestions (manual mode)
  </Tab>

  <Tab title="TypeScript">
    * `log()`: Send messages to users and log locally
    * `memory`: Session-scoped key-value storage
    * `platforms`: Platform integrations (Polymarket, Hyperliquid)
    * `swidge`: Cross-chain swap and bridge operations
    * `signAndSend()`: Sign and broadcast transactions
    * `signMessage()`: Sign messages (EVM only)
    * `transactions()`: Get transaction history
    * `getCurrentPositions()`: Get live positions
    * `clearSuggestedTransactions()`: Clear pending suggestions (manual mode)
  </Tab>
</Tabs>

### Basic Usage

<CodeGroup>
  ```python Python theme={null}
  def run(agent: AgentContext) -> None:
      agent.log(f"Session: {agent.sessionId}")
      agent.log(f"Wallet: {agent.sessionWalletAddress}")
      agent.log(f"Positions: {len(agent.currentPositions)}")
  ```

  ```typescript TypeScript theme={null}
  async function run(agent: AgentContext): Promise<void> {
    await agent.log(`Session: ${agent.sessionId}`);
    await agent.log(`Wallet: ${agent.sessionWalletAddress}`);
    await agent.log(`Positions: ${agent.currentPositions.length}`);
  }
  ```
</CodeGroup>

### Current Positions

`currentPositions` is a snapshot taken at execution start. After transactions, use `getCurrentPositions()` for updated balances. See [Positions](../sdk-reference/positions) for full details.

<CodeGroup>
  ```python Python theme={null}
  positions = agent.get_current_positions()
  if positions.success and positions.data:
      if positions.data.hasPendingTxs:
          agent.log("Pending transactions detected")
      # Use positions.data.positions
  ```

  ```typescript TypeScript theme={null}
  const positions = await agent.getCurrentPositions();
  if (positions.success && positions.data) {
    if (positions.data.hasPendingTxs) {
      await agent.log("Pending transactions detected");
    }
    // Use positions.data.positions
  }
  ```
</CodeGroup>

### See Also

* [Quick Reference](../sdk-reference/quick-reference) — All SDK methods at a glance
* [Execution Model](./execution-model) — How sessions and the run loop work
* [Positions](../sdk-reference/positions) — Full position management reference


# Execution Model
Source: https://docs.circuit.org/agent-developers/concepts/execution-model

Sessions, the run loop, and how agents execute.

<video>
  <source type="video/mp4" />
</video>

### Architecture

<Frame>
  <img alt="Circuit architecture diagram showing user lifecycle, transaction lifecycle, and how agent code interacts with the execution layer, policy engine, and blockchain." />
</Frame>

### Sessions

A session is a running instance of an agent on a specific wallet. Starting an agent creates a session that ties together your `run`/`unwind` functions, a wallet, an execution mode (`auto` or `manual`), and the user's asset allocations.

Sessions persist across execution cycles — your `run` function is called repeatedly at intervals, not just once.

### Session Lifecycle

```text theme={null}
User starts agent
       |
       v
   +--------+
   | Created |  -- Session initialized, assets allocated
   +----+---+
        |
        v
   +---------+
   | Running  |  -- run() called on each interval
   +----+---+
        |
        +---- User pauses --> Paused (session open, no run cycles)
        |                       |
        |                       +---- User resumes --> Running
        |
        +---- User stops  --> Stopped (session ends)
        |
        +---- User unwinds --> unwind() called --> Stopped
```

### Execution Flow

Each time your agent executes:

1. Circuit sends a `run` or `unwind` command to your agent
2. The SDK creates a fresh `AgentContext` with session data
3. Your `run` function is called with the `AgentContext`
4. Your code executes using SDK methods
5. Results are returned to Circuit
6. In manual mode, any transactions become suggestions for user approval in the UI

### The Run Loop

Circuit calls your `run` function on a recurring interval defined by `runtimeIntervalMinutes` in [`circuit.toml`](../getting-started/circuit-toml-reference):

```toml theme={null}
runtimeIntervalMinutes = 15
```

The interval starts after the previous `run` completes — not from the start of execution. Each cycle is independent: your function receives a fresh `AgentContext` each time. To persist state between cycles, use [Memory](../sdk-reference/memory).

### Run Function

<CodeGroup>
  ```python Python theme={null}
  def run(agent: AgentContext) -> None:
      # 1. Read currentPositions to understand holdings
      # 2. Apply strategy logic
      # 3. Execute trades, swaps, or other operations
  ```

  ```typescript TypeScript theme={null}
  async function run(agent: AgentContext): Promise<void> {
    // 1. Read currentPositions to understand holdings
    // 2. Apply strategy logic
    // 3. Execute trades, swaps, or other operations
  }
  ```
</CodeGroup>

### Unwind Function

Called when a user wants to unwind. It receives the positions to close, which may be a subset of total holdings.

<CodeGroup>
  ```python Python theme={null}
  def unwind(agent: AgentContext, positions: list[CurrentPosition]) -> None:
      for pos in positions:
          # Reverse each position (e.g., swap back to starting asset)
  ```

  ```typescript TypeScript theme={null}
  async function unwind(agent: AgentContext, positions: CurrentPosition[]): Promise<void> {
    for (const pos of positions) {
      // Reverse each position (e.g., swap back to starting asset)
    }
  }
  ```
</CodeGroup>

After `unwind` completes, the session ends.

### Modes

Configured via `allowedExecutionModes` in `circuit.toml`:

* **`auto`** — Transactions execute immediately
* **`manual`** — Transactions become suggestions for user approval

Your code is identical in both modes. Circuit routes the request based on the session's mode. In manual mode, the response includes `suggested` and `suggestionId` fields.

<Warning>
  All pending suggestions are automatically soft-deleted at the beginning of each `run` execution. Pass an `expiresAt` timestamp (ISO 8601) when submitting a transaction if you need a shorter expiry window.
</Warning>

For full details on modes, see [Manual vs Auto Mode](./manual-vs-auto-mode).

### Pausing and Resuming

Users can pause a running agent from the Circuit dashboard. While paused:

* The session stays open and asset allocations remain in place
* No `run` cycles are executed — the agent is effectively idle
* Memory and session state are preserved

When the user resumes, execution picks up on the next scheduled interval as if the agent had never stopped. No data is lost.

Pausing is useful when a user wants to temporarily halt an agent during volatile market conditions or while reviewing activity, without fully unwinding positions.

### Key Points

* **Multiple agents per wallet** — a wallet can run different agents simultaneously. However, the same agent cannot run twice on the same wallet.
* **Hyperliquid restriction** — only one Hyperliquid agent per wallet (to safely manage shared margin). Other (non-Hyperliquid) agents can still run on that wallet.
* **Session memory** persists across `run` cycles within a session, but is cleared when the session ends.
* **`currentPositions`** reflects balances at the start of each `run` execution — not live balances.
* **Uncaught exceptions** in `run` or `unwind` are caught by the SDK automatically. The execution is marked as failed and the error is logged.

### See Also

* [Agent Context](./agent-context) — Session data and SDK methods available in your functions
* [Wallets & Asset Allocation](./wallets-and-allocations) — How assets are allocated to sessions
* [Manual vs Auto Mode](./manual-vs-auto-mode) — Detailed mode comparison and suggestion lifecycle
* [Memory](../sdk-reference/memory) — Persist state between `run` cycles


# Manual vs Auto Mode
Source: https://docs.circuit.org/agent-developers/concepts/manual-vs-auto-mode

The two execution modes, how suggestions work, and controlling suggestion expiry.

### Execution Modes

Declare which modes your agent supports in `circuit.toml`:

```toml theme={null}
allowedExecutionModes = ["manual", "auto"]
```

* **`auto`** — Transactions execute immediately when your code calls a transactional SDK method
* **`manual`** — Transactions become **suggestions** that the user must approve in the Circuit UI before they are broadcast

The first entry in the array is used as the default mode when testing locally with `circuit run`.

### Same Code, Different Behavior

You write the same code regardless of mode. Circuit handles the routing:

<CodeGroup>
  ```python Python theme={null}
  # This code works in both auto and manual mode
  result = agent.sign_and_send({
      "network": "ethereum:1",
      "request": {
          "to_address": "0x...",
          "data": "0x",
          "value": "100000000000000",
      }
  })

  # In auto mode: result.data.tx_hash is the transaction hash
  # In manual mode: result.data.suggested = True, result.data.suggestionId = 123
  ```

  ```typescript TypeScript theme={null}
  // This code works in both auto and manual mode
  const result = await agent.signAndSend({
    network: "ethereum:1",
    request: {
      toAddress: "0x...",
      data: "0x",
      value: "100000000000000",
    }
  });

  // In auto mode: result.data.txHash is the transaction hash
  // In manual mode: result.data.suggested = true, result.data.suggestionId = 123
  ```
</CodeGroup>

### Suggestion Lifecycle

In manual mode:

1. Your agent calls a transactional method (e.g., `signAndSend`, `placeOrder`, `marketOrder`)
2. Circuit creates a suggestion visible to the user in the UI
3. The user approves or ignores the suggestion
4. If approved, Circuit executes the transaction
5. At the start of the next `run` cycle, all unapproved suggestions are automatically cleared

### `expiresAt`

All transactional methods accept an optional `expiresAt` parameter (ISO 8601 timestamp). If the user hasn't approved by this time, the suggestion is discarded. Useful when the transaction is only valid for a limited window (e.g., a quote that expires).

### Checking Mode at Runtime

<CodeGroup>
  ```python Python theme={null}
  if agent.executionMode == "manual":
      agent.log("Suggesting a swap — please approve in the Circuit UI")
  ```

  ```typescript TypeScript theme={null}
  if (agent.executionMode === "manual") {
    // Optionally provide more context in logs for manual mode users
    await agent.log("Suggesting a swap — please approve in the Circuit UI");
  }
  ```
</CodeGroup>

### Which Modes to Use

| Scenario                                              | Recommended Modes    |
| ----------------------------------------------------- | -------------------- |
| Fully automated strategy (yield farming, rebalancing) | `["auto"]`           |
| User wants full control over each trade               | `["manual"]`         |
| Flexible — let the user decide                        | `["manual", "auto"]` |

### Notes

* If your agent only supports `["auto"]`, it cannot be run in manual mode.
* If your agent only supports `["manual"]`, every transaction requires user approval.
* The `clearSuggestedTransactions()` method lets you manually clear pending suggestions mid-execution. See [Suggestions](../sdk-reference/suggestions).

### See Also

* [Suggestions](../sdk-reference/suggestions) — Control expiry and clear pending suggestions
* [circuit.toml Reference](../getting-started/circuit-toml-reference) — Configure `allowedExecutionModes`


# Wallets & Asset Allocation
Source: https://docs.circuit.org/agent-developers/concepts/wallets-and-allocations

Self-custodial wallets, asset allocation, and how positions work during execution.

### Self-Custodial Model

Circuit never takes custody of user funds. Private keys live in a secure enclave (KMS) completely separate from agent code. Agents can only **request** transactions — signing happens outside the agent sandbox. Agent code never sees private keys, users can export their wallet at any time, and all transactions are visible onchain.

### Wallet Types

Agents declare their required wallet type in `circuit.toml`:

* `"ethereum"` — EVM-compatible chains (Ethereum, Polygon, Arbitrum, Base, etc.)
* `"solana"` — Solana

An agent can only run on wallets matching its `walletType`.

### Starting Asset

Every agent defines a `startingAsset` in `circuit.toml` — the token a user must hold to start a session:

```toml theme={null}
[startingAsset]
network = "ethereum:137"
address = "0x2791bca1f2de4661ed88a30c99a7a9449aa84174"  # USDC on Polygon
minimumAmount = "1000000"  # 1 USDC (6 decimals)
```

* `network` — The chain where the asset lives ([Network Identifiers](../sdk-reference/quick-reference#network-identifiers))
* `address` — Token contract address. For native tokens: `"0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"` (EVM) or `"11111111111111111111111111111111"` (Solana)
* `minimumAmount` — Minimum balance required in raw units (wei, lamports, etc.)

### How Allocation Works

When a user starts a session:

1. Circuit verifies the user holds at least `minimumAmount` of the starting asset
2. The specified amount is allocated to the agent session
3. The agent receives these allocations as `agent.currentPositions`

**Hyperliquid exception**: For Hyperliquid agents, the entire wallet balance is available to the agent (not just an allocated portion). This is because Circuit restricts one Hyperliquid agent per wallet to safely manage margin requirements.

### Positions

| Method                                              | When to Use                                                                       |
| --------------------------------------------------- | --------------------------------------------------------------------------------- |
| `agent.currentPositions`                            | Snapshot at execution start. Fast, no API call. Use for initial decision-making.  |
| `getCurrentPositions()` / `get_current_positions()` | Live balances. Makes an API call. Use after transactions to verify updated state. |

**Important**: After executing transactions, `currentPositions` will be stale. Call `getCurrentPositions()` if you need updated balances within the same `run` cycle.

**Hyperliquid note**: Use `agent.platforms.hyperliquid.balances()` and `agent.platforms.hyperliquid.positions()` instead of `currentPositions` for Hyperliquid agents. See [Hyperliquid](../sdk-reference/hyperliquid#asset-allocation-notes).

### Pending Transactions

The `getCurrentPositions()` response includes a `hasPendingTxs` flag. When `true`, balances may not reflect recent transactions due to indexing delay (varies by chain). For time-sensitive logic, track position changes in [Memory](../sdk-reference/memory) instead of polling.

### Units

* All amounts are **strings** in **smallest units** (wei for EVM, lamports for Solana)
* Keep amounts as strings to preserve precision for large values
* **Hyperliquid exception**: Amounts are formatted values (e.g., `"1.5"` for \$1.50 USDC), not raw units

### See Also

* [Positions](../sdk-reference/positions) — Read and refresh balances during execution
* [Hyperliquid](../sdk-reference/hyperliquid#asset-allocation-notes) — Platform-specific balance methods
* [circuit.toml Reference](../getting-started/circuit-toml-reference) — Configure `startingAsset` and `walletType`


# Basic Agent
Source: https://docs.circuit.org/agent-developers/examples/basic-agent

A minimal starting point that demonstrates memory persistence across run cycles.

<Tip>
  Scaffold this example locally and test it with the CLI:

  ```bash theme={null}
  circuit new --name my-basic-agent --language python --template basic
  cd my-basic-agent
  circuit run    # execute a run cycle
  circuit unwind # test the unwind logic
  ```
</Tip>

### circuit.toml

```toml circuit.toml theme={null}
name = "Example Agent"
tagline = "A minimal Circuit agent"
walletType = "ethereum"
allowedExecutionModes = ["auto", "manual"]
imageUrl = "https://cdn.circuit.org/agents/default"
runtimeIntervalMinutes = 15
version = "0.0.1"

[startingAsset]
network = "ethereum:1" # Ethereum Mainnet
address = "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee" # Native ETH
minimumAmount = "0"
```

### Example

<CodeGroup>
  ```python Python theme={null}
  from agent_sdk import Agent, AgentContext
  from agent_sdk.agent_context import CurrentPosition


  def run(agent: AgentContext) -> None:
      agent.log("Starting execution")

      # Memory example — persist a counter across run cycles
      run_count_memory = agent.memory.get("run-count")
      if run_count_memory.success and run_count_memory.data:
          run_count = int(run_count_memory.data.value)
      else:
          run_count = 0
      run_count += 1

      agent.memory.set("run-count", str(run_count))
      agent.log(f"Session run count: {run_count}")


  def unwind(agent: AgentContext, positions: list[CurrentPosition]) -> None:
      agent.log(f"Unwinding {len(positions)} positions")


  agent = Agent(run_function=run, unwind_function=unwind)

  handler = agent.get_handler()

  if __name__ == "__main__":
      agent.run()
  ```

  ```typescript TypeScript theme={null}
  import { Agent, type AgentContext, type CurrentPosition } from "@circuitorg/agent-sdk";

  async function run(agent: AgentContext): Promise<void> {
    await agent.log("Starting execution");

    // Memory example — persist a counter across run cycles
    let runCount: number;
    const runCountMemory = await agent.memory.get("run-count");
    if (runCountMemory.success && runCountMemory.data) {
      runCount = parseInt(runCountMemory.data.value || "0", 10);
    } else {
      runCount = 0;
    }
    runCount += 1;

    await agent.memory.set("run-count", runCount.toString());
    await agent.log(`Session run count: ${runCount}`);
  }

  async function unwind(agent: AgentContext, positions: CurrentPosition[]): Promise<void> {
    await agent.log(`Unwinding ${positions.length} positions`);
  }

  const agent = new Agent({ runFunction: run, unwindFunction: unwind });

  export default agent.getExport();
  ```
</CodeGroup>

### Sample Output

```text theme={null}
Agent run started
Starting execution
Session run count: 1
Agent run completed
```

```text theme={null}
Agent unwind started
Unwinding 1 positions
Agent unwind completed
```

### How It Works

1. **Log**: Logs a starting message
2. **Read memory**: Retrieves a persistent counter from agent memory
3. **Increment & store**: Bumps the counter and writes it back
4. **Unwind**: Logs the number of positions being unwound

### Notes

* This is the default template used by `circuit new`. It's a good starting point for any agent.
* Agent memory persists across run cycles — use it for counters, flags, or any state you need between executions.
* See [CLI + SDK Context](../../CLI-SDK-CONTEXT.txt) for the full `AgentContext` API.


# Hyperliquid Agent
Source: https://docs.circuit.org/agent-developers/examples/hyperliquid-agent

A simple agent that buys ETH perps on Hyperliquid and closes positions on unwind.

<Tip>
  Scaffold this example locally and test it with the CLI:

  ```bash theme={null}
  circuit new --name my-hyperliquid-agent --language python --template hyperliquid
  cd my-hyperliquid-agent
  circuit run    # execute a run cycle
  circuit unwind # test the unwind logic
  ```
</Tip>

### circuit.toml

```toml circuit.toml theme={null}
name = "Example ETH Perp Agent"
tagline = "Buys ETH perps each cycle"
walletType = "ethereum"
allowedExecutionModes = ["auto", "manual"]
imageUrl = "https://cdn.circuit.org/agents/default"
runtimeIntervalMinutes = 60
version = "0.0.1"

[startingAsset]
network = "hypercore:perp" # Hyperliquid Perpetuals
address = "USDC" # USDC on Hyperliquid
minimumAmount = "20000000" # 20 USDC (6 decimals)
```

### Example

<CodeGroup>
  ```python Python theme={null}
  from agent_sdk import Agent, AgentContext
  from agent_sdk.agent_context import CurrentPosition

  BUY_SIZE = 0.01  # ETH to buy each cycle

  def run(agent: AgentContext) -> None:
      # Check available balance
      balances = agent.platforms.hyperliquid.balances()
      if not balances.success or not balances.data:
          agent.log(balances.error or "Failed to fetch balances", error=True)
          return

      withdrawable = float(balances.data.perp.withdrawable)
      agent.log(f"Withdrawable balance: ${withdrawable:.2f}")

      if withdrawable < 20:
          agent.log("Not enough balance to place order")
          return

      # Check existing positions
      positions = agent.platforms.hyperliquid.positions()
      if positions.success and positions.data:
          for pos in positions.data:
              agent.log(f"Open: {pos.symbol} {pos.side} {pos.size} @ {pos.entryPrice} (PnL: {pos.unrealizedPnl})")

      # Place a market buy for ETH perps
      # price acts as slippage limit for market orders — set above current market price
      order = agent.platforms.hyperliquid.place_order({
          "symbol": "ETH",
          "side": "buy",
          "size": BUY_SIZE,
          "price": 10000,  # Max price willing to pay (slippage limit)
          "market": "perp",
          "type": "market",
      })

      if order.success and order.data:
          agent.log(f"Order placed: {order.data.orderId} ({order.data.status})")

          # Track total buys in memory
          prev = agent.memory.get("totalBuys")
          count = int(prev.data.value) + 1 if prev.success and prev.data else 1
          agent.memory.set("totalBuys", str(count))
          agent.log(f"Total buy orders placed: {count}")
      else:
          agent.log(order.error or "Order failed", error=True)

  def unwind(agent: AgentContext, positions: list[CurrentPosition]) -> None:
      # Close all open perp positions
      open_positions = agent.platforms.hyperliquid.positions()
      if not open_positions.success or not open_positions.data or len(open_positions.data) == 0:
          agent.log("No open positions to close")
          return

      for pos in open_positions.data:
          close_side = "sell" if pos.side == "long" else "buy"
          # Use entry price with 50% slippage — must stay within 95% of reference price
          entry = float(pos.entryPrice)
          slippage_price = entry * 0.5 if close_side == "sell" else entry * 1.5
          close_order = agent.platforms.hyperliquid.place_order({
              "symbol": pos.symbol,
              "side": close_side,
              "size": float(pos.size),
              "price": slippage_price,
              "market": "perp",
              "type": "market",
              "reduceOnly": True,
          })

          if close_order.success and close_order.data:
              agent.log(f"Closed {pos.symbol} {pos.side}: {close_order.data.status}")
          else:
              agent.log(f"Failed to close {pos.symbol}: {close_order.error}", error=True)

  agent = Agent(run_function=run, unwind_function=unwind)

  handler = agent.get_handler()

  if __name__ == "__main__":
      agent.run()
  ```

  ```typescript TypeScript theme={null}
  import { Agent, type AgentContext, type CurrentPosition } from "@circuitorg/agent-sdk";

  const BUY_SIZE = 0.01; // ETH to buy each cycle

  async function run(agent: AgentContext): Promise<void> {
    // Check available balance
    const balances = await agent.platforms.hyperliquid.balances();
    if (!balances.success || !balances.data) {
      await agent.log(balances.error || "Failed to fetch balances", { error: true });
      return;
    }

    const withdrawable = parseFloat(balances.data.perp.withdrawable);
    await agent.log(`Withdrawable balance: $${withdrawable.toFixed(2)}`);

    if (withdrawable < 20) {
      await agent.log("Not enough balance to place order");
      return;
    }

    // Check existing positions
    const positions = await agent.platforms.hyperliquid.positions();
    if (positions.success && positions.data) {
      for (const pos of positions.data) {
        await agent.log(`Open: ${pos.symbol} ${pos.side} ${pos.size} @ ${pos.entryPrice} (PnL: ${pos.unrealizedPnl})`);
      }
    }

    // Place a market buy for ETH perps
    // price acts as slippage limit for market orders — set above current market price
    const order = await agent.platforms.hyperliquid.placeOrder({
      symbol: "ETH",
      side: "buy",
      size: BUY_SIZE,
      price: 10000, // Max price willing to pay (slippage limit)
      market: "perp",
      type: "market"
    });

    if (order.success && order.data) {
      await agent.log(`Order placed: ${order.data.orderId} (${order.data.status})`);

      // Track total buys in memory
      const prev = await agent.memory.get("totalBuys");
      const count = prev.success && prev.data ? parseInt(prev.data.value) + 1 : 1;
      await agent.memory.set("totalBuys", count.toString());
      await agent.log(`Total buy orders placed: ${count}`);
    } else {
      await agent.log(order.error || "Order failed", { error: true });
    }
  }

  async function unwind(agent: AgentContext, positions: CurrentPosition[]): Promise<void> {
    // Close all open perp positions
    const openPositions = await agent.platforms.hyperliquid.positions();
    if (!openPositions.success || !openPositions.data || openPositions.data.length === 0) {
      await agent.log("No open positions to close");
      return;
    }

    for (const pos of openPositions.data) {
      const closeSide = pos.side === "long" ? "sell" : "buy";
      // Use entry price with 50% slippage — must stay within 95% of reference price
      const entry = parseFloat(pos.entryPrice);
      const slippagePrice = closeSide === "sell" ? entry * 0.5 : entry * 1.5;
      const closeOrder = await agent.platforms.hyperliquid.placeOrder({
        symbol: pos.symbol,
        side: closeSide,
        size: parseFloat(pos.size),
        price: slippagePrice,
        market: "perp",
        type: "market",
        reduceOnly: true
      });

      if (closeOrder.success && closeOrder.data) {
        await agent.log(`Closed ${pos.symbol} ${pos.side}: ${closeOrder.data.status}`);
      } else {
        await agent.log(`Failed to close ${pos.symbol}: ${closeOrder.error}`, { error: true });
      }
    }
  }

  const agent = new Agent({
    runFunction: run,
    unwindFunction: unwind,
  });

  export default agent.getExport();
  ```
</CodeGroup>

### Sample Output

```text theme={null}
Agent run started
Withdrawable balance: $96.67
Open: BTC long 0.00031 @ 68237.0 (PnL: -0.26629)
Open: ETH long 0.021 @ 1951.33 (PnL: -0.175046)
Open: SOL long 0.13 @ 84.979 (PnL: -0.24856)
Order placed: 327024162229 (filled)
Total buy orders placed: 1
Agent run completed
```

```text theme={null}
Agent unwind started
Closed BTC long: filled
Closed ETH long: filled
Closed SOL long: filled
Agent unwind completed
```

### How It Works

1. **Check balance**: Reads withdrawable USDC from the perp account
2. **Log positions**: Shows any existing open positions with PnL
3. **Place order**: Buys a small ETH perp position with a market order
4. **Track state**: Uses memory to count total buy orders across cycles
5. **Unwind**: Closes all open positions with reduce-only market orders

### Notes

* The `price` field on market orders acts as a slippage limit — set it above current market for buys, below for sells.
* `reduceOnly: true` ensures the close order can only reduce an existing position, not open a new one.
* Hyperliquid amounts are formatted values (e.g., `0.01` ETH), not raw units like EVM chains.
* See [Hyperliquid tick and lot sizes](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size) for minimum order sizes per symbol.


# Polymarket Agent
Source: https://docs.circuit.org/agent-developers/examples/polymarket-agent

A sports prediction market agent that finds liquid markets and buys shares on Polymarket.

<Tip>
  Scaffold this example locally and test it with the CLI:

  ```bash theme={null}
  circuit new --name my-polymarket-agent --language python --template polymarket
  cd my-polymarket-agent
  circuit run    # execute a run cycle
  circuit unwind # test the unwind logic
  ```
</Tip>

### circuit.toml

```toml circuit.toml theme={null}
name = "Example Polymarket Agent"
tagline = "Trades on Polymarket markets"
walletType = "ethereum"
allowedExecutionModes = ["auto", "manual"]
imageUrl = "https://cdn.circuit.org/agents/default"
runtimeIntervalMinutes = 60
version = "0.0.1"

[startingAsset]
network = "ethereum:137" # Polygon
address = "0x2791bca1f2de4661ed88a30c99a7a9449aa84174" # USDC
minimumAmount = "5000000" # 5 USDC (6 decimals)
```

### Example

<CodeGroup>
  ```python Python theme={null}
  import json
  import requests
  from agent_sdk import Agent, AgentContext
  from agent_sdk.agent_context import CurrentPosition

  BUY_AMOUNT = 5  # USD to spend per cycle

  # Polygon USDC address
  USDC = "0x2791bca1f2de4661ed88a30c99a7a9449aa84174"

  CLOB_API = "https://clob.polymarket.com"

  def check_order_book_liquidity(token_id: str, side: str, min_usd: float) -> bool:
      """Check that the CLOB order book has enough liquidity for our order."""
      try:
          response = requests.get(
              f"{CLOB_API}/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 = 0
          for order in orders:
              price = float(order["price"])
              size = float(order["size"])
              total_usd += price * size

          return total_usd >= min_usd
      except Exception:
          return False

  def find_liquid_sports_market(min_liquidity_usd: float) -> dict | None:
      """Find the most liquid active sports market on Polymarket via the Gamma API."""
      try:
          response = requests.get(
              "https://gamma-api.polymarket.com/events/pagination",
              params={
                  "tag_slug": "sports",
                  "limit": 10,
                  "active": "true",
                  "closed": "false",
                  "archived": "false",
                  "order": "volume24hr",
                  "ascending": "false",
              },
              timeout=10,
          )
          events = response.json().get("data", [])

          for event in events:
              for market in event.get("markets", []):
                  if not market.get("acceptingOrders"):
                      continue

                  clob_token_ids = json.loads(market.get("clobTokenIds", "[]"))
                  outcomes = json.loads(market.get("outcomes", "[]"))
                  outcome_prices = json.loads(market.get("outcomePrices", "[]"))

                  if not clob_token_ids or not outcomes:
                      continue

                  price = float(outcome_prices[0]) if outcome_prices else 0

                  # Skip markets with extreme prices (thin liquidity on one side)
                  if price < 0.10 or price > 0.90:
                      continue

                  token_id = clob_token_ids[0]

                  # Verify order book has enough ask liquidity for our buy
                  if not check_order_book_liquidity(token_id, "BUY", min_liquidity_usd):
                      continue

                  return {
                      "tokenId": token_id,
                      "question": market.get("question", "Unknown"),
                      "outcome": outcomes[0],
                      "price": outcome_prices[0] if outcome_prices else "?",
                  }

      except Exception as e:
          print(f"Failed to fetch markets: {e}")

      return None

  def run(agent: AgentContext) -> None:
      # 1. Redeem any settled positions
      redemption = agent.platforms.polymarket.redeem_positions()
      if redemption.success and redemption.data:
          redeemed = [r for r in redemption.data if r.success]
          if redeemed:
              agent.log(f"Redeemed {len(redeemed)} settled positions")
              for r in redeemed:
                  if r.position:
                      agent.log(f"  {r.position.question} ({r.position.outcome}): ${r.position.valueUsd}")

      # 2. Check current positions and log Polymarket portfolio
      result = agent.get_current_positions()
      if not result.success or not result.data:
          agent.log(result.error or "Failed to get positions", error=True)
          return

      for pos in result.data.positions:
          if pos.polymarketMetadata:
              pm = pos.polymarketMetadata
              agent.log(f"{pm.question} [{pm.outcome}]: ${pm.valueUsd} (PnL: ${pm.pnlUsd})")

      # 3. Find USDC balance
      usdc = next(
          (p for p in result.data.positions if p.assetAddress.lower() == USDC),
          None,
      )
      usdc_balance = float(usdc.currentQty) / 1e6 if usdc else 0
      agent.log(f"USDC balance: ${usdc_balance:.2f}")

      if usdc_balance < BUY_AMOUNT:
          agent.log("Not enough USDC to buy")
          return

      # 4. Find the most liquid sports market (with order book liquidity check)
      market = find_liquid_sports_market(min_liquidity_usd=BUY_AMOUNT)
      if not market:
          agent.log("No active sports markets with sufficient liquidity found")
          return

      agent.log(f"Target market: {market['question']} [{market['outcome']}] @ {market['price']}")

      # 5. Buy a position
      buy = agent.platforms.polymarket.market_order({
          "tokenId": market["tokenId"],
          "size": BUY_AMOUNT,
          "side": "BUY",
      })

      if buy.success and buy.data:
          info = buy.data.orderInfo
          if info.totalPriceUsd:
              agent.log(f"Bought shares: ${info.totalPriceUsd} at ${info.priceUsd}/share (order {info.orderId})")
          else:
              agent.log(f"Order placed: {info.orderId} ({info.size} shares, {info.side})")
      else:
          agent.log(f"Buy failed: {buy.error}", error=True)

  def unwind(agent: AgentContext, positions: list[CurrentPosition]) -> None:
      # Sell all Polymarket positions
      result = agent.get_current_positions()
      if not result.success or not result.data:
          agent.log("Failed to get positions for unwind", error=True)
          return

      sold = 0
      for pos in result.data.positions:
          if not pos.polymarketMetadata:
              continue

          token_id = pos.tokenId
          if not token_id:
              continue

          shares = float(pos.currentQty) / 1e6  # Convert from raw units
          if shares <= 0:
              continue

          sell = agent.platforms.polymarket.market_order({
              "tokenId": token_id,
              "size": shares,
              "side": "SELL",
          })

          if sell.success and sell.data:
              pm = pos.polymarketMetadata
              agent.log(f"Sold {pm.question} ({pm.outcome}): ${sell.data.orderInfo.totalPriceUsd}")
              sold += 1
          else:
              agent.log(f"Failed to sell position: {sell.error}", error=True)

      if sold == 0:
          agent.log("No Polymarket positions to sell")

      # Redeem any settled positions
      agent.platforms.polymarket.redeem_positions()

  agent = Agent(run_function=run, unwind_function=unwind)

  handler = agent.get_handler()

  if __name__ == "__main__":
      agent.run()
  ```

  ```typescript TypeScript theme={null}
  import { Agent, type AgentContext, type CurrentPosition } from "@circuitorg/agent-sdk";

  const BUY_AMOUNT = 5; // USD to spend per cycle

  // Polygon USDC address
  const USDC = "0x2791bca1f2de4661ed88a30c99a7a9449aa84174";

  const CLOB_API = "https://clob.polymarket.com";

  async function checkOrderBookLiquidity(tokenId: string, side: string, minUsd: number): Promise<boolean> {
    /** Check that the CLOB order book has enough liquidity for our order. */
    try {
      const response = await fetch(`${CLOB_API}/book?token_id=${tokenId}`, { signal: AbortSignal.timeout(10000) });
      if (!response.ok) return false;

      const book = await response.json();
      const orders = book[side === "BUY" ? "asks" : "bids"] || [];

      let totalUsd = 0;
      for (const order of orders) {
        totalUsd += parseFloat(order.price) * parseFloat(order.size);
      }

      return totalUsd >= minUsd;
    } catch {
      return false;
    }
  }

  interface MarketInfo {
    tokenId: string;
    question: string;
    outcome: string;
    price: string;
  }

  async function findLiquidSportsMarket(minLiquidityUsd: number): Promise<MarketInfo | null> {
    /** Find the most liquid active sports market on Polymarket via the Gamma API. */
    try {
      const params = new URLSearchParams({
        tag_slug: "sports",
        limit: "10",
        active: "true",
        closed: "false",
        archived: "false",
        order: "volume24hr",
        ascending: "false",
      });

      const response = await fetch(
        `https://gamma-api.polymarket.com/events/pagination?${params}`,
        { signal: AbortSignal.timeout(10000) }
      );
      const { data: events = [] } = await response.json();

      for (const event of events) {
        for (const market of event.markets || []) {
          if (!market.acceptingOrders) continue;

          const clobTokenIds: string[] = JSON.parse(market.clobTokenIds || "[]");
          const outcomes: string[] = JSON.parse(market.outcomes || "[]");
          const outcomePrices: string[] = JSON.parse(market.outcomePrices || "[]");

          if (!clobTokenIds.length || !outcomes.length) continue;

          const price = outcomePrices.length ? parseFloat(outcomePrices[0]) : 0;

          // Skip markets with extreme prices (thin liquidity on one side)
          if (price < 0.10 || price > 0.90) continue;

          const tokenId = clobTokenIds[0];

          // Verify order book has enough ask liquidity for our buy
          if (!(await checkOrderBookLiquidity(tokenId, "BUY", minLiquidityUsd))) continue;

          return {
            tokenId,
            question: market.question || "Unknown",
            outcome: outcomes[0],
            price: outcomePrices.length ? outcomePrices[0] : "?",
          };
        }
      }
    } catch (e) {
      console.error(`Failed to fetch markets: ${e}`);
    }

    return null;
  }

  async function run(agent: AgentContext): Promise<void> {
    // 1. Redeem any settled positions
    const redemption = await agent.platforms.polymarket.redeemPositions();
    if (redemption.success && redemption.data) {
      const redeemed = redemption.data.filter((r) => r.success);
      if (redeemed.length > 0) {
        await agent.log(`Redeemed ${redeemed.length} settled positions`);
        for (const r of redeemed) {
          if (r.position) {
            await agent.log(`  ${r.position.question} (${r.position.outcome}): $${r.position.valueUsd}`);
          }
        }
      }
    }

    // 2. Check current positions and log Polymarket portfolio
    const result = await agent.getCurrentPositions();
    if (!result.success || !result.data) {
      await agent.log(result.error || "Failed to get positions", { error: true });
      return;
    }

    for (const pos of result.data.positions) {
      if (pos.polymarketMetadata) {
        const pm = pos.polymarketMetadata;
        await agent.log(`${pm.question} [${pm.outcome}]: $${pm.valueUsd} (PnL: $${pm.pnlUsd})`);
      }
    }

    // 3. Find USDC balance
    const usdc = result.data.positions.find(
      (p) => p.assetAddress.toLowerCase() === USDC
    );
    const usdcBalance = usdc ? parseFloat(usdc.currentQty) / 1e6 : 0;
    await agent.log(`USDC balance: $${usdcBalance.toFixed(2)}`);

    if (usdcBalance < BUY_AMOUNT) {
      await agent.log("Not enough USDC to buy");
      return;
    }

    // 4. Find the most liquid sports market (with order book liquidity check)
    const market = await findLiquidSportsMarket(BUY_AMOUNT);
    if (!market) {
      await agent.log("No active sports markets with sufficient liquidity found");
      return;
    }

    await agent.log(`Target market: ${market.question} [${market.outcome}] @ ${market.price}`);

    // 5. Buy a position
    const buy = await agent.platforms.polymarket.marketOrder({
      tokenId: market.tokenId,
      size: BUY_AMOUNT,
      side: "BUY",
    });

    if (buy.success && buy.data) {
      const info = buy.data.orderInfo;
      if (info.totalPriceUsd) {
        await agent.log(`Bought shares: $${info.totalPriceUsd} at $${info.priceUsd}/share (order ${info.orderId})`);
      } else {
        await agent.log(`Order placed: ${info.orderId} (${info.size} shares, ${info.side})`);
      }
    } else {
      await agent.log(`Buy failed: ${buy.error}`, { error: true });
    }
  }

  async function unwind(agent: AgentContext, positions: CurrentPosition[]): Promise<void> {
    // Sell all Polymarket positions
    const result = await agent.getCurrentPositions();
    if (!result.success || !result.data) {
      await agent.log("Failed to get positions for unwind", { error: true });
      return;
    }

    let sold = 0;
    for (const pos of result.data.positions) {
      if (!pos.polymarketMetadata) continue;

      const tokenId = pos.tokenId;
      if (!tokenId) continue;

      const shares = parseFloat(pos.currentQty) / 1e6; // Convert from raw units
      if (shares <= 0) continue;

      const sell = await agent.platforms.polymarket.marketOrder({
        tokenId,
        size: shares,
        side: "SELL",
      });

      if (sell.success && sell.data) {
        const pm = pos.polymarketMetadata;
        await agent.log(`Sold ${pm.question} (${pm.outcome}): $${sell.data.orderInfo.totalPriceUsd}`);
        sold++;
      } else {
        await agent.log(`Failed to sell position: ${sell.error}`, { error: true });
      }
    }

    if (sold === 0) {
      await agent.log("No Polymarket positions to sell");
    }

    // Redeem any settled positions
    await agent.platforms.polymarket.redeemPositions();
  }

  const agent = new Agent({
    runFunction: run,
    unwindFunction: unwind,
  });

  export default agent.getExport();
  ```
</CodeGroup>

### Sample Output

```text theme={null}
Agent run started
Redeemed 1 settled positions
  Will Spain win the 2026 FIFA World Cup? (Yes): $5.12
USDC balance: $12.34
Target market: Will Argentina win Copa America 2025? [Yes] @ 0.62
Bought shares: $5.00 at $0.62/share (order 8837291045)
Agent run completed
```

```text theme={null}
Agent unwind started
Sold 8.06 shares of token 123456... (order 9912345678)
Redeemed 1 settled positions
Agent unwind completed
```

### How It Works

1. **Redeem settled positions**: Claims winnings from any resolved markets
2. **Log portfolio**: Shows current Polymarket positions with PnL
3. **Check balance**: Finds USDC balance from current positions
4. **Find market**: Queries the Gamma API for liquid sports markets, filters by price range (0.10-0.90), and verifies order book depth via the CLOB API
5. **Buy shares**: Places a market buy order on the best available market
6. **Unwind**: Sells all open Polymarket positions and redeems settled ones

### Notes

* **Always check order book liquidity** before calling `marketOrder`. The CLOB will error if there aren't enough asks/bids to fill your order. See [Troubleshooting](../troubleshooting#polymarket-issues) for details.
* Polymarket uses USDC on Polygon (`ethereum:137`). Set your `startingAsset` accordingly.
* `size` means different things for buys vs sells: USD amount for BUY, share count for SELL.
* Token IDs are long numeric strings from Polymarket's API — they identify a specific outcome (e.g., "Yes" or "No") in a market.
* Use `redeemPositions()` to claim winnings after markets resolve. It's good practice to call it at the start of each run cycle.


# Yield Agent
Source: https://docs.circuit.org/agent-developers/examples/yield-agent

A simple agent that deposits all USDC into Aave V3 on Base and withdraws on unwind.

<Tip>
  Scaffold this example locally and test it with the CLI:

  ```bash theme={null}
  circuit new --name my-yield-agent --language python --template yield
  cd my-yield-agent
  circuit run    # execute a run cycle
  circuit unwind # test the unwind logic
  ```
</Tip>

### circuit.toml

```toml circuit.toml theme={null}
name = "Example Aave Yield Agent"
tagline = "Deposits USDC into Aave V3"
walletType = "ethereum"
allowedExecutionModes = ["auto", "manual"]
imageUrl = "https://cdn.circuit.org/agents/default"
runtimeIntervalMinutes = 60
version = "0.0.1"

[startingAsset]
network = "ethereum:8453" # Base
address = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" # USDC
minimumAmount = "1000000" # 1 USDC (6 decimals)
```

### Example

<CodeGroup>
  ```python Python theme={null}
  from agent_sdk import Agent, AgentContext
  from agent_sdk.agent_context import CurrentPosition
  from eth_abi import encode

  # Base addresses
  USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  AAVE_V3_POOL = "0xA238Dd80C259a72e81d7e4664a9801593F98d1c5"

  # Function selectors
  APPROVE_SELECTOR = "095ea7b3"
  SUPPLY_SELECTOR = "617ba037"
  WITHDRAW_SELECTOR = "69328dec"
  MAX_UINT256 = 2**256 - 1

  def build_approve_data(spender: str, amount: int) -> str:
      params = encode(["address", "uint256"], [spender, amount])
      return "0x" + APPROVE_SELECTOR + params.hex()

  def build_supply_data(asset: str, amount: int, on_behalf_of: str) -> str:
      params = encode(
          ["address", "uint256", "address", "uint16"], [asset, amount, on_behalf_of, 0]
      )
      return "0x" + SUPPLY_SELECTOR + params.hex()

  def build_withdraw_data(asset: str, amount: int, to: str) -> str:
      params = encode(["address", "uint256", "address"], [asset, amount, to])
      return "0x" + WITHDRAW_SELECTOR + params.hex()

  def run(agent: AgentContext) -> None:
      # Find USDC balance
      usdc = next(
          (p for p in agent.currentPositions if p.assetAddress.lower() == USDC.lower()),
          None,
      )
      if not usdc or int(usdc.currentQty) == 0:
          agent.log("No USDC to deposit")
          return

      amount = int(usdc.currentQty)
      agent.log(f"Depositing {usdc.currentQty} USDC (raw) into Aave V3")

      # Step 1: Approve Aave Pool to spend USDC (skip if already approved)
      approved_check = agent.memory.get("aaveApproved")
      already_approved = approved_check.success and approved_check.data and approved_check.data.value == "true"

      if not already_approved:
          approve_result = agent.sign_and_send({
              "network": "ethereum:8453",
              "wait_for_confirmation": True,
              "request": {
                  "to_address": USDC,
                  "data": build_approve_data(AAVE_V3_POOL, MAX_UINT256),
                  "value": "0",
              },
              "message": "Approve USDC for Aave V3",
          })

          if not approve_result.success:
              agent.log(f"Approve failed: {approve_result.error}", error=True)
              return
          agent.memory.set("aaveApproved", "true")
          agent.log("USDC approved for Aave V3")

      # Step 2: Supply USDC to Aave V3
      supply_result = agent.sign_and_send({
          "network": "ethereum:8453",
          "request": {
              "to_address": AAVE_V3_POOL,
              "data": build_supply_data(USDC, amount, agent.sessionWalletAddress),
              "value": "0",
          },
          "message": "Supply USDC to Aave V3",
      })

      if supply_result.success:
          agent.log("USDC deposited into Aave V3!")
      else:
          agent.log(f"Supply failed: {supply_result.error}", error=True)

  def unwind(agent: AgentContext, positions: list[CurrentPosition]) -> None:
      # Withdraw all USDC from Aave V3
      result = agent.sign_and_send({
          "network": "ethereum:8453",
          "request": {
              "to_address": AAVE_V3_POOL,
              "data": build_withdraw_data(USDC, MAX_UINT256, agent.sessionWalletAddress),
              "value": "0",
          },
          "message": "Withdraw all USDC from Aave V3",
      })

      if result.success:
          agent.log("Withdrawn all USDC from Aave V3")
      else:
          agent.log(f"Withdraw failed: {result.error}", error=True)

  agent = Agent(run_function=run, unwind_function=unwind)

  handler = agent.get_handler()

  if __name__ == "__main__":
      agent.run()
  ```

  ```typescript TypeScript theme={null}
  import { Agent, type AgentContext, type CurrentPosition } from "@circuitorg/agent-sdk";
  import { encodeFunctionData, parseAbi } from "viem";

  // Base addresses
  const USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
  const AAVE_V3_POOL = "0xA238Dd80C259a72e81d7e4664a9801593F98d1c5";

  const erc20Abi = parseAbi(["function approve(address spender, uint256 amount)"]);
  const aavePoolAbi = parseAbi([
    "function supply(address asset, uint256 amount, address onBehalfOf, uint16 referralCode)",
    "function withdraw(address asset, uint256 amount, address to)",
  ]);

  async function run(agent: AgentContext): Promise<void> {
    // Find USDC balance
    const usdc = agent.currentPositions.find(
      (p) => p.assetAddress.toLowerCase() === USDC.toLowerCase()
    );
    if (!usdc || BigInt(usdc.currentQty) === 0n) {
      await agent.log("No USDC to deposit");
      return;
    }

    const amount = BigInt(usdc.currentQty);
    await agent.log(`Depositing ${usdc.currentQty} USDC (raw) into Aave V3`);

    // Step 1: Approve Aave Pool to spend USDC (skip if already approved)
    const approvedCheck = await agent.memory.get("aaveApproved");
    const alreadyApproved = approvedCheck.success && approvedCheck.data?.value === "true";

    if (!alreadyApproved) {
      const approveData = encodeFunctionData({
        abi: erc20Abi,
        functionName: "approve",
        args: [AAVE_V3_POOL, 2n ** 256n - 1n], // max uint256 = approve once
      });

      const approveResult = await agent.signAndSend({
        network: "ethereum:8453",
        waitForConfirmation: true,
        request: {
          toAddress: USDC,
          data: approveData,
          value: "0",
        },
        message: "Approve USDC for Aave V3",
      });

      if (!approveResult.success) {
        await agent.log(`Approve failed: ${approveResult.error}`, { error: true });
        return;
      }
      await agent.memory.set("aaveApproved", "true");
      await agent.log("USDC approved for Aave V3");
    }

    // Step 2: Supply USDC to Aave V3
    const supplyData = encodeFunctionData({
      abi: aavePoolAbi,
      functionName: "supply",
      args: [USDC, amount, agent.sessionWalletAddress, 0],
    });

    const supplyResult = await agent.signAndSend({
      network: "ethereum:8453",
      request: {
        toAddress: AAVE_V3_POOL,
        data: supplyData,
        value: "0",
      },
      message: "Supply USDC to Aave V3",
    });

    if (supplyResult.success) {
      await agent.log("USDC deposited into Aave V3!");
    } else {
      await agent.log(`Supply failed: ${supplyResult.error}`, { error: true });
    }
  }

  async function unwind(agent: AgentContext, positions: CurrentPosition[]): Promise<void> {
    // Withdraw all USDC from Aave V3
    const withdrawData = encodeFunctionData({
      abi: aavePoolAbi,
      functionName: "withdraw",
      args: [USDC, 2n ** 256n - 1n, agent.sessionWalletAddress], // max uint256 = withdraw all
    });

    const result = await agent.signAndSend({
      network: "ethereum:8453",
      request: {
        toAddress: AAVE_V3_POOL,
        data: withdrawData,
        value: "0",
      },
      message: "Withdraw all USDC from Aave V3",
    });

    if (result.success) {
      await agent.log("Withdrawn all USDC from Aave V3");
    } else {
      await agent.log(`Withdraw failed: ${result.error}`, { error: true });
    }
  }

  const agent = new Agent({
    runFunction: run,
    unwindFunction: unwind,
  });

  export default agent.getExport();
  ```
</CodeGroup>

### Sample Output

```text theme={null}
Agent run started
USDC balance: 50.00 (raw: 50000000)
Approving Aave V3 Pool to spend USDC...
Approval confirmed: 0xabc123...
Supplying 50000000 USDC to Aave V3...
Supply confirmed: 0xdef456...
Agent run completed
```

```text theme={null}
Agent unwind started
Withdrawing all USDC from Aave V3...
Withdrawal confirmed: 0x789abc...
Agent unwind completed
```

### How It Works

1. **Check positions**: Finds USDC in `agent.currentPositions`
2. **Approve (once)**: On first run, approves Aave V3 Pool to spend USDC with max uint256 and stores a flag in memory. Uses `waitForConfirmation: true` to ensure the approval is confirmed onchain before proceeding. Subsequent runs skip this step.
3. **Supply**: Deposits USDC into Aave V3 using the Pool's `supply` function
4. **Unwind**: Withdraws all USDC from Aave V3 using `withdraw` with max uint256

### Notes

* This agent uses `signAndSend` to build custom transactions with ABI-encoded calldata. See [Custom Transactions and Signing](../sdk-reference/custom-transactions-signing) for details.
* TypeScript uses [viem](https://viem.sh/) for ABI encoding — add it with `bun add viem`.
* Python uses [eth-abi](https://pypi.org/project/eth-abi/) — add it with `uv pip install eth-abi`.
* Aave V3 Pool address and USDC address shown are for Base. Adjust for other networks.
* The `approve` + `supply` pattern is standard for any ERC-20 DeFi deposit. Use `waitForConfirmation: true` on the approval to ensure it's confirmed before the subsequent `supply` call.


# Agent Structure & Configuration
Source: https://docs.circuit.org/agent-developers/getting-started/circuit-toml-reference

Agent directory layout, code structure, circuit.toml configuration reference, and DESCRIPTION.md format.

### Directory Structure

<Tabs>
  <Tab title="Python">
    ```text theme={null}
    <agent-name>/
    ├── main.py               # Agent code (run/unwind functions)
    ├── DESCRIPTION.md        # Agent description (shown in Circuit UI)
    ├── circuit.toml         # Agent configuration
    └── pyproject.toml        # Dependencies
    ```
  </Tab>

  <Tab title="TypeScript">
    ```text theme={null}
    <agent-name>/
    ├── index.ts              # Agent code (run/unwind functions)
    ├── DESCRIPTION.md        # Agent description (shown in Circuit UI)
    ├── circuit.toml         # Agent configuration
    └── package.json          # Dependencies
    ```
  </Tab>
</Tabs>

***

### Agent Code

<CodeGroup>
  ```python Python theme={null}
  from agent_sdk import Agent, AgentContext
  from agent_sdk.agent_context import CurrentPosition

  def run(agent: AgentContext) -> None:
      agent.log("Hello from my agent!")
      # Your agent logic here

  def unwind(agent: AgentContext, positions: list[CurrentPosition]) -> None:
      agent.log(f"Unwind requested for {len(positions)} positions")
      # Optional unwind logic

  agent = Agent(run_function=run, unwind_function=unwind)

  handler = agent.get_handler()

  if __name__ == "__main__":
      agent.run()
  ```

  ```typescript TypeScript theme={null}
  import { Agent, type AgentContext, type CurrentPosition } from "@circuitorg/agent-sdk";

  async function run(agent: AgentContext): Promise<void> {
    await agent.log("Hello from my agent!");
    // Your agent logic here
  }

  async function unwind(agent: AgentContext, positions: CurrentPosition[]): Promise<void> {
    await agent.log(`Unwind requested for ${positions.length} positions`);
    // Optional unwind logic
  }

  const agent = new Agent({
    runFunction: run,
    unwindFunction: unwind
  });

  export default agent.getExport();
  ```
</CodeGroup>

#### `run` Function

<Tabs>
  <Tab title="Python">
    * Signature: `def run(agent: AgentContext) -> None:`
    * Called periodically based on `runtimeIntervalMinutes`
    * Receives `AgentContext` with session data and SDK methods
    * Returns `void` (no return value)
  </Tab>

  <Tab title="TypeScript">
    * Signature: `async function run(agent: AgentContext): Promise<void>`
    * Called periodically based on `runtimeIntervalMinutes`
    * Receives `AgentContext` with session data and SDK methods
    * Returns `void` (no return value)
  </Tab>
</Tabs>

#### `unwind` Function

<Tabs>
  <Tab title="Python">
    * Signature: `def unwind(agent: AgentContext, positions: list[CurrentPosition]) -> None:`
    * Called when you ask the agent to unwind positions
    * Optional unwind logic for the provided positions
    * Returns `void` (no return value)
  </Tab>

  <Tab title="TypeScript">
    * Signature: `async function unwind(agent: AgentContext, positions: CurrentPosition[]): Promise<void>`
    * Called when the agent is unwound
    * Optional unwind logic for the provided positions
    * Returns `void` (no return value)
  </Tab>
</Tabs>

***

### DESCRIPTION.md

Every agent must include a `DESCRIPTION.md` file alongside `circuit.toml`. This Markdown file is displayed to users in the Circuit UI.

```markdown theme={null}
## Summary

A brief description of what your agent does and the value it provides to users.

## Strategy

Explain the core logic and decision-making process your agent follows. Include details on which protocols it interacts with, what conditions trigger actions, and how it manages positions.

## Risks

Outline the key risks users should understand before starting a session. Consider market risk, smart contract risk, liquidity risk, and any other factors that could result in loss of funds.

## Changelog

- **0.0.1** — Initial release.
```

***

### circuit.toml

The `circuit.toml` file defines your agent's metadata, asset requirements, execution settings, and deployment configuration. It must be in the root of your agent directory.

#### Full Example

```toml theme={null}
name = "My Agent"                        # max 32 characters
tagline = "Short subtitle for cards"     # max 32 characters
walletType = "ethereum"
allowedExecutionModes = ["manual", "auto"]
runtimeIntervalMinutes = 15
filesToInclude = []
filesToExclude = []
imageUrl = "https://cdn.circuit.org/agents/default"
version = "0.0.1"
id = 123

[startingAsset]
network = "ethereum:1"
address = "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
minimumAmount = "10000000000000000"
```

#### Field Reference

| Field                      | Type      | Required | Description                                                                                                              |
| -------------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `name`                     | string    | Yes      | Display name shown in the Circuit UI (32 characters or less)                                                             |
| `tagline`                  | string    | Yes      | Brief subtitle shown on agent cards (32 characters or less)                                                              |
| `walletType`               | string    | Yes      | `"ethereum"` or `"solana"`                                                                                               |
| `allowedExecutionModes`    | string\[] | Yes      | Array of `"auto"` and/or `"manual"`. First entry is the default for `circuit run`.                                       |
| `runtimeIntervalMinutes`   | number    | Yes      | How often `run()` is called (in minutes). Interval starts after previous run completes.                                  |
| `version`                  | string    | Yes      | Semver version (`major.minor.patch`). Auto-bumped on `circuit publish` if not manually incremented.                      |
| `id`                       | number    | No       | Agent identity. Auto-set on first `circuit publish` — do not set manually. Allows renaming without creating a new agent. |
| `filesToInclude`           | string\[] | No       | Extra files/directories to upload (for monorepo setups). Relative paths from agent directory.                            |
| `filesToExclude`           | string\[] | No       | Files in agent directory to exclude from upload.                                                                         |
| `imageUrl`                 | string    | No       | Agent icon URL. Defaults to `"https://cdn.circuit.org/agents/default"`.                                                  |
| `deploymentRegionOverride` | string    | No       | Override deployment region. Allowed values: `"us-east-1"` or `"eu-central-1"`. Defaults to `"us-east-1"`.                |

#### Deployment Regions

| Allowed values              | Default when omitted |
| --------------------------- | -------------------- |
| `us-east-1`, `eu-central-1` | `us-east-1`          |

#### `[startingAsset]` Section

Defines the token a user must hold to start a session.

| Field           | Type   | Required | Description                                                                                                                                                                        |
| --------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `network`       | string | Yes      | [Network identifier](../sdk-reference/quick-reference#network-identifiers) (e.g., `"ethereum:1"`, `"solana"`, `"hypercore:perp"`)                                                  |
| `address`       | string | Yes      | Token contract address. For native tokens: `"0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"` (EVM) or `"11111111111111111111111111111111"` (Solana). For Hyperliquid perps: `"USDC"`. |
| `minimumAmount` | string | Yes      | Minimum balance in raw units (wei, lamports, USDC with 6 decimals for Hyperliquid).                                                                                                |

#### Common Configurations

**EVM agent with ETH on mainnet:**

```toml theme={null}
walletType = "ethereum"

[startingAsset]
network = "ethereum:1"
address = "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
minimumAmount = "10000000000000000"  # 0.01 ETH
```

**EVM agent with USDC on Polygon:**

```toml theme={null}
walletType = "ethereum"

[startingAsset]
network = "ethereum:137"
address = "0x2791bca1f2de4661ed88a30c99a7a9449aa84174"
minimumAmount = "10000000"  # 10 USDC (6 decimals)
```

**Solana agent with SOL:**

```toml theme={null}
walletType = "solana"

[startingAsset]
network = "solana"
address = "11111111111111111111111111111111"
minimumAmount = "100000000"  # 0.1 SOL (9 decimals)
```

**Hyperliquid perps agent:**

```toml theme={null}
walletType = "ethereum"

[startingAsset]
network = "hypercore:perp"
address = "USDC"
minimumAmount = "1000000"  # 1 USDC (6 decimals)
```

#### Notes

* The `id` field is written to `circuit.toml` automatically after your first publish. Once set, it ties subsequent publishes to the same agent — you can rename your agent freely without creating a duplicate. Do not copy `id` values between projects.
* The `version` field follows semver. If you don't increment it before `circuit publish`, the CLI auto-bumps the patch version.
* `filesToInclude` paths are relative to the agent directory. Use `../../utils` to include shared code from a monorepo root. See [Multi-Agent Monorepo](./multi-agent-monorepo).
* `allowedExecutionModes` order matters — the first entry is used as the execution mode when running locally with `circuit run`.

***

### Next Steps

* [Execution Model](../concepts/execution-model) — How sessions and the run loop work
* [Multi-Agent Monorepo](./multi-agent-monorepo) — Share code across multiple agents


# Installation
Source: https://docs.circuit.org/agent-developers/getting-started/installation

Install the Circuit CLI and SDK for your chosen language.

### What you'll need

* A Circuit account (to run/publish agents)
* Bun installed (required for Circuit CLI)
* Python 3.12+ with [uv](https://docs.astral.sh/uv/getting-started/installation/) for Python agents, or Bun for TypeScript agents

### Step 1: CLI

Install the [Circuit CLI](https://www.npmjs.com/package/@circuitorg/agent-cli) using Bun:

```bash theme={null}
bun install -g @circuitorg/agent-cli
circuit --version
```

### Step 2: SDK (Python OR TypeScript)

Choose either Python or TypeScript to develop your agent in, then install the respective SDK.
If you use `circuit new`, the generated project already includes the SDK dependency in the project files.

#### Python SDK

Install the [Circuit Agent SDK](https://pypi.org/project/circuit-agent-sdk/) using `uv`:

```bash theme={null}
uv pip install circuit-agent-sdk
```

#### TypeScript SDK

Install the [Circuit Agent SDK](https://www.npmjs.com/package/@circuitorg/agent-sdk) using `bun`:

```bash theme={null}
bun add @circuitorg/agent-sdk
```


# Multi-Agent Monorepo
Source: https://docs.circuit.org/agent-developers/getting-started/multi-agent-monorepo

Organize multiple agents in a single repository and share utility code across them.

<Note>This section is for advanced use cases. If you're building a single agent, you can skip this entirely.</Note>

The CLI supports monorepo setups where multiple agents share utility code.

> **Important:** Each agent's dependency file (`pyproject.toml` for Python, `package.json` for TypeScript) should include the dependencies for any shared utils being used.

### Monorepo Structure

The recommended structure uses separate directories for agents and shared utilities:

<CodeGroup>
  ```text Python theme={null}
  my-circuit-agents/
  ├── agents/
  │   ├── sample-agent-1/
  │   │   ├── main.py
  │   │   ├── DESCRIPTION.md
  │   │   ├── circuit.toml
  │   │   └── pyproject.toml
  │   ├── sample-agent-2/
  │   │   ├── main.py
  │   │   ├── DESCRIPTION.md
  │   │   ├── circuit.toml
  │   │   └── pyproject.toml
  └── utils/
      ├── __init__.py
      ├── polymarket/
      │   ├── __init__.py
      │   └── trading.py
      ├── hyperliquid/
      │   ├── __init__.py
      │   └── positions.py
      └── analytics/
          ├── __init__.py
          └── metrics.py
  ```

  ```text TypeScript theme={null}
  my-circuit-agents/
  ├── agents/
  │   ├── sample-agent-1/
  │   │   ├── index.ts
  │   │   ├── DESCRIPTION.md
  │   │   ├── circuit.toml
  │   │   ├── package.json
  │   │   └── tsconfig.json
  │   ├── sample-agent-2/
  │   │   ├── index.ts
  │   │   ├── DESCRIPTION.md
  │   │   ├── circuit.toml
  │   │   ├── package.json
  │   │   └── tsconfig.json
  └── utils/
      ├── index.ts
      ├── polymarket/
      │   ├── index.ts
      │   └── trading.ts
      ├── hyperliquid/
      │   ├── index.ts
      │   └── positions.ts
      └── analytics/
          ├── index.ts
          └── metrics.ts
  ```
</CodeGroup>

### Setting Up Shared Utilities

#### 1. Create the Utils Package

Create a `utils/` directory at your monorepo root with proper package structure:

<CodeGroup>
  ```bash Python theme={null}
  # From your monorepo root
  mkdir -p utils/polymarket utils/hyperliquid utils/analytics
  touch utils/__init__.py
  touch utils/polymarket/__init__.py
  touch utils/hyperliquid/__init__.py
  touch utils/analytics/__init__.py
  ```

  ```bash TypeScript theme={null}
  # From your monorepo root
  mkdir -p utils/polymarket utils/hyperliquid utils/analytics
  touch utils/index.ts
  touch utils/polymarket/index.ts
  touch utils/hyperliquid/index.ts
  touch utils/analytics/index.ts
  ```
</CodeGroup>

#### 2. Export Functions in Module Index Files

Make your utility functions easily importable by exporting them:

<CodeGroup>
  ```python Python theme={null}
  # utils/polymarket/__init__.py
  from .trading import get_positions, place_order

  __all__ = [
      "get_positions",
      "place_order",
  ]
  ```

  ```typescript TypeScript theme={null}
  // utils/polymarket/index.ts
  export { getPositions, placeOrder } from './trading';
  ```
</CodeGroup>

#### 3. Configure `filesToInclude`

In each agent's `circuit.toml`, specify which shared directories to include:

```toml theme={null}
# agents/trading-bot/circuit.toml
name = "Trading Bot"
# ... other config ...
# Include all shared utilities
filesToInclude = ["../../utils"]

# Or include only specific subdirectories
# filesToInclude = ["../../utils/polymarket", "../../utils/analytics"]
```

> **Note:** The `filesToInclude` configuration works the same for both Python and TypeScript agents.

#### 4. Configure Module Resolution And Import Syntax

Set up module resolution to enable imports in local development.

**Python:** Add these lines at the top of your agent's `main.py`. This adds your monorepo root to Python's search path, which is needed because Python doesn't automatically look in parent directories.

```python theme={null}
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent))

# Now you can import shared utilities
from utils.polymarket import get_positions, place_order
from utils.analytics import calculate_sharpe_ratio
```

**TypeScript:** Configure your agent's `tsconfig.json` with path aliases, then import using the alias:

```json theme={null}
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "~/*": ["../../*"]
    }
  }
}
```

```typescript theme={null}
import { getPositions, placeOrder } from '~/utils/polymarket';
import { calculateSharpeRatio } from '~/utils/analytics';
```


# Quickstart
Source: https://docs.circuit.org/agent-developers/getting-started/quickstart

Create and publish your first agent in three steps. By the end, you'll have a running agent that logs a message to the Circuit UI every 15 minutes.

### Step 1: Create Your Agent

Sign in and scaffold a new agent project:

```bash theme={null}
circuit signin
circuit new
```

The CLI prompts you for a template, a language (TypeScript or Python), and an agent name, then generates a project directory with your agent code, `circuit.toml` config, and dependencies.

Install dependencies and navigate into the project:

<CodeGroup>
  ```bash TypeScript theme={null}
  cd agent-name && bun install
  ```

  ```bash Python theme={null}
  cd agent-name && uv sync
  ```
</CodeGroup>

Your generated agent code looks like this:

<CodeGroup>
  ```python Python theme={null}
  from agent_sdk import Agent, AgentContext

  def run(agent: AgentContext) -> None:
      agent.log("Hello from my agent!")

  agent = Agent(run_function=run)

  handler = agent.get_handler()

  if __name__ == "__main__":
      agent.run()
  ```

  ```typescript TypeScript theme={null}
  import { Agent, type AgentContext } from "@circuitorg/agent-sdk";

  async function run(agent: AgentContext): Promise<void> {
    await agent.log("Hello from my agent!");
  }

  const agent = new Agent({ runFunction: run });

  export default agent.getExport();
  ```
</CodeGroup>

### Step 2: Test Locally

```bash theme={null}
circuit run
```

The CLI prompts you to select a wallet, creates a test session, and executes your `run` function. You should see output like:

```text theme={null}
✓ Connected to wallet 0x1234...abcd
✓ Session created (mode: manual)
ℹ Running agent...
  Hello from my agent!
✓ Execution complete
```

### Step 3: Publish

```bash theme={null}
circuit publish
```

If your agent needs API keys or other secrets, create a local `.env` file before publishing:

```bash theme={null}
YOUR_API_KEY=...
```

`circuit publish` reads `.env` from the agent root, then applies any `--env KEY=VALUE` overrides, encrypts those values at rest, and injects them into your deployed agent runtime as normal environment variables. For more details, see [Publishing → Environment Variables](../cli-references/publishing#environment-variables).

This uploads your agent to Circuit. Once published, users can find and run it through the [Circuit app](https://app.circuit.org).


# Introduction
Source: https://docs.circuit.org/agent-developers/introduction

This documentation covers how to build, test, and publish Circuit agents using the Circuit CLI and SDKs.

### AI-Assisted Development

* [**AGENTS.md**](../CLI-SDK-CONTEXT.txt) — Full SDK context for AI coding assistants
* [**llms.txt**](https://docs.circuit.org/llms.txt) — Lightweight site index for LLMs
* [**llms-full.txt**](https://docs.circuit.org/llms-full.txt) — Complete documentation in a single file
* [**MCP Server**](./sdk-reference/sdk-context) — Connect your assistant to Circuit docs via MCP

***

Circuit agents are programs that run on Circuit's infrastructure, read wallet balances, and request transactions on behalf of users. You write a `run` function, Circuit calls it on a recurring interval, and any transactions your code requests are routed through a secure signing layer — your agent never touches private keys.

You can go from zero to a published agent in about 10 minutes.

### What you'll need

* **Bun** (required for the CLI and TypeScript agents)
* **Python 3.12+** and **uv** (for Python agents)
* A [Circuit account](https://app.circuit.org) with a wallet
* The Circuit CLI: `bun install -g @circuitorg/agent-cli`

### Contents

1. [**Installation**](./getting-started/installation): Install the tools, create your first agent, and configure `circuit.toml`.
2. [**Core Concepts**](./concepts/execution-model): Understand sessions, the run loop, wallets, and execution modes.
3. [**Examples**](./examples/yield-agent): Working example agents.
4. [**SDK Reference**](./sdk-reference/quick-reference): Complete method reference for the Agent SDK.
5. [**CLI Reference**](./cli-references/authentication): Documentation for the CLI tool.
6. [**Advanced**](./getting-started/multi-agent-monorepo): Multi-agent monorepos and troubleshooting.

### Quick Links

* **CLI**: [npm package](https://www.npmjs.com/package/@circuitorg/agent-cli)
* **Python SDK**: [PyPI](https://pypi.org/project/circuit-agent-sdk/)
* **TypeScript SDK**: [npm package](https://www.npmjs.com/package/@circuitorg/agent-sdk)


# Custom Transactions and Signing
Source: https://docs.circuit.org/agent-developers/sdk-reference/custom-transactions-signing

Sign and broadcast custom built transactions on Ethereum, Solana, and other supported networks. This will require you to build your own transaction calldata.

Use custom transactions when you need to interact with smart contracts directly — for example, depositing into an Aave pool, calling a custom DeFi protocol, or executing any onchain operation not covered by the swap/bridge or platform integrations.

It is recommended to use viem or web3py to populate calldata and other raw transaction data, rather than doing raw low-level transformations in the script.

Refer to DefiLlama as a high-quality data source.

### Sign and Send

Sign and broadcast a transaction.

<CodeGroup>
  ```python Python theme={null}
  def sign_and_send(request: SignAndSendRequest | dict) -> SignAndSendResponse
  ```

  ```typescript TypeScript theme={null}
  async signAndSend(request: SignAndSendRequest): Promise<SignAndSendResponse>
  ```
</CodeGroup>

#### Ethereum (EVM Chains)

**Request:**

* `network` (string): [Network identifier](./quick-reference#network-identifiers)
* `request` (object):
  * `toAddress` (string): Recipient address (hex string)
  * `data` (string): Calldata (hex string, use "0x" for transfers)
  * `value` (string): Wei amount (string)
  * `gas` (number, optional): Gas limit. If omitted, estimated automatically with a 25% buffer.
  * `maxFeePerGas` (string, optional): Max fee per gas in wei. If omitted, estimated from current network conditions.
  * `maxPriorityFeePerGas` (string, optional): Max priority fee per gas in wei. If omitted, estimated from current network conditions.
  * `enforceTransactionSuccess` (boolean, optional): If `true` (default), the transaction will be simulated before signing and rejected if simulation fails.
* `message` (string, optional): Context message for logging (max 250 characters)
* `expiresAt` (string | null, optional): ISO 8601 timestamp. In manual mode, the suggestion expires at this time. If omitted, no time-based expiry is set (suggestions are auto-cleared at each `run` start).
* `waitForConfirmation` (boolean, optional): EVM only. The SDK polls a public RPC for the transaction receipt after broadcast and returns `success: false` if the transaction reverted onchain. Set to `false` to skip receipt polling and return immediately after broadcast. Defaults to `true`.

**Example:**

<CodeGroup>
  ```python Python theme={null}
  response = agent.sign_and_send({
      "network": "ethereum:1",
      "request": {
          "to_address": agent.sessionWalletAddress,
          "data": "0x",
          "value": "100000000000000",  # 0.0001 ETH
      },
      "message": "Self-send demo",
  })

  if response.success and response.data:
      agent.log(f"Transaction sent: {response.data.tx_hash}")
      if response.data.transaction_url:
          agent.log(f"View: {response.data.transaction_url}")
  else:
      agent.log(response.error or "Transaction failed", error=True)
  ```

  ```typescript TypeScript theme={null}
  const response = await agent.signAndSend({
    network: "ethereum:1",
    request: {
      toAddress: agent.sessionWalletAddress,
      data: "0x",
      value: "100000000000000", // 0.0001 ETH
    },
    message: "Self-send demo"
  });

  if (response.success && response.data) {
    await agent.log(`Transaction sent: ${response.data.txHash}`);
    if (response.data.transactionUrl) {
      await agent.log(`View: ${response.data.transactionUrl}`);
    }
  } else {
    await agent.log(response.error || "Transaction failed", { error: true });
  }
  ```
</CodeGroup>

#### Solana

**Request:**

* `network` (string): "solana"
* `request` (object):
  * `hexTransaction` (string): Serialized VersionedTransaction as hex string

**Example:**

<CodeGroup>
  ```python Python theme={null}
  response = agent.sign_and_send({
      "network": "solana",
      "request": {
          "hex_transaction": "010001030a0b..."  # Serialized transaction
      }
  })

  if response.success and response.data:
      agent.log(f"Transaction: {response.data.tx_hash}")
  ```

  ```typescript TypeScript theme={null}
  const response = await agent.signAndSend({
    network: "solana",
    request: {
      hexTransaction: "010001030a0b..." // Serialized transaction
    }
  });

  if (response.success && response.data) {
    await agent.log(`Transaction: ${response.data.txHash}`);
  }
  ```
</CodeGroup>

**Response:**

* `success` (boolean): Whether the transaction was signed and broadcast
* `data.txHash` / `data.tx_hash` (string): Transaction hash (on success)
* `data.transactionUrl` / `data.transaction_url` (string, optional): Explorer link (on success)
* `error` (string | null): Error message (on failure)

### Sign Message

Sign a message on an EVM network (EIP-712 or EIP-191).

<CodeGroup>
  ```python Python theme={null}
  def sign_message(request: EvmMessageSignRequest | dict) -> EvmMessageSignResponse
  ```

  ```typescript TypeScript theme={null}
  async signMessage(request: SignMessageRequest): Promise<SignMessageResponse>
  ```
</CodeGroup>

**Request:**

* `network` (string): "ethereum:chainId" for EVM networks
* `request` (object):
  * `messageType` (string): "eip712" or "eip191"
  * `chainId` (number): Ethereum chain ID
  * `data` (object): Message data structure
    * For EIP-712: `{ domain, types, primaryType, message }`
    * For EIP-191: `{ message }` (plain text)

**Response:**

* `success` (boolean): Whether the message was signed
* `data` (object): Signature data (on success)
  * `v` (number): Signature v component
  * `r` (string): Signature r component (hex)
  * `s` (string): Signature s component (hex)
  * `formattedSignature` (string): Complete signature (hex)
  * `type` (string): Always "evm"
* `error` (string | null): Error message (on failure)

**Example:**

<CodeGroup>
  ```python Python theme={null}
  # EIP-191 simple message
  result = agent.sign_message({
      "network": "ethereum:1",
      "request": {
          "messageType": "eip191",
          "chainId": 1,
          "data": {"message": "Hello, world!"}
      }
  })
  if result.success and result.data:
      agent.log(f"Signature: {result.data.formattedSignature}")
  else:
      agent.log(result.error or "Signing failed", error=True)
  ```

  ```typescript TypeScript theme={null}
  // EIP-191 simple message
  const result = await agent.signMessage({
    network: "ethereum:1",
    request: {
      messageType: "eip191",
      data: { message: "Hello, world!" },
      chainId: 1
    }
  });
  if (result.success && result.data) {
    await agent.log(`Signature: ${result.data.formattedSignature}`);
  } else {
    await agent.log(result.error || "Signing failed", { error: true });
  }
  ```
</CodeGroup>

### Notes

* `signMessage` is EVM-only. Solana message signing is not supported.
* Gas estimation: When `gas`, `maxFeePerGas`, and `maxPriorityFeePerGas` are omitted, the execution layer estimates them automatically. Gas limits include a 25% buffer over the simulation estimate.
* `enforceTransactionSuccess` defaults to `true`. Set to `false` only if you expect the transaction to revert in simulation but still want to submit it (rare).
* `waitForConfirmation` (default `true`) polls a public RPC for the transaction receipt (up to 30 seconds). If the transaction reverts onchain, the response returns `success: false` with an error. Set to `false` when you don't need to wait for confirmation — for example, fire-and-forget transactions where you'll check the result later.

### See Also

* [Yield Agent Example](../examples/yield-agent) — Full working agent using `signAndSend` for Aave deposits
* [Quick Reference](./quick-reference#network-identifiers) — Network identifiers and native token addresses
* [Suggestions](./suggestions) — Control suggestion expiry with `expiresAt` in manual mode


# Error Handling
Source: https://docs.circuit.org/agent-developers/sdk-reference/error-handling

All SDK methods return response objects with consistent `success`/`error` patterns.

Use these patterns to handle failures gracefully — checking `success` before using `data`, logging errors for visibility in the UI, and matching specific error codes when you need different recovery logic per failure type.

### Response Structure

All SDK methods return response objects:

<CodeGroup>
  ```python Python theme={null}
  {
      success: bool
      data: any | None
      error: str | None
  }
  ```

  ```typescript TypeScript theme={null}
  {
    success: boolean;
    data?: any;
    error?: string;
  }
  ```
</CodeGroup>

### Checking Results

Always check `success` before using `data`:

<CodeGroup>
  ```python Python theme={null}
  result = agent.memory.get("key")
  if result.success and result.data:
      # Safe to use result.data
      agent.log(f"Value: {result.data.value}")
  else:
      # Handle error
      agent.log(f"Error: {result.error}", error=True)
  ```

  ```typescript TypeScript theme={null}
  const result = await agent.memory.get("key");
  if (result.success && result.data) {
    // Safe to use result.data
    await agent.log(`Value: ${result.data.value}`);
  } else {
    // Handle error
    await agent.log(`Error: ${result.error}`, { error: true });
  }
  ```
</CodeGroup>

### Uncaught Exceptions

Uncaught exceptions in `run` or `unwind` are caught by the SDK. The execution is marked as failed and the `error` is logged. You don't need to wrap SDK method calls in try/catch blocks unless you need to handle for a specific error.

<CodeGroup>
  ```python Python theme={null}
  def run(agent: AgentContext) -> None:
      # This typo will be caught and logged automatically
      agent.memmory.set("key", "value")  # AttributeError

      # No try/except needed
  ```

  ```typescript TypeScript theme={null}
  async function run(agent: AgentContext): Promise<void> {
    // This typo will be caught and logged automatically
    await agent.memmory.set("key", "value"); // TypeError

    // No try/catch needed
  }
  ```
</CodeGroup>

### When to Use Try/Catch

Only use try/catch for your own logic that might throw (parsing, calculations with external data, custom recovery). Don't use it for SDK method calls — just check `.success` instead.

### Swap Error Codes

Swap methods (`agent.swidge.quote()`, `agent.swidge.execute()`) return typed error codes in the `error` field:

| Error Code              | Cause                                       | Solution                                                 |
| ----------------------- | ------------------------------------------- | -------------------------------------------------------- |
| `QUOTE_TIMEOUT`         | Quote request timed out                     | Retry after a brief delay                                |
| `ALL_ENGINES_FAILED`    | Every routing engine returned an error      | Check input parameters; the route may not be available   |
| `NO_COMPATIBLE_ENGINES` | No engine supports this token pair or route | Verify token addresses and network IDs                   |
| `ENGINE_API_ERROR`      | Upstream routing engine returned an error   | Retry; if persistent, the engine may be temporarily down |
| `PRICE_IMPACT_TOO_HIGH` | Price impact exceeds acceptable threshold   | Reduce swap amount or increase slippage tolerance        |
| `INSUFFICIENT_BALANCE`  | Wallet balance too low for this swap        | Check positions before quoting                           |
| `INTERNAL_ERROR`        | Unexpected internal error                   | Log and retry; contact support if persistent             |

### Hyperliquid Error Codes

Hyperliquid methods (`agent.platforms.hyperliquid.*`) return error messages in the `error` field. See [Hyperliquid: Common Errors](./hyperliquid#common-errors) for the full table.

### Polymarket Error Codes

Polymarket methods (`agent.platforms.polymarket.*`) return typed error codes:

| Error Code                  | Cause                                      | Solution                                              |
| --------------------------- | ------------------------------------------ | ----------------------------------------------------- |
| `ORDERBOOK_NOT_FOUND`       | No orderbook for the given token           | Verify tokenId from Polymarket                        |
| `MARKET_NOT_FOUND`          | Market does not exist                      | Check that the market hasn't been resolved or removed |
| `TOKEN_NOT_IN_MARKET`       | Token ID not associated with market        | Use correct tokenId for the market                    |
| `INSUFFICIENT_LIQUIDITY`    | Not enough liquidity to fill order         | Reduce order size or wait for more liquidity          |
| `INSUFFICIENT_BALANCE`      | Wallet USDC balance too low for this order | Check balances before placing orders                  |
| `ORDER_REJECTED`            | Order was rejected by the exchange         | Check order parameters (size, side)                   |
| `UPSTREAM_API_ERROR`        | Polymarket API returned an error           | Retry; check Polymarket status                        |
| `UPSTREAM_HTTP_ERROR`       | HTTP error from Polymarket                 | Retry with backoff                                    |
| `UPSTREAM_INVALID_RESPONSE` | Unexpected response format from Polymarket | Likely a temporary API issue; retry                   |
| `NETWORK_ERROR`             | Network connectivity issue                 | Retry with backoff                                    |
| `CREDENTIALS_ERROR`         | Invalid or missing API credentials         | Ensure session is active and wallet is valid          |
| `INTERNAL_ERROR`            | Unexpected internal error                  | Log and retry; contact support if persistent          |

### Transaction Reverts

When `waitForConfirmation` is `true` (the default), the SDK polls a public RPC for the transaction receipt after broadcast. If the transaction was mined but reverted onchain, the response returns `success: false`:

<CodeGroup>
  ```python Python theme={null}
  result = agent.sign_and_send({
      "network": "ethereum:1",
      "request": {
          "to_address": "0x...",
          "data": "0x...",
          "value": "0",
      },
  })

  if not result.success:
      if result.error and "reverted" in result.error:
          agent.log("Transaction reverted onchain", error=True)
      else:
          agent.log(f"Error: {result.error}", error=True)
  ```

  ```typescript TypeScript theme={null}
  const result = await agent.signAndSend({
    network: "ethereum:1",
    request: {
      toAddress: "0x...",
      data: "0x...",
      value: "0",
    },
  });

  if (!result.success) {
    if (result.error?.includes("reverted")) {
      await agent.log("Transaction reverted onchain", { error: true });
    } else {
      await agent.log(`Error: ${result.error}`, { error: true });
    }
  }
  ```
</CodeGroup>

This applies to all transacting methods: `signAndSend`, `swidge.execute`, `polymarket.marketOrder`, and `polymarket.redeemPositions`. Set `waitForConfirmation: false` to skip receipt polling and return immediately after broadcast.

### General Error Patterns

| Error                | Cause                              | Solution                                                       |
| -------------------- | ---------------------------------- | -------------------------------------------------------------- |
| "Key not found"      | Memory key doesn't exist           | Check if key exists first or handle missing keys               |
| "Invalid request"    | Bad parameters to SDK method       | Validate inputs before calling SDK methods                     |
| "Transaction failed" | Insufficient balance/gas or revert | Check balances via `getCurrentPositions()` before transactions |

### Tips

* Always check `success` before using `data`
* Log errors with `error: true` / `error=True` so they show up in the UI
* Return early on errors instead of continuing
* Validate inputs before making SDK calls
* Match against specific error codes when you need different handling per failure type

### See Also

* [Troubleshooting](../troubleshooting) — Common issues and solutions for CLI, SDK, and platform-specific problems
* [Logging](./logging) — Log errors with `error: true` so they appear in the UI


# Hyperliquid
Source: https://docs.circuit.org/agent-developers/sdk-reference/hyperliquid

Trade perpetual futures and spot markets on Hyperliquid DEX.

Use the Hyperliquid integration to build agents that trade perpetual futures and spot markets. Common strategies include market making, momentum trading, and delta-neutral farming.

### Configuration

To define USDC Perps as your agent's starting asset, use the following `network` and `address` in the `circuit.toml` file.

```toml theme={null}
[startingAsset]
network = "hypercore:perp"
address = "USDC"
minimumAmount = "1000000"  # 1 USDC (6 decimals)
```

### Asset Allocation Notes

Circuit restricts users from running multiple Hyperliquid agents per wallet. This enables your agent to safely manage margin requirements on open perpetual positions without potential interference from other agents. This also introduces a few quirks to be aware of.

* For Hyperliquid agents, your entire wallet balance is available to the agent when you start a session.
* The `minimumAmount` will still ensure that anyone running the agent will at least have that amount.
* Your agent should use the below methods to pull available balances/positions directly from Hyperliquid, as opposed to the `agent.currentPositions` property.
  * Balances: `agent.platforms.hyperliquid.balances()`
  * Positions: `agent.platforms.hyperliquid.positions()`
  * **IMPORTANT: Be careful with your usage of these methods in loops (avoid entirely if possible), Hyperliquid will rate limit if too many requests are sent.**
  * > Note: Hyperliquid balances are not yet included in `agent.currentPositions`. This will be added in a future release once Circuit's Hyperliquid indexing is complete.

### Units

When querying via Hyperliquid's API (via `agent.platforms.hyperliquid`), all values will be returned in their formatted value, as opposed to the rest of Circuit which returns values in their raw units (wei/lamports)

### Place Order

If you are unfamiliar with placing orders via Hyperliquid's API, please see [these docs](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size) for information regarding tick/lot sizes, as well as decimals.

<CodeGroup>
  ```python Python theme={null}
  def place_order(request: HyperliquidPlaceOrderRequest | dict) -> HyperliquidPlaceOrderResponse
  ```

  ```typescript TypeScript theme={null}
  async placeOrder(request: HyperliquidPlaceOrderRequest): Promise<HyperliquidPlaceOrderResponse>
  ```
</CodeGroup>

**Request Parameters:**

* `symbol` (string): Trading pair symbol. For perps: `"BTC"`. For spot: `"BTC/USDC"`.
* `side` (string): "buy" or "sell"
* `size` (number): Order size
* `price` (number): Order price. For market orders, acts as slippage limit (maximum acceptable execution price). For limit orders, the limit price.
* `market` (string): "perp" or "spot"
* `type` (string, optional): "market", "limit", "stop", "take\_profit"
* `triggerPrice` (number, optional): Trigger price for stop/take-profit orders
* `reduceOnly` (boolean, optional): Whether this is a reduce-only order
* `postOnly` (boolean, optional): Whether this is a post-only order
* `expiresAt` (string | null, optional): ISO 8601 timestamp. In manual mode, the suggestion expires at this time. If omitted, no time-based expiry is set (suggestions are auto-cleared at each `run` start).

**Response:**

* `success` (boolean): Whether the operation succeeded
* `data` (object): Order information (on success)
  * `orderId` (string): Order ID
  * `symbol` (string): Trading pair symbol
  * `side` (string): "buy" or "sell"
  * `price` (number): Order price
  * `size` (number): Order size
  * `filled` (number): Filled amount
  * `status` (string): Order status
  * `market` (string): "perp" or "spot"
* `error` (string | null): Error message (on failure)

**Example:**

<CodeGroup>
  ```python Python theme={null}
  # Perp market order
  perp_order = agent.platforms.hyperliquid.place_order({
      "symbol": "BTC",
      "side": "buy",
      "size": 0.0001,
      "price": 110000,  # Acts as slippage limit for market orders
      "market": "perp",
      "type": "market"
  })

  if perp_order.success and perp_order.data:
      agent.log(f"Perp Order {perp_order.data.orderId}: {perp_order.data.status}")

  # Spot market order
  spot_order = agent.platforms.hyperliquid.place_order({
      "symbol": "BTC/USDC",
      "side": "buy",
      "size": 0.0001,
      "price": 110000,  # Acts as slippage limit for market orders
      "market": "spot",
      "type": "market"
  })
  ```

  ```typescript TypeScript theme={null}
  // Perp market order
  const perpOrder = await agent.platforms.hyperliquid.placeOrder({
    symbol: "BTC",
    side: "buy",
    size: 0.0001,
    price: 110000, // Acts as slippage limit for market orders
    market: "perp",
    type: "market"
  });

  if (perpOrder.success && perpOrder.data) {
    await agent.log(`Perp Order ${perpOrder.data.orderId}: ${perpOrder.data.status}`);
  }

  // Spot market order
  const spotOrder = await agent.platforms.hyperliquid.placeOrder({
    symbol: "BTC/USDC",
    side: "buy",
    size: 0.0001,
    price: 110000, // Acts as slippage limit for market orders
    market: "spot",
    type: "market"
  });
  ```
</CodeGroup>

### Balances

Get account balances.

<CodeGroup>
  ```python Python theme={null}
  def balances() -> HyperliquidBalancesResponse
  ```

  ```typescript TypeScript theme={null}
  async balances(): Promise<HyperliquidBalancesResponse>
  ```
</CodeGroup>

**Response:**

* `success` (boolean): Whether the operation succeeded
* `data.perp` (object): Perp account balance
  * `accountValue` (string): Total account value
  * `totalMarginUsed` (string): Total margin used
  * `withdrawable` (string): Withdrawable amount
* `data.spot` (array): Spot token balances
  * `coin` (string): Token symbol
  * `total` (string): Total balance
  * `hold` (string): Amount on hold (in open orders)
* `error` (string | null): Error message (on failure)

**Example:**

<CodeGroup>
  ```python Python theme={null}
  balances = agent.platforms.hyperliquid.balances()
  if balances.success and balances.data:
      agent.log(f"Account value: {balances.data.perp.accountValue}")
      agent.log(f"Withdrawable: {balances.data.perp.withdrawable}")

      for token in balances.data.spot:
          agent.log(f"{token.coin}: {token.total} (hold: {token.hold})")
  ```

  ```typescript TypeScript theme={null}
  const balances = await agent.platforms.hyperliquid.balances();
  if (balances.success && balances.data) {
    await agent.log(`Account value: ${balances.data.perp.accountValue}`);
    await agent.log(`Withdrawable: ${balances.data.perp.withdrawable}`);

    for (const token of balances.data.spot) {
      await agent.log(`${token.coin}: ${token.total} (hold: ${token.hold})`);
    }
  }
  ```
</CodeGroup>

### Positions

Get open positions.

<CodeGroup>
  ```python Python theme={null}
  def positions() -> HyperliquidPositionsResponse
  ```

  ```typescript TypeScript theme={null}
  async positions(): Promise<HyperliquidPositionsResponse>
  ```
</CodeGroup>

**Response:**

* `success` (boolean): Whether the operation succeeded
* `data` (array): Array of open positions
  * `symbol` (string): Trading pair symbol
  * `side` (string): "long" or "short"
  * `size` (string): Position size
  * `entryPrice` (string): Average entry price
  * `markPrice` (string): Current mark price
  * `liquidationPrice` (string | null): Liquidation price
  * `unrealizedPnl` (string): Unrealized profit/loss
  * `leverage` (string): Current leverage
  * `marginUsed` (string): Margin allocated to position
* `error` (string | null): Error message (on failure)

**Example:**

<CodeGroup>
  ```python Python theme={null}
  positions = agent.platforms.hyperliquid.positions()
  if positions.success and positions.data:
      for pos in positions.data:
          agent.log(f"{pos.symbol} {pos.side}: {pos.size} @ {pos.entryPrice}")
          agent.log(f"  PnL: {pos.unrealizedPnl}, Leverage: {pos.leverage}x")
          if pos.liquidationPrice:
              agent.log(f"  Liq price: {pos.liquidationPrice}")
  ```

  ```typescript TypeScript theme={null}
  const positions = await agent.platforms.hyperliquid.positions();
  if (positions.success && positions.data) {
    for (const pos of positions.data) {
      await agent.log(`${pos.symbol} ${pos.side}: ${pos.size} @ ${pos.entryPrice}`);
      await agent.log(`  PnL: ${pos.unrealizedPnl}, Leverage: ${pos.leverage}x`);
      if (pos.liquidationPrice) {
        await agent.log(`  Liq price: ${pos.liquidationPrice}`);
      }
    }
  }
  ```
</CodeGroup>

### Order

Get order information by order ID.

<CodeGroup>
  ```python Python theme={null}
  def order(order_id: str) -> HyperliquidOrderResponse
  ```

  ```typescript TypeScript theme={null}
  async order(orderId: string): Promise<HyperliquidOrderResponse>
  ```
</CodeGroup>

**Response:**

* `success` (boolean): Whether the operation succeeded
* `data` (object): Order information (same shape as `placeOrder` response)
  * `orderId` (string): Order ID
  * `symbol` (string): Trading pair symbol
  * `side` (string): "buy" or "sell"
  * `price` (number): Order price
  * `size` (number): Order size
  * `filled` (number): Filled amount
  * `status` (string): Order status
  * `market` (string): "perp" or "spot"
* `error` (string | null): Error message (on failure)

### Delete Order

Cancel an order.

<CodeGroup>
  ```python Python theme={null}
  def delete_order(order_id: str, symbol: str) -> HyperliquidDeleteOrderResponse
  ```

  ```typescript TypeScript theme={null}
  async deleteOrder(orderId: string, symbol: string): Promise<HyperliquidDeleteOrderResponse>
  ```
</CodeGroup>

**Example:**

<CodeGroup>
  ```python Python theme={null}
  result = agent.platforms.hyperliquid.delete_order("1234567890", "BTC")
  if result.success:
      agent.log("Order cancelled")
  else:
      agent.log(result.error or "Failed to cancel order", error=True)
  ```

  ```typescript TypeScript theme={null}
  const result = await agent.platforms.hyperliquid.deleteOrder("1234567890", "BTC");
  if (result.success) {
    await agent.log("Order cancelled");
  } else {
    await agent.log(result.error || "Failed to cancel order", { error: true });
  }
  ```
</CodeGroup>

### Open Orders

Get all open orders.

<CodeGroup>
  ```python Python theme={null}
  def open_orders() -> HyperliquidOpenOrdersResponse
  ```

  ```typescript TypeScript theme={null}
  async openOrders(): Promise<HyperliquidOpenOrdersResponse>
  ```
</CodeGroup>

**Response:**

* `success` (boolean): Whether the operation succeeded
* `data` (array): Array of open orders (same shape as `placeOrder` response — `orderId`, `symbol`, `side`, `price`, `size`, `filled`, `status`, `market`)
* `error` (string | null): Error message (on failure)

### Orders

Get historical orders.

<CodeGroup>
  ```python Python theme={null}
  def orders() -> HyperliquidHistoricalOrdersResponse
  ```

  ```typescript TypeScript theme={null}
  async orders(): Promise<HyperliquidHistoricalOrdersResponse>
  ```
</CodeGroup>

**Response includes:**

* `status`: "open", "filled", "canceled", "triggered", "rejected", "marginCanceled", "liquidatedCanceled"
* `orderType`: "Market", "Limit", "Stop Market", "Stop Limit", "Take Profit Market", "Take Profit Limit"
* `timestamp`: Order creation timestamp
* `statusTimestamp`: Status update timestamp

### Order Fills

Get order fill history.

<CodeGroup>
  ```python Python theme={null}
  def order_fills() -> HyperliquidOrderFillsResponse
  ```

  ```typescript TypeScript theme={null}
  async orderFills(): Promise<HyperliquidOrderFillsResponse>
  ```
</CodeGroup>

**Response includes:**

* `price` (string): Fill price
* `size` (string): Fill size
* `fee` (string): Trading fee paid
* `isMaker` (boolean): True if maker, false if taker

### Transfer

Transfer between spot and perp accounts.

<CodeGroup>
  ```python Python theme={null}
  def transfer(request: HyperliquidTransferRequest | dict) -> HyperliquidTransferResponse
  ```

  ```typescript TypeScript theme={null}
  async transfer(request: HyperliquidTransferRequest): Promise<HyperliquidTransferResponse>
  ```
</CodeGroup>

**Request Parameters:**

* `amount` (number): Amount to transfer
* `toPerp` (boolean): `true` to transfer to perp account, `false` to transfer to spot
* `expiresAt` (string | null, optional): ISO 8601 timestamp for suggestion expiry in manual mode.

**Example:**

<CodeGroup>
  ```python Python theme={null}
  # Transfer USDC from spot to perp account
  transfer = agent.platforms.hyperliquid.transfer({
      "amount": 1000.0,
      "toPerp": True
  })

  if transfer.success:
      agent.log("Transfer completed")
  ```

  ```typescript TypeScript theme={null}
  // Transfer USDC from spot to perp account
  const transfer = await agent.platforms.hyperliquid.transfer({
    amount: 1000.0,
    toPerp: true
  });

  if (transfer.success) {
    await agent.log("Transfer completed");
  }
  ```
</CodeGroup>

### Liquidations

Get liquidation events.

<CodeGroup>
  ```python Python theme={null}
  def liquidations(start_time: int | None = None) -> HyperliquidLiquidationsResponse
  ```

  ```typescript TypeScript theme={null}
  async liquidations(startTime?: number): Promise<HyperliquidLiquidationsResponse>
  ```
</CodeGroup>

**Parameters:**

* `startTime` (number, optional): Unix timestamp in milliseconds to filter liquidations from

**Response includes:**

* `timestamp` (number): Liquidation timestamp
* `liquidatedPositions` (array): Liquidated positions
* `totalNotional` (string): Total notional value liquidated
* `accountValue` (string): Account value at liquidation
* `leverageType` (string): "Cross" or "Isolated"
* `txHash` (string): Transaction hash

### Common Errors

Errors are returned in the `error` field of the response. Common errors include:

| Error                                         | Cause                                           | Solution                                                               |
| --------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------- |
| "Unknown perp asset: . Available assets: ..." | Symbol not found in available perps             | Use a valid perp symbol like `"BTC"`, `"ETH"`                          |
| "Unknown spot pair: . Available pairs: ..."   | Symbol not found in available spot pairs        | Use a valid spot pair like `"BTC/USDC"`, `"ETH/USDC"`                  |
| "Invalid coin format: "                       | Invalid symbol format                           | Ensure symbol matches expected format (perps: "BTC", spot: "BTC/USDC") |
| " order requires triggerPrice"                | Stop or take\_profit order missing triggerPrice | Provide `triggerPrice` parameter for stop/take\_profit orders          |
| "Order not found"                             | Order ID doesn't exist                          | Verify order ID is correct                                             |
| "Failed to place order"                       | Order submission failed                         | Check order parameters and account balance                             |

Note: Additional error messages may be returned by Hyperliquid's API. Check the `error` field in the response for specific details.

### Notes

* All balance and position amounts are strings to preserve precision.
* Market orders use `price` as a slippage limit (maximum acceptable execution price).
* Transfer operations return void responses (no `data` on success).
* **Spot symbols** use the format `"BTC/USDC"`, while **perp symbols** use just the base asset like `"BTC"`.
* Hyperliquid rate-limits aggressively. Avoid calling `balances()` or `positions()` in loops.

### See Also

* [Hyperliquid Agent Example](../examples/hyperliquid-agent) — Full working trading agent
* [Wallets & Asset Allocation](../concepts/wallets-and-allocations) — Why Hyperliquid agents get the full wallet balance
* [Suggestions](./suggestions) — Control suggestion expiry with `expiresAt` in manual mode


# Logging
Source: https://docs.circuit.org/agent-developers/sdk-reference/logging

Send messages to users and log locally with a unified logging interface.

Use logging to surface status updates, errors, and debug info. Standard logs appear in the Circuit UI for end users; debug logs stay in the console during local development.

### Log

<CodeGroup>
  ```python Python theme={null}
  def log(
      message: str | dict | list | BaseModel,
      error: bool = False,
      debug: bool = False
  ) -> LogResponse
  ```

  ```typescript TypeScript theme={null}
  async log(
    message: string | object | any[],
    options?: { error?: boolean; debug?: boolean }
  ): Promise<LogResponse>
  ```
</CodeGroup>

**Parameters:**

* `message`: String, object, array, or Pydantic model to log
* `error` (optional): If `true`, log as error level
* `debug` (optional): If `true`, only log to console (skip backend)

**Response:**

* `success` (boolean): Whether the log was sent
* `error` (string | null): Error message if sending failed

**Example:**

<CodeGroup>
  ```python Python theme={null}
  # Standard log
  agent.log("Processing transaction")

  # Error log
  agent.log("Failed to load settings", error=True)

  # Debug log (console only)
  agent.log("Internal state", debug=True)

  # Log dict - ONLY DO THIS WHEN DEBUGGING. The user needs to see a nicely formatted string
  agent.log({"wallet": agent.sessionWalletAddress, "status": "active"}, debug=True)
  ```

  ```typescript TypeScript theme={null}
  // Standard log
  await agent.log("Processing transaction");

  // Error log
  await agent.log("Failed to load settings", { error: true });

  // Debug log (console only)
  await agent.log("Internal state", { debug: true });

  // Log object - ONLY DO THIS WHEN DEBUGGING. The user needs to see a nicely formatted string
  await agent.log({ wallet: agent.sessionWalletAddress, status: "active" }, { debug: true});
  ```
</CodeGroup>

### Notes

* To ensure a good user experience, make sure that any logs which do not have `debug=True` are clean and concise.
* Objects and arrays are pretty-printed in the console and serialized to JSON strings when sent to the backend.
* Pydantic models (Python) are automatically converted via `.model_dump()` before serialization.

### See Also

* [Error Handling](./error-handling) — Log errors with `error: true` so they appear in the UI
* [Agent Context](../concepts/agent-context) — All SDK methods available on the agent object


# Memory
Source: https://docs.circuit.org/agent-developers/sdk-reference/memory

Session-scoped key-value storage. Keys are automatically namespaced by agentId and sessionId.

Use memory to persist state between `run` cycles within a session — for example, storing the last rebalance timestamp to avoid trading too frequently, tracking cumulative PnL, or caching external API responses.

Access memory methods via `agent.memory`.

### Set Value

Store a key-value pair.

<CodeGroup>
  ```python Python theme={null}
  def set(key: str, value: str) -> MemorySetResponse
  ```

  ```typescript TypeScript theme={null}
  async set(key: string, value: string): Promise<MemorySetResponse>
  ```
</CodeGroup>

**Parameters:**

* `key` (string): Unique identifier (1-255 characters)
* `value` (string): String value to store

**Response:**

* `success` (boolean): Whether the operation succeeded
* `data.key` (string): The key that was set (on success)
* `error` (string | null): Error message (on failure)

**Example:**

<CodeGroup>
  ```python Python theme={null}
  result = agent.memory.set("lastSwapNetwork", "ethereum:42161")
  if result.success and result.data:
      agent.log(f"Stored: {result.data.key}")
  ```

  ```typescript TypeScript theme={null}
  const result = await agent.memory.set("lastSwapNetwork", "ethereum:42161");
  if (result.success && result.data) {
    await agent.log(`Stored: ${result.data.key}`);
  }
  ```
</CodeGroup>

### Get Value

Retrieve a value by key.

<CodeGroup>
  ```python Python theme={null}
  def get(key: str) -> MemoryGetResponse
  ```

  ```typescript TypeScript theme={null}
  async get(key: string): Promise<MemoryGetResponse>
  ```
</CodeGroup>

**Parameters:**

* `key` (string): The key to retrieve

**Response:**

* `success` (boolean): Whether the operation succeeded
* `data.key` (string): The requested key (on success)
* `data.value` (string): The stored value (on success)
* `error` (string | null): Error message if key not found

**Example:**

<CodeGroup>
  ```python Python theme={null}
  result = agent.memory.get("lastSwapNetwork")
  if result.success and result.data:
      agent.log(f"Network: {result.data.value}")
  else:
      agent.log(f"Key not found: {result.error}")
  ```

  ```typescript TypeScript theme={null}
  const result = await agent.memory.get("lastSwapNetwork");
  if (result.success && result.data) {
    await agent.log(`Network: ${result.data.value}`);
  } else {
    await agent.log(`Key not found: ${result.error}`);
  }
  ```
</CodeGroup>

### Delete Value

Remove a key-value pair.

<CodeGroup>
  ```python Python theme={null}
  def delete(key: str) -> MemoryDeleteResponse
  ```

  ```typescript TypeScript theme={null}
  async delete(key: string): Promise<MemoryDeleteResponse>
  ```
</CodeGroup>

**Parameters:**

* `key` (string): The key to delete

**Response:**

* `success` (boolean): Whether the operation succeeded
* `data.key` (string): The deleted key (on success)
* `error` (string | null): Error message (on failure)

**Note:** Succeeds even if the key doesn't exist.

**Example:**

<CodeGroup>
  ```python Python theme={null}
  result = agent.memory.delete("tempSwapQuote")
  if result.success and result.data:
      agent.log(f"Deleted: {result.data.key}")
  ```

  ```typescript TypeScript theme={null}
  const result = await agent.memory.delete("tempSwapQuote");
  if (result.success && result.data) {
    await agent.log(`Deleted: ${result.data.key}`);
  }
  ```
</CodeGroup>

### List Session Memory Keys

List all keys in session memory.

<CodeGroup>
  ```python Python theme={null}
  def list() -> MemoryListResponse
  ```

  ```typescript TypeScript theme={null}
  async list(): Promise<MemoryListResponse>
  ```
</CodeGroup>

**Response:**

* `success` (boolean): Whether the operation succeeded
* `data.keys` (string\[]): Array of all stored keys (on success)
* `data.count` (number): Number of keys (on success)
* `error` (string | null): Error message (on failure)

**Example:**

<CodeGroup>
  ```python Python theme={null}
  result = agent.memory.list()
  if result.success and result.data:
      agent.log(f"Found {result.data.count} keys:")
      for key in result.data.keys:
          agent.log(f"  - {key}")
  ```

  ```typescript TypeScript theme={null}
  const result = await agent.memory.list();
  if (result.success && result.data) {
    await agent.log(`Found ${result.data.count} keys:`);
    for (const key of result.data.keys) {
      await agent.log(`  - ${key}`);
    }
  }
  ```
</CodeGroup>

### Notes

* Values must be strings. Serialize complex data (JSON, numbers) before storing.
* Keys must be 1-255 characters.
* Keys are automatically scoped to the current agent session.
* Memory persists across execution cycles within the same session.
* Storage is cleared when the session ends.
* `delete()` is idempotent — it succeeds even if the key does not exist.
* Memory is backed by object storage (R2). Reads and writes have low but non-zero latency — avoid calling memory methods in tight loops.
* For tracking position changes within an execution cycle, memory is often more reliable than polling `getCurrentPositions()`. See [Positions](./positions) for details.

### See Also

* [Positions](./positions) — Use memory to track position deltas instead of polling
* [Execution Model](../concepts/execution-model) — How the run loop and session lifecycle work


# Polymarket
Source: https://docs.circuit.org/agent-developers/sdk-reference/polymarket

Trade prediction markets on Polygon.

Use the Polymarket integration to build agents that buy and sell shares in prediction markets. Common use cases include event-driven trading, portfolio hedging, and automated redemption of settled positions.

### Market Order

Execute a buy or sell market order.

<CodeGroup>
  ```python Python theme={null}
  def market_order(request: PolymarketMarketOrderRequest | dict) -> PolymarketMarketOrderResponse
  ```

  ```typescript TypeScript theme={null}
  async marketOrder(request: PolymarketMarketOrderRequest): Promise<PolymarketMarketOrderResponse>
  ```
</CodeGroup>

**Request Parameters:**

* `tokenId` (string): Market token ID for the position
* `size` (number): Order size (meaning differs by side)
* `side` (string): "BUY" or "SELL"
* `expiresAt` (string | null, optional): ISO 8601 timestamp. In manual mode, the suggestion expires at this time. If omitted, no time-based expiry is set (suggestions are auto-cleared at each `run` start).
* `waitForConfirmation` (boolean, optional): If `true` (default), the SDK polls for transaction receipts after the order executes and returns `success: false` if any transaction reverted onchain. Set to `false` to skip receipt polling.

**Size Parameter:**

* **BUY**: `size` is the USD amount to spend (e.g., `10` = \$10 worth of shares)
* **SELL**: `size` is the number of shares to sell (e.g., `10` = 10 shares)

**Response:**

* `success` (boolean): Whether the operation succeeded
* `data.orderInfo` (object): Order information (on success)
  * `orderId` (string): Unique order identifier
  * `side` (string): "BUY" or "SELL"
  * `size` (string): Order size
  * `priceUsd` (string): Price per share in USD
  * `totalPriceUsd` (string): Total order value in USD
  * `txHashes` (string\[]): Transaction hashes
* `error` (string | null): Error message (on failure)

**Example:**

<CodeGroup>
  ```python Python theme={null}
  # BUY order - size is USD amount to spend
  # tokenId comes from Polymarket's API for the specific outcome you want to trade
  token_id = "71321045679252212594626385532706912750332728571942532289631379312455583992563"

  buy_result = agent.platforms.polymarket.market_order({
      "tokenId": token_id,
      "size": 10,  # Spend $10 to buy shares
      "side": "BUY"
  })

  if buy_result.success and buy_result.data:
      agent.log(f"Order ID: {buy_result.data.orderInfo.orderId}")
      agent.log(f"Total Price: ${buy_result.data.orderInfo.totalPriceUsd}")
      agent.log(f"Price per share: ${buy_result.data.orderInfo.priceUsd}")

  # SELL order - size is number of shares to sell
  sell_result = agent.platforms.polymarket.market_order({
      "tokenId": token_id,
      "size": 5,  # Sell 5 shares
      "side": "SELL"
  })

  if sell_result.success and sell_result.data:
      agent.log(f"Sold {sell_result.data.orderInfo.size} shares")
      agent.log(f"Received: ${sell_result.data.orderInfo.totalPriceUsd}")
  ```

  ```typescript TypeScript theme={null}
  // BUY order - size is USD amount to spend
  // tokenId comes from Polymarket's API for the specific outcome you want to trade
  const tokenId = "71321045679252212594626385532706912750332728571942532289631379312455583992563";

  const buyResult = await agent.platforms.polymarket.marketOrder({
    tokenId,
    size: 10, // Spend $10 to buy shares
    side: "BUY"
  });

  if (buyResult.success && buyResult.data) {
    await agent.log(`Order ID: ${buyResult.data.orderInfo.orderId}`);
    await agent.log(`Total Price: $${buyResult.data.orderInfo.totalPriceUsd}`);
    await agent.log(`Price per share: $${buyResult.data.orderInfo.priceUsd}`);
  }

  // SELL order - size is number of shares to sell
  const sellResult = await agent.platforms.polymarket.marketOrder({
    tokenId,
    size: 5, // Sell 5 shares
    side: "SELL"
  });

  if (sellResult.success && sellResult.data) {
    await agent.log(`Sold ${sellResult.data.orderInfo.size} shares`);
    await agent.log(`Received: $${sellResult.data.orderInfo.totalPriceUsd}`);
  }
  ```
</CodeGroup>

### Redeem Positions

Redeem settled positions and claim winnings.

<CodeGroup>
  ```python Python theme={null}
  def redeem_positions(request: PolymarketRedeemPositionsRequest | None = None) -> PolymarketRedeemPositionsResponse
  ```

  ```typescript TypeScript theme={null}
  async redeemPositions(request?: PolymarketRedeemPositionsRequest): Promise<PolymarketRedeemPositionsResponse>
  ```
</CodeGroup>

**Request Parameters (optional):**

* `tokenIds` (string\[], optional): Specific token IDs to redeem. Omit or pass empty array to redeem all redeemable positions.
* `waitForConfirmation` (boolean, optional): If `true` (default), the SDK polls for transaction receipts after redemption and returns `success: false` if any transaction reverted onchain. Set to `false` to skip receipt polling.

**Response:**

* `success` (boolean): Whether the operation succeeded
* `data` (array): Array of redemption results
  * `success` (boolean): Whether this redemption succeeded
  * `position` (object | null): Position details (on success)
    * `question` (string): Market question text
    * `outcome` (string): Outcome name (e.g., "Yes", "No")
    * `valueUsd` (string): Position value in USD
    * `pnlUsd` (string): Profit/loss in USD
    * `pnlPercent` (string): Profit/loss percentage
    * `isRedeemable` (boolean): Whether position can be redeemed
    * `contractAddress` (string): Token contract address
    * `tokenId` (string | null): Token ID
    * `decimals` (number): Token decimals
    * `conditionId` (string): Market condition ID
    * `formattedShares` (string): Human-readable share count
    * `shares` (string): Raw share count
    * `averagePriceUsd` (string): Average entry price
    * `initialValue` (string): Original position value
    * `pnlRealizedUsd` (string): Realized PnL in USD
    * `pnlRealizedPercent` (string): Realized PnL percentage
    * `isNegativeRisk` (boolean): Whether this is a negative risk market
    * `imageUrl` (string): Market image URL
    * `endDate` (string): Market end date
  * `transactionHash` (string | null): Transaction hash (on success)
* `error` (string | null): Error message (on failure)

**Example:**

<CodeGroup>
  ```python Python theme={null}
  # Redeem all redeemable positions
  redemption = agent.platforms.polymarket.redeem_positions()

  if redemption.success and redemption.data:
      successful = [r for r in redemption.data if r.success]
      agent.log(f"Redeemed {len(successful)} positions")

      for tx in redemption.data:
          if tx.success and tx.position:
              agent.log(f"Redeemed: {tx.position.question} ({tx.position.outcome})")
              agent.log(f"Value: ${tx.position.valueUsd}")
              agent.log(f"PnL: ${tx.position.pnlUsd} ({tx.position.pnlPercent}%)")
              agent.log(f"Tx: {tx.transactionHash}")

  # Redeem specific positions by tokenId
  specific_result = agent.platforms.polymarket.redeem_positions({
      "tokenIds": [
          "71321045679252212594626385532706912750332728571942532289631379312455583992563",
          "52114319501245915516055106046884209969926127482827954674443846427813813222426"
      ]
  })
  ```

  ```typescript TypeScript theme={null}
  // Redeem all redeemable positions
  const redemption = await agent.platforms.polymarket.redeemPositions();

  if (redemption.success && redemption.data) {
    const successful = redemption.data.filter(r => r.success);
    await agent.log(`Redeemed ${successful.length} positions`);

    for (const tx of redemption.data) {
      if (tx.success && tx.position) {
        await agent.log(`Redeemed: ${tx.position.question} (${tx.position.outcome})`);
        await agent.log(`Value: $${tx.position.valueUsd}`);
        await agent.log(`PnL: $${tx.position.pnlUsd} (${tx.position.pnlPercent}%)`);
        await agent.log(`Tx: ${tx.transactionHash}`);
      }
    }
  }

  // Redeem specific positions by tokenId
  const specificResult = await agent.platforms.polymarket.redeemPositions({
    tokenIds: [
      "71321045679252212594626385532706912750332728571942532289631379312455583992563",
      "52114319501245915516055106046884209969926127482827954674443846427813813222426"
    ]
  });
  ```
</CodeGroup>

### Common Errors

Errors are returned from Polymarket's API in the `error` field. Common errors include:

| Error                                            | Cause                                   | Solution                                |
| ------------------------------------------------ | --------------------------------------- | --------------------------------------- |
| "Insufficient balance"                           | Not enough USDC for BUY order           | Check currentPositions for USDC balance |
| "No orderbook exists for the requested token id" | Invalid tokenId or market doesn't exist | Verify tokenId from Polymarket API      |

Note: Additional error messages may be returned by Polymarket's API. Check the `error` field in the response for specific details.

### Getting Token IDs

The `tokenId` identifies a specific outcome (e.g., "Yes" or "No") in a Polymarket market. You can find token IDs through:

* **Polymarket's CLOB API**: `GET https://clob.polymarket.com/markets` returns all markets with their `tokens` array, each containing a `token_id` and `outcome`.
* **From positions**: If you already hold shares, `getCurrentPositions()` returns Polymarket positions with token IDs in the position data.

### Notes

* Polymarket's API accepts different decimal precision for buys and sells. This can result in dust positions if selling a position before expiry. Clean up dust with `redeemPositions()` after market expiry.
* **Negative risk markets**: Some markets use an inverted pricing model. The SDK handles this transparently, but be aware that position values may display differently.
* Position data is available via `agent.currentPositions` and `agent.getCurrentPositions()`.
* Polymarket positions include enriched metadata (question, outcome, PNL) when retrieved via `getCurrentPositions()`.

### See Also

* [Polymarket Agent Example](../examples/polymarket-agent) — Full working prediction market agent
* [Positions](./positions) — Polymarket positions include enriched metadata via `getCurrentPositions()`
* [Error Handling](./error-handling#polymarket-error-codes) — Polymarket-specific error codes


# Positions
Source: https://docs.circuit.org/agent-developers/sdk-reference/positions

Manage assets and balances allocated to your agent.

Use positions to check what assets are available to your agent and verify balances after transactions. Most agents read `currentPositions` at the start of each `run` to decide what to do.

### Current Positions

`agent.currentPositions` contains assets allocated at the start of execution. Each position includes:

* `network` (string): Network identifier (e.g., "ethereum:137")
* `assetAddress` (string): Token contract address
* `tokenId` (string | null): Token ID for NFTs/ERC1155 (null for fungible tokens)
* `avgUnitCost` (string): Average unit cost in USD. Currently returns `"0"` — cost basis tracking will be enabled in a future release.
* `currentQty` (string): Current quantity held (raw amount)

**Note:** `currentPositions` reflects balances at execution start. After transactions, use `getCurrentPositions()` for updated balances.

### Get Current Positions

Get live positions with updated balances. Indexing speed varies by chain, so updated positions may not appear immediately after transactions are submitted. For agents that need position updates under 5-10 seconds, it is recommended to track position changes in memory instead.

<CodeGroup>
  ```python Python theme={null}
  def get_current_positions() -> CurrentPositionsResponse
  ```

  ```typescript TypeScript theme={null}
  async getCurrentPositions(): Promise<CurrentPositionsResponse>
  ```
</CodeGroup>

**Response:**

* `success` (boolean): Whether the operation succeeded
* `data.hasPendingTxs` (boolean): Whether there are pending transactions
* `data.positions` (array): Array of current positions
* `error` (string | null): Error message (on failure)

**Position Fields:**

* `network` (string): Network identifier
* `assetAddress` (string): Token contract address
* `tokenId` (string | null): Token ID for NFTs/ERC1155
* `avgUnitCost` (string): Average unit cost in USD
* `currentQty` (string): Current quantity held (raw amount)
* `polymarketMetadata` (object | null): Enriched Polymarket position data (if applicable)
  * `question` (string): Market question text
  * `outcome` (string): Outcome name (e.g., "Yes", "No")
  * `valueUsd` (string): Position value in USD
  * `priceUsd` (string): Current price per share
  * `averagePriceUsd` (string): Average entry price
  * `pnlUsd` (string): Profit/loss in USD
  * `pnlPercent` (string): Profit/loss percentage
  * `pnlRealizedUsd` (string): Realized PnL in USD
  * `pnlRealizedPercent` (string): Realized PnL percentage
  * `isRedeemable` (boolean): Whether position can be redeemed
  * `isNegativeRisk` (boolean): Whether this is a negative risk market
  * `imageUrl` (string): Market image URL
  * `endDate` (string): Market end date
  * `contractAddress` (string): Polymarket contract address
  * `tokenId` (string | null): Outcome token ID
  * `decimals` (number): Token decimals
  * `conditionId` (string): Market condition ID
  * `formattedShares` (string): Human-readable share count
  * `shares` (string): Raw share count
  * `initialValue` (string): Initial position value

**Example:**

<CodeGroup>
  ```python Python theme={null}
  result = agent.get_current_positions()
  if result.success and result.data:
      if result.data.hasPendingTxs:
          agent.log("Warning: Pending transactions may affect balances")

      for position in result.data.positions:
          agent.log(f"Position: {position.assetAddress}")
          agent.log(f"  Quantity: {position.currentQty}")
          agent.log(f"  Avg Cost: ${position.avgUnitCost}")

          if position.polymarketMetadata:
              pm = position.polymarketMetadata
              agent.log(f"  Market: {pm.question}")
              agent.log(f"  Outcome: {pm.outcome}")
              agent.log(f"  Value: ${pm.valueUsd}")
              agent.log(f"  PNL: ${pm.pnlUsd} ({pm.pnlPercent}%)")
  ```

  ```typescript TypeScript theme={null}
  const result = await agent.getCurrentPositions();
  if (result.success && result.data) {
    if (result.data.hasPendingTxs) {
      await agent.log("Warning: Pending transactions may affect balances");
    }

    for (const position of result.data.positions) {
      await agent.log(`Position: ${position.assetAddress}`);
      await agent.log(`  Quantity: ${position.currentQty}`);
      await agent.log(`  Avg Cost: $${position.avgUnitCost}`);

      if (position.polymarketMetadata) {
        const pm = position.polymarketMetadata;
        await agent.log(`  Market: ${pm.question}`);
        await agent.log(`  Outcome: ${pm.outcome}`);
        await agent.log(`  Value: $${pm.valueUsd}`);
        await agent.log(`  PNL: $${pm.pnlUsd} (${pm.pnlPercent}%)`);
      }
    }
  }
  ```
</CodeGroup>

### Handling Pending Transactions

If `hasPendingTxs` is `true`, wait until it's `false` before relying on balances, as this indicates not all transactions have been indexed. Indexing speed varies by chain. For critical time-sensitive logic, track position changes in memory instead:

<CodeGroup>
  ```python Python theme={null}
  import time

  retry_count = 0
  max_retries = 10

  while retry_count < max_retries:
      positions = agent.get_current_positions()
      if positions.success and positions.data:
          if positions.data.hasPendingTxs:
              agent.log("Pending transactions detected, retrying...", debug=True)
              retry_count += 1
              time.sleep(1)
          else:
              break
  ```

  ```typescript TypeScript theme={null}
  let retryCount = 0;
  const maxRetries = 10;

  while (retryCount < maxRetries) {
    const positions = await agent.getCurrentPositions();
    if (positions.success && positions.data) {
      if (positions.data.hasPendingTxs) {
        await agent.log("Pending transactions detected, retrying...", { debug: true });
        retryCount++;
        await new Promise(resolve => setTimeout(resolve, 1000));
      } else {
        break;
      }
    }
  }
  ```
</CodeGroup>

### Notes

* `currentPositions` is provided at execution start. Use `getCurrentPositions()` for live balances.
* Quantities are strings to preserve precision for large numbers.
* Polymarket positions include enriched metadata (question, outcome, PNL, etc.).
* Check `hasPendingTxs` before relying on balance data after transactions.
* For tracking position changes within an execution cycle, consider using [Memory](./memory) to store deltas instead of polling `getCurrentPositions()` repeatedly.

### See Also

* [Wallets & Asset Allocation](../concepts/wallets-and-allocations) — How assets are allocated to sessions
* [Memory](./memory) — Track position deltas without polling
* [Hyperliquid](./hyperliquid#asset-allocation-notes) — Hyperliquid agents use platform-specific balance methods instead


# Quick Reference
Source: https://docs.circuit.org/agent-developers/sdk-reference/quick-reference

Network identifiers, native tokens, amounts, conventions, and all SDK methods at a glance with TypeScript and Python signatures.

### Network Identifiers

All methods use consistent network identifiers:

* **EVM networks**: `"ethereum:{chainId}"`
* **Solana**: `"solana"`
* **Hyperliquid Perps**: `"hypercore:perp"`
* **Hyperliquid Spot**: `"hypercore:spot"`

#### Supported EVM Chains

| Network ID          | Chain             |
| ------------------- | ----------------- |
| `ethereum:1`        | Ethereum Mainnet  |
| `ethereum:10`       | Optimism          |
| `ethereum:56`       | BNB Smart Chain   |
| `ethereum:100`      | Gnosis            |
| `ethereum:137`      | Polygon           |
| `ethereum:146`      | Sonic             |
| `ethereum:8453`     | Base              |
| `ethereum:42161`    | Arbitrum One      |
| `ethereum:43114`    | Avalanche         |
| `ethereum:59144`    | Linea             |
| `ethereum:11155111` | Sepolia (testnet) |

***

### Native Tokens

Native tokens are handled slightly differently depending on the surface:

* **In some SDK methods** (e.g., Swap quoting/executing), you **omit** `fromToken` / `toToken` for native tokens.
* **In config and position data**, native assets are represented by a canonical "null address" per network.

#### Common Native Tokens

| Network          | Token                | Address                                                                           |
| ---------------- | -------------------- | --------------------------------------------------------------------------------- |
| `ethereum:1`     | ETH                  | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`                                      |
| `ethereum:10`    | ETH                  | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`                                      |
| `ethereum:56`    | BNB                  | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`                                      |
| `ethereum:100`   | xDAI                 | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`                                      |
| `ethereum:137`   | POL (formerly MATIC) | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`                                      |
| `ethereum:146`   | S                    | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`                                      |
| `ethereum:8453`  | ETH                  | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`                                      |
| `ethereum:42161` | ETH                  | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`                                      |
| `ethereum:43114` | AVAX                 | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`                                      |
| `ethereum:59144` | ETH                  | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`                                      |
| `solana`         | SOL                  | `11111111111111111111111111111111`                                                |
| `hypercore:perp` | USDC (Perps)         | `USDC` (startingAsset) / `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` (positions) |

**Note:** EVM native tokens use the EIP-7528 canonical address (`0xeeee...eeee`). Position data from `currentPositions` / `getCurrentPositions()` uses these addresses. Some SDK methods (e.g., swap quoting) let you omit the token address for native tokens instead.

***

### Amounts and Units

* Amounts are typically **strings** and in the **smallest unit** for the given network
  * wei (EVM), lamports (Solana), etc.
  * **Hyperliquid Exception**: When placing orders or fetching data from Hyperliquid's API, amounts will be formatted (e.g. \$1.5 USDC would be "1.5"). You will also need to consider Hyperliquid's restrictions on [tick and lot sizing](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size) when placing orders.
* Keep them as strings to preserve precision for large values.

***

### Agent Context Properties

| Property               | Type               | Description                         |
| ---------------------- | ------------------ | ----------------------------------- |
| `sessionId`            | number             | Unique session identifier           |
| `sessionWalletAddress` | string             | Wallet address for this session     |
| `currentPositions`     | CurrentPosition\[] | Assets allocated at execution start |
| `executionMode`        | string             | `"auto"` or `"manual"`              |

### Core Methods

| Method (TS)                    | Method (Python)                          | Description                                                                      |
| ------------------------------ | ---------------------------------------- | -------------------------------------------------------------------------------- |
| `log(message, options?)`       | `log(message, error=False, debug=False)` | Send log messages. `error: true` for error logs, `debug: true` for console-only. |
| `getCurrentPositions()`        | `get_current_positions()`                | Get live positions with pending tx status                                        |
| `transactions()`               | `transactions()`                         | Get transaction history for the session                                          |
| `clearSuggestedTransactions()` | `clear_suggested_transactions()`         | Clear pending manual mode suggestions                                            |

### Memory

| Method (TS)              | Method (Python)          | Description                                      |
| ------------------------ | ------------------------ | ------------------------------------------------ |
| `memory.set(key, value)` | `memory.set(key, value)` | Store a string value                             |
| `memory.get(key)`        | `memory.get(key)`        | Retrieve a value (returns `{ value }` in `data`) |
| `memory.delete(key)`     | `memory.delete(key)`     | Delete a key                                     |
| `memory.list()`          | `memory.list()`          | List all keys                                    |

### Swap and Bridge (`agent.swidge`)

| Method (TS)                 | Method (Python)              | Description                          |
| --------------------------- | ---------------------------- | ------------------------------------ |
| `swidge.quote(request)`     | `swidge.quote(request)`      | Get swap/bridge quote with routing   |
| `swidge.execute(quoteData)` | `swidge.execute(quote_data)` | Execute a quote (or array of quotes) |

**Quote request fields**: `from`, `to`, `amount`, `fromToken?`, `toToken?`, `slippage?`

**Execute fields**: `quoteData`, `waitForConfirmation?`, `expiresAt?`

### Custom Transactions

| Method (TS)            | Method (Python)          | Description                            |
| ---------------------- | ------------------------ | -------------------------------------- |
| `signAndSend(request)` | `sign_and_send(request)` | Sign and broadcast a transaction       |
| `signMessage(request)` | `sign_message(request)`  | Sign a message (EVM only, EIP-191/712) |

**signAndSend fields (EVM)**: `network`, `request.toAddress`, `request.data`, `request.value`, `request.gas?`, `request.maxFeePerGas?`, `request.maxPriorityFeePerGas?`, `request.enforceTransactionSuccess?`, `message?`, `expiresAt?`, `waitForConfirmation?`

**signAndSend fields (Solana)**: `network`, `request.hexTransaction`, `message?`, `expiresAt?`

### Hyperliquid (`agent.platforms.hyperliquid`)

| Method (TS)                    | Method (Python)                  | Description                             |
| ------------------------------ | -------------------------------- | --------------------------------------- |
| `placeOrder(request)`          | `place_order(request)`           | Place a perp or spot order              |
| `balances()`                   | `balances()`                     | Get perp account value + spot balances  |
| `positions()`                  | `positions()`                    | Get open perpetual positions            |
| `order(orderId)`               | `order(order_id)`                | Get order info by ID                    |
| `deleteOrder(orderId, symbol)` | `delete_order(order_id, symbol)` | Cancel an order                         |
| `openOrders()`                 | `open_orders()`                  | Get all open orders                     |
| `orders()`                     | `orders()`                       | Get historical orders                   |
| `orderFills()`                 | `order_fills()`                  | Get fill history                        |
| `transfer(request)`            | `transfer(request)`              | Transfer between spot and perp accounts |
| `liquidations(startTime?)`     | `liquidations(start_time?)`      | Get liquidation events                  |

**placeOrder fields**: `symbol`, `side`, `size`, `price`, `market`, `type?`, `triggerPrice?`, `reduceOnly?`, `postOnly?`, `expiresAt?`

**Symbols**: Perps use `"BTC"`, spot uses `"BTC/USDC"`.

### Polymarket (`agent.platforms.polymarket`)

| Method (TS)                 | Method (Python)              | Description                          |
| --------------------------- | ---------------------------- | ------------------------------------ |
| `marketOrder(request)`      | `market_order(request)`      | Buy or sell prediction market shares |
| `redeemPositions(request?)` | `redeem_positions(request?)` | Redeem settled positions             |

**marketOrder fields**: `tokenId`, `size`, `side`, `expiresAt?`, `waitForConfirmation?`

**redeemPositions fields**: `tokenIds?`, `waitForConfirmation?`

**Size meaning**: BUY = USD to spend, SELL = shares to sell.

### Common Transaction Parameters

`expiresAt` is accepted by all transactional methods. `waitForConfirmation` is accepted by `signAndSend`, `swidge.execute`, `marketOrder`, and `redeemPositions`.

| Parameter             | Type           | Description                                                                                                                          |
| --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `expiresAt`           | string \| null | ISO 8601 expiry for suggestions in manual mode. If omitted, no time-based expiry (suggestions are auto-cleared at each `run` start). |
| `waitForConfirmation` | boolean        | Polls for onchain receipt and detects reverts. Default: `true`.                                                                      |

### Response Pattern

Every method returns:

```typescript theme={null}
{
  success: boolean;
  data?: any;       // present on success
  error?: string;   // present on failure
}
```

Always check `success` before using `data`. See [Error Handling](./error-handling) for patterns.


# Suggestions
Source: https://docs.circuit.org/agent-developers/sdk-reference/suggestions

Manual mode transaction suggestions: how they work and how to control expiry.

Use suggestions when your agent supports manual mode and you need to control how long a pending transaction stays available for user approval, or clear stale suggestions mid-execution.

In **manual** mode, transactional SDK calls (`signAndSend`, `swidge.execute`, `placeOrder`, `marketOrder`, etc.) create **suggestions** instead of executing immediately. The user approves each suggestion in the Circuit UI before it's broadcast.

The response in manual mode includes:

* `suggested` (boolean): `true`
* `suggestionId` (number): Unique suggestion identifier

For a general overview of modes, see [Manual vs Auto Mode](../concepts/manual-vs-auto-mode).

### Automatic Clearing

<Warning>
  All pending suggestions are automatically soft-deleted at the beginning of each `run` execution. If you need a shorter expiry, pass an `expiresAt` timestamp when submitting the transaction.
</Warning>

### Manual Clearing

Clear pending suggestions at any point during execution:

<CodeGroup>
  ```python Python theme={null}
  def clear_suggested_transactions() -> ClearSuggestionsResponse
  ```

  ```typescript TypeScript theme={null}
  async clearSuggestedTransactions(): Promise<ClearSuggestionsResponse>
  ```
</CodeGroup>

**Response:**

* `success` (boolean): Whether the pending suggestions were cleared
* `error` (string | null): Error message if clearing failed

**Example:**

<CodeGroup>
  ```python Python theme={null}
  agent.clear_suggested_transactions()
  ```

  ```typescript TypeScript theme={null}
  await agent.clearSuggestedTransactions();
  ```
</CodeGroup>

### `expiresAt`

All transactional SDK methods accept an optional `expiresAt` parameter (ISO 8601 timestamp). If the user hasn't approved by this time, the suggestion is discarded.

<CodeGroup>
  ```python Python theme={null}
  from datetime import datetime, timedelta, timezone

  # Suggestion expires in 5 minutes
  expires = (datetime.now(timezone.utc) + timedelta(minutes=5)).isoformat()

  result = agent.sign_and_send({
      "network": "ethereum:1",
      "request": {
          "to_address": agent.sessionWalletAddress,
          "data": "0x",
          "value": "100000000000000",  # 0.0001 ETH
      },
      "expiresAt": expires
  })
  ```

  ```typescript TypeScript theme={null}
  // Suggestion expires in 5 minutes
  const fiveMinutes = new Date(Date.now() + 5 * 60 * 1000).toISOString();

  const result = await agent.signAndSend({
    network: "ethereum:1",
    request: {
      toAddress: agent.sessionWalletAddress,
      data: "0x",
      value: "100000000000000", // 0.0001 ETH
    },
    expiresAt: fiveMinutes
  });
  ```
</CodeGroup>

### Notes

* `expiresAt` is available on: `signAndSend` / `sign_and_send`, `swidge.execute`, `placeOrder` / `place_order`, `transfer`, and `marketOrder` / `market_order`.
* In `auto` mode, `expiresAt` is ignored — transactions execute immediately.
* Suggestions that expire before user approval are automatically discarded.

### See Also

* [Manual vs Auto Mode](../concepts/manual-vs-auto-mode) — Overview of execution modes and when to use each
* [Swap and Bridge](./swap-and-bridge) — `expiresAt` works on `swidge.execute()` too


# Swap and Bridge
Source: https://docs.circuit.org/agent-developers/sdk-reference/swap-and-bridge

Cross-chain token swaps and bridges using Circuit's swap engine. The engine automatically selects the best route across multiple liquidity sources.

Use swap and bridge to move tokens between chains or swap between assets on the same chain. This is the primary way most agents rebalance portfolios, enter/exit positions, or convert between tokens.

### Workflow

1. Get a quote with `quote()`
2. Execute the swap with `execute()`
3. Check `data.status` in the response

### Get Quote

Get pricing and routing information for a swap.

<CodeGroup>
  ```python Python theme={null}
  def quote(request: SwidgeQuoteRequest | dict) -> SwidgeQuoteResponse
  ```

  ```typescript TypeScript theme={null}
  async quote(request: SwidgeQuoteRequest): Promise<SwidgeQuoteResponse>
  ```
</CodeGroup>

**Request Parameters:**

* `from` (object): Source wallet `{ network, address }`
* `to` (object): Destination wallet `{ network, address }`
* `amount` (string): Amount in smallest unit (wei, lamports, etc.)
* `fromToken` (string | null, optional): Source token address (omit for native tokens)
* `toToken` (string | null, optional): Destination token address (omit for native tokens)
* `slippage` (string, optional): Slippage tolerance % as string (default: "0.5")

**Response:**

* `success` (boolean): Whether the quote was retrieved
* `data` (object): Quote data (on success)
  * `engine` (string): Routing engine used (e.g., `"lifi"`, `"relay"`, `"hypercore"`)
  * `assetSend` (object): Source asset details
    * `network` (string): Network identifier
    * `token` (string | null): Token address (`null` for native)
    * `name` (string): Token name
    * `symbol` (string): Token symbol
    * `decimals` (number): Token decimals
    * `amount` (string): Amount in smallest units
    * `amountFormatted` (string): Human-readable amount
    * `amountUsd` (string): Total value in USD
  * `assetReceive` (object): Destination asset details (same shape as `assetSend`)
  * `priceImpact` (object): Price impact info
    * `percentage` (string): Price impact as a percentage
    * `usd` (string, optional): Price impact in USD
  * `fees` (array): Fee breakdown
    * `name` (string): Fee label
    * `amount` (string, optional): Fee amount in smallest units
    * `amountFormatted` (string, optional): Human-readable fee
    * `amountUsd` (string, optional): Fee value in USD
  * `steps` (array): Transaction steps to execute
* `error` (string | null): Error message if quote failed

**Example:**

<CodeGroup>
  ```python Python theme={null}
  quote = agent.swidge.quote({
      "from": {
          "network": "ethereum:137",
          "address": agent.sessionWalletAddress,
      },
      "to": {
          "network": "ethereum:137",
          "address": agent.sessionWalletAddress,
      },
      "amount": "1000000",  # 1 USDC (6 decimals)
      "fromToken": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",  # USDC
      "toToken": "0xd93f7e271cb87c23aaa73edc008a79646d1f9912",  # wSOL
      "slippage": "10.0",
  })

  if quote.success and quote.data:
      if quote.data.assetReceive.amountFormatted:
          agent.log(f"You'll receive: {quote.data.assetReceive.amountFormatted}")
      if quote.data.priceImpact.percentage:
          agent.log(f"Price impact: {quote.data.priceImpact.percentage}%")

          # Validate price impact
          if abs(float(quote.data.priceImpact.percentage)) > 10:
              agent.log("Price impact too high", error=True)
              return
  ```

  ```typescript TypeScript theme={null}
  const quote = await agent.swidge.quote({
    from: { network: "ethereum:137", address: agent.sessionWalletAddress },
    to: { network: "ethereum:137", address: agent.sessionWalletAddress },
    amount: "1000000", // 1 USDC (6 decimals)
    fromToken: "0x2791bca1f2de4661ed88a30c99a7a9449aa84174", // USDC
    toToken: "0xd93f7e271cb87c23aaa73edc008a79646d1f9912", // wSOL
    slippage: "10.0"
  });

  if (quote.success && quote.data) {
    if (quote.data.assetReceive.amountFormatted) {
      await agent.log(`You'll receive: ${quote.data.assetReceive.amountFormatted}`);
    }
    if (quote.data.priceImpact.percentage) {
      await agent.log(`Price impact: ${quote.data.priceImpact.percentage}%`);

      // Validate price impact
      if (Math.abs(parseFloat(quote.data.priceImpact.percentage)) > 10) {
        await agent.log("Price impact too high", { error: true });
        return;
      }
    }
  }
  ```
</CodeGroup>

### Execute Quote

Execute a swap using a quote.

<CodeGroup>
  ```python Python theme={null}
  def execute(quote_data: SwidgeData | list[SwidgeData]) -> SwidgeExecuteResponse | list[SwidgeExecuteResponse]
  ```

  ```typescript TypeScript theme={null}
  async execute(quoteData: SwidgeQuoteData | SwidgeQuoteData[]): Promise<SwidgeExecuteResponse | SwidgeExecuteResponse[]>
  ```
</CodeGroup>

**Parameters:**

* `quoteData`: Complete quote object from `quote()`, or array of quotes for bulk execution
* `waitForConfirmation` (boolean, optional): If `true` (default), the SDK polls for transaction receipts on EVM chains and returns `success: false` if any transaction reverted onchain. Set to `false` to skip receipt polling.
* `expiresAt` (string | null, optional): ISO 8601 timestamp. In manual mode, the suggestion is discarded if not approved by this time. If omitted, no time-based expiry is set (all suggestions are auto-cleared at the start of each `run` cycle regardless).

**Response:**

* `success` (boolean): Whether execution started
* `data.status` (string): Execution status ("success", "failure", "refund", "delayed")
* `data.in.txs` (string\[]): Input transaction hashes (on success)
* `data.out.txs` (string\[]): Output transaction hashes (on success)
* `error` (string | null): Error message (on failure)

**Example:**

<CodeGroup>
  ```python Python theme={null}
  if quote.success and quote.data:
      result = agent.swidge.execute(quote.data)

      if result.success and result.data:
          agent.log(f"Swap status: {result.data.status}")
          if result.data.status == "success":
              agent.log("Swap completed")
              if result.data.in_ and result.data.in_.txs:
                  agent.log(f"In tx: {result.data.in_.txs[0]}")
              if result.data.out and result.data.out.txs:
                  agent.log(f"Out tx: {result.data.out.txs[0]}")
          elif result.data.status == "failure":
              agent.log("Swap failed", error=True)
      else:
          agent.log(result.error or "Execute failed", error=True)
  ```

  ```typescript TypeScript theme={null}
  if (quote.success && quote.data) {
    const result = await agent.swidge.execute(quote.data);

    if (result.success && result.data) {
      await agent.log(`Swap status: ${result.data.status}`);
      if (result.data.status === "success") {
        await agent.log("Swap completed");
        if (result.data.in?.txs?.[0]) {
          await agent.log(`In tx: ${result.data.in.txs[0]}`);
        }
        if (result.data.out?.txs?.[0]) {
          await agent.log(`Out tx: ${result.data.out.txs[0]}`);
        }
      } else if (result.data.status === "failure") {
        await agent.log("Swap failed", { error: true });
      }
    } else {
      await agent.log(result.error || "Execute failed", { error: true });
    }
  }
  ```
</CodeGroup>

### Bulk Execution

Execute multiple swaps in parallel by passing an array of quotes:

<CodeGroup>
  ```python Python theme={null}
  results = agent.swidge.execute([quote1.data, quote2.data])
  for index, result in enumerate(results):
      if result.success and result.data:
          agent.log(f"Swap {index + 1} status: {result.data.status}")
  ```

  ```typescript TypeScript theme={null}
  const results = await agent.swidge.execute([quote1.data, quote2.data]);
  for (let i = 0; i < results.length; i++) {
    if (results[i].success && results[i].data) {
      await agent.log(`Swap ${i + 1} status: ${results[i].data.status}`);
    }
  }
  ```
</CodeGroup>

### Routing Engines

Circuit queries multiple routing engines and selects the best route automatically.

| Engine  | Supported Networks                      |
| ------- | --------------------------------------- |
| `relay` | EVM chains, Solana, Hyperliquid         |
| `lifi`  | EVM chains (cross-chain and same-chain) |

### Notes

* Always validate quotes before executing. Check price impact and slippage.
* Circuit filters quotes with price impact exceeding 100%. Agents should validate returned quotes based on their own parameters.
* Amounts are in smallest units (wei for ETH, lamports for SOL, etc.).
* Omit `fromToken`/`toToken` for native tokens (ETH, SOL).
* Execution status is final for same-chain swaps. For cross-chain bridges, the `data.status` field in the execute response indicates the final status: `"success"`, `"failure"`, `"refund"`, or `"delayed"`.

### Manual Mode

In manual mode, `execute()` returns a suggestion instead of executing. The response will have `data.suggested = true` and `data.suggestionId`.

### See Also

* [Positions](./positions) — Check balances before and after swaps
* [Quick Reference](./quick-reference#network-identifiers) — Network identifiers and native token addresses
* [Error Handling](./error-handling#swap-error-codes) — Swap-specific error codes
* [Yield Agent Example](../examples/yield-agent) — Full working agent using swap

### Python: `from` Parameter

<Warning>
  `from` is a reserved keyword in Python. Use the string key `"from"` in dicts (recommended), or `from_` if using the Pydantic model directly.
</Warning>

`from` is a reserved keyword in Python. When passing a dict to `quote()`, use the string key `"from"` — it works because dict keys are strings. If using the Pydantic model directly, the field is `from_`:

```python theme={null}
# Using a dict (recommended) — "from" works as a string key
quote = agent.swidge.quote({
    "from": {"network": "ethereum:137", "address": agent.sessionWalletAddress},
    "to": {"network": "ethereum:137", "address": agent.sessionWalletAddress},
    "amount": "1000000",
})

# Using the Pydantic model — use from_ (with underscore)
from agent_sdk.types.swidge import SwidgeQuoteRequest, SwidgeWallet
quote = agent.swidge.quote(SwidgeQuoteRequest(
    from_=SwidgeWallet(network="ethereum:137", address=agent.sessionWalletAddress),
    to=SwidgeWallet(network="ethereum:137", address=agent.sessionWalletAddress),
    amount="1000000",
))
```


# Transaction History
Source: https://docs.circuit.org/agent-developers/sdk-reference/transaction-history

Get the transaction history for the agent session. These are reflected in the in/out asset changes. A swap would result in 2 records being returned in this method.

Use transaction history to audit what your agent has done during a session — for example, calculating total fees paid, verifying that a swap executed correctly, or building a trade log.

### List Transactions

Get transaction history with asset changes.

<CodeGroup>
  ```python Python theme={null}
  def transactions() -> TransactionsResponse
  ```

  ```typescript TypeScript theme={null}
  async transactions(): Promise<TransactionsResponse>
  ```
</CodeGroup>

**Response:**

* `success` (boolean): Whether the operation succeeded
* `data` (array): Array of asset changes
  * `network` (string): Network identifier
  * `transactionHash` (string): Transaction hash
  * `from` / `from_` (string): Sender address
  * `to` (string): Recipient address
  * `amount` (string): Amount transferred (string to preserve precision)
  * `token` (string | null): Token contract address (null for native tokens)
  * `tokenId` (string | null): Token ID for NFTs (null for fungible tokens)
  * `tokenType` (string): Token type ("native", "ERC20", "ERC721", etc.)
  * `tokenUsdPrice` (string | null): Token price in USD at transaction time
  * `timestamp` (string): Transaction timestamp
* `error` (string | null): Error message (on failure)

**Example:**

<CodeGroup>
  ```python Python theme={null}
  result = agent.transactions()
  if result.success and result.data:
      agent.log(f"Found {len(result.data)} asset changes")

      outgoing = [c for c in result.data if c.from_ == agent.sessionWalletAddress]
      agent.log(f"Outgoing transfers: {len(outgoing)}")
  ```

  ```typescript TypeScript theme={null}
  const result = await agent.transactions();
  if (result.success && result.data) {
    await agent.log(`Found ${result.data.length} asset changes`);

    const outgoing = result.data.filter(
      change => change.from === agent.sessionWalletAddress
    );
    await agent.log(`Outgoing transfers: ${outgoing.length}`);
  }
  ```
</CodeGroup>

### Notes

* Indexing speed varies by chain and may have a delay, so new transactions may not appear here immediately.
* Amounts are strings to preserve precision for large numbers.
* Network format: `"ethereum:{chainId}"` for EVM chains, `"solana"` for Solana, `"hypercore:perp"` and `"hypercore:spot"` for Hyperliquid.
* The sender field is `from` in TypeScript and `from_` in Python (since `from` is a reserved keyword).
* `tokenType` values: `"native"`, `"ERC20"`, `"ERC721"`, `"ERC1155"`, `"SPL"`.
* `tokenUsdPrice` may be `null` if the price was not available at indexing time.

### See Also

* [Positions](./positions) — Check current balances instead of inferring from history
* [Swap and Bridge](./swap-and-bridge) — Execute swaps that generate transaction records
* [Error Handling](./error-handling) — Handle failures in transacting methods that generate history


# Troubleshooting
Source: https://docs.circuit.org/agent-developers/troubleshooting

Common issues, gotchas, and solutions when building and testing Circuit agents.

### CLI Issues

**`circuit: command not found`**

The CLI is not installed globally. Install with:

```bash theme={null}
bun install -g @circuitorg/agent-cli
```

**`circuit run` fails with "No wallet found"**

Import a wallet first:

```bash theme={null}
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 .`

***

### SDK Issues

**`result.data` is undefined**

Always check `success` before accessing `data`:

```typescript theme={null}
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:

```typescript theme={null}
// 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:

```typescript theme={null}
// 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:

```python theme={null}
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()**

See [Swap and Bridge: Python `from` Parameter](./sdk-reference/swap-and-bridge#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:

```python theme={null}
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


# Get Started
Source: https://docs.circuit.org/agent-users/get-started

Create an account, set up wallets, and start using Circuit.

Circuit is available at [app.circuit.org](https://app.circuit.org/). You can use it directly from your browser, or add it to your home screen for a mobile-app-like experience:

* **iOS**: Open `app.circuit.org` in Safari, tap Share, then Add to Home Screen.
* **Android**: Open `app.circuit.org` in Chrome, tap **⋮**, then Add to Home Screen.

### Create an account

Circuit uses passkeys instead of passwords — no phishing, faster auth, nothing to memorize. Your device handles everything. Using a password manager is recommended (iCloud Keychain, 1Password, Google Password Manager) for cross-device compatibility.

You can add multiple passkeys in Settings for backup, or rotate them by adding a new one and deleting the old.

### Set up your wallets

Agents need a wallet to run on. You can create a new one (provisioned by Circuit) or import an existing wallet by private key.

<Note>
  Agents never have access to your private keys. Agent code runs in a sandboxed environment completely separate from the secure signing enclave. You can export your wallet at any time from the wallet management menu.
</Note>


# Running Agents
Source: https://docs.circuit.org/agent-users/running-agents

Browse, start, manage, and unwind agents on your wallets.

### Browse agents

Explore the agent library once your wallet is ready:

* **First-party agents** — Built and maintained by the Circuit team
* **Third-party agents** — Created by independent developers, reviewed by Circuit

Each agent includes a description covering its strategy, supported networks, and risk profile. You can also compare agents by their historical ROI, TVL, and live onchain transactions.

Circuit agents work across Ethereum, Solana, Base, Hyperliquid, Polymarket, and more.

### Start an agent

Pick an agent and select a wallet to run it on. It starts thinking and transacting immediately.

Some agents require a dedicated wallet, others can run alongside other agents on the same wallet. Each agent's description tells you which kind it is.

Agents continue running in the background until you unwind them.

### Manage and unwind

You stay in control through the Circuit dashboard:

* **Active agents** — See which agents are running and on which wallets
* **Pause** — Temporarily stop an agent from executing. The session stays open and your allocations remain in place, but `run` cycles are skipped until you resume.
* **Resume** — Restart a paused agent. Execution picks up on the next scheduled interval.
* **Unwind** — Stop an agent and revoke it from your wallet
* **Activity** — Review what the agent analyzed, suggested, and transacted onchain
* **Multi-wallet** — Run one agent per wallet, multiple agents on one wallet, or any combination


# Wallets & Security
Source: https://docs.circuit.org/agent-users/wallets-and-security

Export wallets, understand safety policies, and manage your keys.

### Export your wallet

You can export your wallet's private key at any time. From the wallet management screen:

1. Tap the **⋯** (three-dot menu) on the wallet you want to export
2. Select **Export Private Key**
3. Authenticate with your passkey when prompted
4. Your private key is displayed — copy it and store it somewhere safe

<Warning>
  Anyone with your private key has full control of that wallet. Never share it, and store it securely.
</Warning>

### Safety

Every agent runs inside Circuit's infrastructure, and every transaction passes through automatic safety checks:

* **Global rules** prevent invalid or malicious actions. These rules are maintained by Circuit and apply to every agent.
* **Personal policies** enforce your own limits on spend amounts, chains, protocols, and assets

If an agent violates either, the transaction is blocked and never signed.


# Agents
Source: https://docs.circuit.org/integrating-circuit-agents-in-your-app-wallet/api/agents

Base URL: https://api.circuit.org/v1

### List Available Agents

Get all agents available to the user.

**Endpoint:** `GET /agents`

**Request**

| Header                          | Description                                       |
| ------------------------------- | ------------------------------------------------- |
| `Authorization: Bearer {token}` | User's session token acquired from authentication |

**cURL Example**

```bash theme={null}
curl -X GET "https://api.circuit.org/v1/agents"    -H "Authorization: Bearer user_session_token"
```

**Response**

<Tabs>
  <Tab title="200">
    Returns Agents

    ```typescript theme={null}
    Array<{
      id: number;
      name: string;
      description: string | null;
      createdAt: string;
      updatedAt: string;
      createdBy: {
        id: number;
        username: string;
      };
      imageUrl: string | null;
      category: string;
      shortDescription: string | null;
      allowedWalletTypes: string[];
      allowedExecutionModes: ("manual" | "auto")[];
      totalSessions: number;
      userSessions: number;
      totalRuns: number;
      totalTransactions: number;
      networks: string[];
      tokensTraded: Array<{
        network: string;
        type: string;
        address: string | null;
        tokenId: string | null;
        imageUrl: string | null;
      }>;
      tvlUsd: number;
      volumeUsd: number;
      roi7dPercent: number | null;
      roi30dPercent: number | null;
      roi1yrPercent: number | null;
      roiInceptionPercent: number | null;
    }>
    ```

    Empty Agents

    ```typescript theme={null}
    []
    ```
  </Tab>

  <Tab title="401">
    Unauthorized

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>

  <Tab title="500">
    Internal Server Error

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>
</Tabs>

### Get Agent Details

Retrieve detailed information about a specific agent.

**Endpoint:** `GET /agents/:id`

**Request**

| Header                          | Description                                       |
| ------------------------------- | ------------------------------------------------- |
| `Authorization: Bearer {token}` | User's session token acquired from authentication |

| Path Parameter | Description                                                               |
| -------------- | ------------------------------------------------------------------------- |
| `id`           | An agent ID from [`GET /agents`](./agents#list-available-agents) response |

**cURL Example**

```bash theme={null}
curl -X GET "https://api.circuit.org/v1/agents/1"    -H "Authorization: Bearer user_session_token"
```

**Response**

<Tabs>
  <Tab title="200">
    Agent Details

    ```typescript theme={null}
    {
      id: number;
      name: string;
      description: string | null;
      createdAt: string;
      updatedAt: string;
      createdBy: {
        id: number;
        username: string;
      };
      imageUrl: string | null;
      shortDescription: string | null;
      allowedWalletTypes: string[];
      allowedExecutionModes: ("manual" | "auto")[];
      defaultSleepIntervalMinutes: number;
      agentVersion: string | null;
      sdkVersion: string | null;
      totalSessions: number;
      totalRuns: number;
      distinctUsers: number;
      totalTransactions: number;
      networks: string[];
      tokensTraded: Array<{
        network: string;
        type: string;
        address: string | null;
        tokenId: string | null;
        imageUrl: string | null;
      }>;
      tvlUsd: number;
      volumeUsd: number;
      roi7dPercent: number | null;
      roi30dPercent: number | null;
      roi1yrPercent: number | null;
      roiInceptionPercent: number | null;
    }
    ```
  </Tab>

  <Tab title="400">
    Invalid Agent ID

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>

  <Tab title="401">
    Unauthorized

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>

  <Tab title="404">
    Agent Not Found

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>

  <Tab title="500">
    Internal Server Error

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>
</Tabs>

### Get Agent Historical Stats

<Warning>This REST endpoint is not currently available. Historical stats are accessible via the tRPC API. This section is provided for reference and will be updated when the REST endpoint is enabled.</Warning>

Retrieve performance statistics for an agent.

**Endpoint:** `GET /agents/:id/historical-stats`

**Request**

| Header                          | Description                                       |
| ------------------------------- | ------------------------------------------------- |
| `Authorization: Bearer {token}` | User's session token acquired from authentication |

| Path Parameter | Description                                                               |
| -------------- | ------------------------------------------------------------------------- |
| `id`           | An agent ID from [`GET /agents`](./agents#list-available-agents) response |

| Query Parameter | Description                                                      |
| --------------- | ---------------------------------------------------------------- |
| `format`        | Time format - "day", "week", "month", "year" (defaults to "day") |

**cURL Example**

```bash theme={null}
# Default format (day)
curl -X GET "https://api.circuit.org/v1/agents/1/historical-stats?format=week"    -H "Authorization: Bearer user_session_token"
```

**Response**

<Tabs>
  <Tab title="200">
    Success

    ```typescript theme={null}
    {
      id: number;
      totalPeriodWeightedRoi: number | null;
      transactions: Array<{
        timestamp: string;
        count: number;
      }>;
      roi: Array<{
        timestamp: string;
        weightedAvgHourlyReturn: number | null;
      }>;
      tvl: Array<{
        timestamp: string;
        totalTvlUsd: number;
      }>;
    }
    ```

    Format Options

    * `day`: 24 hourly data points (last 24 hours)
    * `week`: 7 daily data points (last 7 days)
    * `month`: 30 daily data points (last 30 days)
    * `year`: 365 daily data points (last 365 days)
  </Tab>

  <Tab title="400">
    Invalid Parameter

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>

  <Tab title="401">
    Unauthorized

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>

  <Tab title="404">
    Not Found

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>

  <Tab title="500">
    Internal Server Error

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>
</Tabs>

### Start Agent Session

Begin running an agent on a specific wallet.

**Endpoint:** `POST /agents/start`

**Request**

| Header                          | Description                                       |
| ------------------------------- | ------------------------------------------------- |
| `Authorization: Bearer {token}` | User's session token acquired from authentication |

| Body                       | Description                                                                  |
| -------------------------- | ---------------------------------------------------------------------------- |
| `agentId: number`          | An agent ID from [`GET /agents`](./agents#list-available-agents) response    |
| `walletId: number`         | User's Wallet ID from [`GET /wallets`](./wallets#list-user-wallets) response |
| `allocations: array`       | See below                                                                    |
| `mode: "auto" \| "manual"` | Optional execution mode. Defaults to `"auto"` if omitted.                    |

**`allocations` Object Properties**

| Property  | Type             | Required | Description                                                                                                                                                |
| --------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `network` | `string`         | true     | Network identifier (for example, `"ethereum:1"` or `"solana"`)                                                                                             |
| `address` | `string`         | true     | Token contract address. For native EVM tokens use `"0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"`; for native SOL use `"11111111111111111111111111111111"`. |
| `tokenId` | `string \| null` | false    | Token ID for NFTs of multi-token contracts. Use `null` for fungible tokens (default: `null`)                                                               |
| `amount`  | `string`         | true     | Maximum amount to allocate in smallest unit (wei for Ethereum, lamports for Solana)                                                                        |

**cURL Example**

```bash theme={null}
curl -X POST "https://api.circuit.org/v1/agents/start"    -H "Authorization: Bearer user_session_token"    -H "Content-Type: application/json"    -d '{
    "agentId": 1,
    "walletId": 456,
    "mode": "auto",
    "allocations": [
      {
        "network": "ethereum:1",
        "address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
        "tokenId": null,
        "amount": "100000000000000"
      }
    ]
  }'
```

**Response**

<Tabs>
  <Tab title="200">
    Success Start

    ```typescript theme={null}
    {
      sessionId: number;
    }
    ```
  </Tab>

  <Tab title="400">
    Bad Request

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>

  <Tab title="401">
    Unauthorized

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>

  <Tab title="404">
    Agent / Wallet Not Found

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>

  <Tab title="500">
    Internal Server Error

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>
</Tabs>

### Stop Agent Session

Stop a running agent session.

**Endpoint:** `DELETE /agents/stop/:sessionId`

**Request**

| Header                          | Description                                       |
| ------------------------------- | ------------------------------------------------- |
| `Authorization: Bearer {token}` | User's session token acquired from authentication |

| Path Parameter | Description                                                                   |
| -------------- | ----------------------------------------------------------------------------- |
| `sessionId`    | Session ID from [`POST /agents/start`](./agents#start-agent-session) response |

**cURL Example**

```bash theme={null}
curl -X DELETE "https://api.circuit.org/v1/agents/stop/789"    -H "Authorization: Bearer user_session_token"
```

**Response**

<Tabs>
  <Tab title="200">
    Success

    ```typescript theme={null}
    {
      success: boolean;
    }
    ```
  </Tab>

  <Tab title="400">
    Invalid Session ID

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>

  <Tab title="401">
    Unauthorized

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>

  <Tab title="404">
    Session Not Found

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>

  <Tab title="500">
    Internal Server Error

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>
</Tabs>

### Get Agent Logs

Retrieve execution logs for a specific agent session.

**Endpoint:** `GET /agents/logs/:sessionId`

**Request**

| Header                          | Description                                       |
| ------------------------------- | ------------------------------------------------- |
| `Authorization: Bearer {token}` | User's session token acquired from authentication |

| Path Parameter | Description                                                                   |
| -------------- | ----------------------------------------------------------------------------- |
| `sessionId`    | Session ID from [`POST /agents/start`](./agents#start-agent-session) response |

**cURL Example**

```bash theme={null}
curl -X GET "https://api.circuit.org/v1/agents/logs/789"    -H "Authorization: Bearer user_session_token"
```

**Response**

<Tabs>
  <Tab title="200">
    Returns Logs

    ```typescript theme={null}
    Array<{
      id: number;
      sessionId: number;
      type: string;
      message: string;
      createdAt: string;
    }>
    ```

    Empty Logs

    ```typescript theme={null}
    []
    ```
  </Tab>

  <Tab title="400">
    Invalid Session ID

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>

  <Tab title="401">
    Unauthorized

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>

  <Tab title="500">
    Internal Server Error

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>
</Tabs>


# API Errors
Source: https://docs.circuit.org/integrating-circuit-agents-in-your-app-wallet/api/api-errors

Standard error response format and common error messages returned by the Circuit API.

All endpoints return standard HTTP status codes and consistent error response format.

### Error Response Format

All error responses follow this structure:

```typescript theme={null}
{
  error: string;
}
```

### Typical Error Categories

| Category                  | Example Message                                 | Notes                                          |
| ------------------------- | ----------------------------------------------- | ---------------------------------------------- |
| Authentication            | `"Invalid or expired session"`                  | Token missing, invalid, or expired             |
| Authorization             | `"You are not authorized to stop this session"` | Authenticated but not allowed for the resource |
| Validation                | `"Validation failed"`                           | Request body/query/path input is invalid       |
| Not Found                 | `"Agent not found"`                             | Resource does not exist or is not visible      |
| Conflict / Business Rules | `"Wallet already exists"`                       | Request conflicts with current state           |
| Server                    | `"Internal server error"`                       | Unexpected backend error                       |


# User
Source: https://docs.circuit.org/integrating-circuit-agents-in-your-app-wallet/api/user

Base URL: https://api.circuit.org/v1

Retrieve information about the authenticated user.

**Endpoint:** `GET /user/info`

**Request**

| Header                          | Description                                       |
| ------------------------------- | ------------------------------------------------- |
| `Authorization: Bearer {token}` | User's session token acquired from authentication |

**cURL Example**

```bash theme={null}
curl -X GET "https://api.circuit.org/v1/user/info"    -H "Authorization: Bearer user_session_token"
```

**Response**

<Tabs>
  <Tab title="200">
    Success

    ```typescript theme={null}
    {
      username: string;
      email: string | null;
      isEmailVerified: boolean;
      referrerUsername: string | null;
    }
    ```
  </Tab>

  <Tab title="401">
    Unauthorized

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>

  <Tab title="404">
    No User Found

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>

  <Tab title="500">
    Internal Server Error

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>
</Tabs>


# Validation
Source: https://docs.circuit.org/integrating-circuit-agents-in-your-app-wallet/api/validation

Base URL: https://api.circuit.org/v1

Once you have obtained a session token, validate it to ensure authenticated access.

**Endpoint:** `POST /auth/validate`

**Request**

| Body            | Description                                       |
| --------------- | ------------------------------------------------- |
| `token: string` | User's session token acquired from authentication |

**cURL Example**

```bash theme={null}
curl -X POST "https://api.circuit.org/v1/auth/validate"    -H "Content-Type: application/json"    -d '{
    "token": "user_session_token"
  }'
```

**Response**

<Tabs>
  <Tab title="200">
    Valid Session

    ```typescript theme={null}
    {
      token: string;
      isValid: boolean; // true
      hasWalletSession: boolean;
      type: string;
      credentialId: string;
      username: string;
      userId: number;
      expiresAt: number;
    }
    ```

    Invalid Session

    ```typescript theme={null}
    {
      token: string;
      isValid: boolean; // false
    }
    ```
  </Tab>

  <Tab title="400">
    Validation Error

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>

  <Tab title="500">
    Internal Server Error

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>
</Tabs>


# Wallets
Source: https://docs.circuit.org/integrating-circuit-agents-in-your-app-wallet/api/wallets

Base URL: https://api.circuit.org/v1

### List User Wallets

Get all wallets associated with the authenticated user.

**Endpoint:** `GET /wallets`

**Request**

| Header                          | Description                                       |
| ------------------------------- | ------------------------------------------------- |
| `Authorization: Bearer {token}` | User's session token acquired from authentication |

**cURL Example**

```bash theme={null}
curl -X GET "https://api.circuit.org/v1/wallets"    -H "Authorization: Bearer user_session_token"
```

**Response**

<Tabs>
  <Tab title="200">
    Returns Wallets

    ```typescript theme={null}
    Array<{
      id: number;
      name: string;
      type: string;
      address: string;
      createdAt: string;
      totalUsd: string;
      networks: string[];
      agents: Array<{
        id: number;
        name: string;
        imageUrl: string | null;
      }>;
    }>
    ```

    No Wallets

    ```typescript theme={null}
    []
    ```
  </Tab>

  <Tab title="401">
    Unauthorized

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>

  <Tab title="500">
    Internal Server Error

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>
</Tabs>

### Create Wallet

Create a new wallet for the authenticated user.

**Endpoint:** `POST /wallets`

**Request**

| Header                          | Description                                       |
| ------------------------------- | ------------------------------------------------- |
| `Authorization: Bearer {token}` | User's session token acquired from authentication |

| Body           | Description                                      |
| -------------- | ------------------------------------------------ |
| `name: string` | Display name for the wallet                      |
| `type: string` | Network type of wallet; `"ethereum" \| "solana"` |

**cURL Example**

```bash theme={null}
curl -X POST "https://api.circuit.org/v1/wallets"    -H "Authorization: Bearer user_session_token"    -H "Content-Type: application/json"    -d '{
    "name": "My New Wallet",
    "type": "ethereum"
  }'
```

**Response**

<Tabs>
  <Tab title="200">
    Success Wallet Create

    ```typescript theme={null}
    {
      address: string;
      type: string;
      name: string;
    }
    ```
  </Tab>

  <Tab title="400">
    Bad Request

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>

  <Tab title="401">
    Unauthorized

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>

  <Tab title="500">
    Internal Server Error

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>
</Tabs>

### Import Wallet

Import an existing wallet using a private key.

**Endpoint:** `POST /wallets/import`

**Request**

| Header                          | Description                                       |
| ------------------------------- | ------------------------------------------------- |
| `Authorization: Bearer {token}` | User's session token acquired from authentication |

| Body                 | Description                                      |
| -------------------- | ------------------------------------------------ |
| `privateKey: string` | Private key of the wallet to be imported         |
| `name: string`       | Assign a name to this wallet                     |
| `type: string`       | Network type of wallet; `"ethereum" \| "solana"` |

**cURL Example**

```bash theme={null}
curl -X POST "https://api.circuit.org/v1/wallets/import"    -H "Authorization: Bearer user_session_token"    -H "Content-Type: application/json"    -d '{
    "privateKey": "wallet_private_key",
    "name": "My Wallet",
    "type": "ethereum"
  }'
```

**Response**

<Tabs>
  <Tab title="200">
    Success Wallet Import

    ```typescript theme={null}
    {
      address: string;
      type: string;
      name: string;
    }
    ```
  </Tab>

  <Tab title="400">
    Validation Error / Wallet Already Exists

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>

  <Tab title="401">
    Unauthorized

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>

  <Tab title="500">
    Internal Server Error

    ```typescript theme={null}
    {
      error: string;
    }
    ```
  </Tab>
</Tabs>


# Authentication
Source: https://docs.circuit.org/integrating-circuit-agents-in-your-app-wallet/authentication

Embed Circuit's passkey authentication in your app using an iframe to get session tokens for the Circuit API.

This integration embeds Circuit's authentication system directly into your app using an iframe that handles passkey authentication and returns session tokens to use with the [API](./api/agents).

### Authentication Flow

1. User sees a Circuit login interface embedded in your app
2. User authenticates using their passkey (fingerprint, face ID, etc.)
3. Circuit sends your app a session token via a secure message
4. Your app receives the token and can now call Circuit's API
5. User is logged in with no redirects or popups

The session token acts like a key that unlocks Circuit's wallet and agent API for that user.

<img alt="" />

### Implementation Guide

<Tabs>
  <Tab title="HTML/JS Example">
    ```javascript theme={null}
    <!DOCTYPE html>
    <html>
    <head>
        <title>App + Circuit</title>
    </head>
    <body>
        <h1>Welcome to App + Circuit</h1>

        <!-- Status display -->
        <div id="auth-status">Click the button below to authenticate...</div>

        <!-- Circuit authentication iframe -->
        <iframe
            id="circuit-iframe"
            src="https://app.circuit.org/embed/auth/basic"
            width="400"
            height="500"
            style="border: none; border-radius: 12px; display: block; margin: 20px auto;">
        </iframe>

        <script>
            // This will store the session token later on receipt
            let circuitSessionToken = null;

            // Listen for messages from the Circuit iframe
            window.addEventListener('message', function(event) {
                // SECURITY: Only accept messages from Circuit's domain
                if (event.origin !== 'https://app.circuit.org') return;

                const messageType = event.data.type;
                const messagePayload = event.data.payload;

                // When Circuit iframe finishes loading and is ready
                if (messageType === 'ready') {
                    document.getElementById('auth-status').textContent = 'Please authenticate';

                    // Configure the iframe
                    document.getElementById('circuit-iframe').contentWindow.postMessage({
                        type: 'configure',
                        config: {
                            backgroundColor: '#ffffff',
                            buttonColor: '#007bff',
                            buttonTextColor: '#ffffff',
                            title: 'Login to App + Circuit'
                        },
                        actionType: 'signIn',   // 'register' to register new user
                        username: 'username',   // Replace with actual username
                    }, 'https://app.circuit.org');
                }

                // Getting the session token
                if (messageType === 'signInResult' || messageType === 'registerResult') {
                    if (messagePayload.success) {
                        // SUCCESS! Get the session token
                        circuitSessionToken = messagePayload.authToken;

                        // Store it for later use
                        localStorage.setItem('circuitSessionToken', circuitSessionToken);

                        // Update the UI
                        document.getElementById('auth-status').textContent = 'Authentication successful';

                        // Now you can call Circuit API

                    } else {
                        // Authentication failed
                        const errorMessage = messagePayload.error;
                        document.getElementById('auth-status').textContent = 'Authentication Failed: ' + errorMessage;

                        // Handle user not found error
                        if (errorMessage.includes('No matching passkey found')) {
                            // Try registration instead
                            document.getElementById('circuit-iframe').contentWindow.postMessage({
                                type: 'configure',
                                actionType: 'register',
                                username: 'username',
                                inviteCode: '', // Required for registration
                            }, 'https://app.circuit.org');
                        }
                    }
                }
            });
        </script>
    </body>
    </html>
    ```
  </Tab>

  <Tab title="React Example">
    ```typescript theme={null}
    import { useEffect, useRef, useState } from 'react';

    export default function App() {
        return (
            <div>
                <h1>My App</h1>
                <CircuitAuth username="testuser" /> // Replace with actual username
            </div>
        );
    }

    function CircuitAuth({ username }: { username: string }) {
        const iframeRef = useRef<HTMLIFrameElement>(null);
        const [status, setStatus] = useState('Loading...');
        const [tryingRegister, setTryingRegister] = useState(false);

        const configure = (actionType: 'signIn' | 'register') => {
            // Configure the iframe
            iframeRef.current?.contentWindow?.postMessage({
                type: 'configure',
                config: {
                    backgroundColor: '#ffffff',
                    buttonColor: '#007bff',
                    buttonTextColor: '#ffffff',
                    title: 'Login to App + Circuit'
                },
                actionType: actionType,
                username: username,
                inviteCode: actionType === 'register' ? '' : undefined, // Required for registration
            }, 'https://app.circuit.org');
        };

        useEffect(() => {
            // Listen for messages from the Circuit iframe
            const handleMessage = (event: MessageEvent) => {
                // SECURITY: Only accept messages from Circuit's domain
                if (event.origin !== 'https://app.circuit.org') return;

                const messageType = event.data.type;
                const messagePayload = event.data.payload;

                // When Circuit iframe finishes loading and is ready
                if (messageType === 'ready') {
                    setStatus('Please authenticate');
                    configure('signIn');
                }

                // Getting the session token
                if (messageType === 'signInResult' || messageType === 'registerResult') {
                    if (messagePayload.success) {
                        // SUCCESS! Get the session token
                        const circuitSessionToken = messagePayload.authToken;

                        // Store session token for later use
                        localStorage.setItem('circuitSessionToken', circuitSessionToken);

                        // Update the UI
                        setStatus('Authentication successful');

                        // Now you can call Circuit API

                    } else {
                        // Authentication failed
                        const errorMessage = messagePayload.error;
                        setStatus('Authentication failed: ' + errorMessage);

                        // Handle user not found error
                        if (errorMessage.includes("No matching passkey found") && !tryingRegister) {
                            // Try registration instead
                            setStatus("User not found, trying registration...");
                            setTryingRegister(true);
                            configure('register');
                        }
                    }
                }
            };

            window.addEventListener('message', handleMessage);
            return () => window.removeEventListener('message', handleMessage);
        }, [username, tryingRegister]);

        return (
            <div>
                {/* Status display */}
                <p>{status}</p>

                {/* Circuit authentication iframe */}
                <iframe
                    ref={iframeRef}
                    src="https://app.circuit.org/embed/auth/basic"
                    width="400"
                    height="500"
                    style={{ border: 'none', borderRadius: '12px' }}
                />
            </div>
        );
    }

    ```
  </Tab>
</Tabs>

### iframe Message Communication Protocol

| Direction     | Message Type     | When Sent              | Payload                                                          |
| ------------- | ---------------- | ---------------------- | ---------------------------------------------------------------- |
| Circuit → App | `ready`          | iframe loaded          | `{ version: '1.0.0' }`                                           |
| App → Circuit | `configure`      | After receiving ready  | `json { actionType, username, inviteCode?, config? } `           |
| Circuit → App | `signInResult`   | Sign-in completed      | `json { success: boolean, authToken?: string, error?: string } ` |
| Circuit → App | `registerResult` | Registration completed | `json { success: boolean, authToken?: string, error?: string } ` |

### Authentication Requirements

| Action Type | Required Fields             | Optional Fields |
| ----------- | --------------------------- | --------------- |
| `signIn`    | `username` (must exist)     | `config`        |
| `register`  | `username` (must be unique) | `config`        |

### iframe Structure

```javascript theme={null}
<iframe
    src="https://app.circuit.org/embed/auth/basic"
    width="400"
    height="500"
    style="border: none; border-radius: 12px;">
</iframe>
```

### Configuration Options

| Property          | Type     | Description             | Example                 |
| ----------------- | -------- | ----------------------- | ----------------------- |
| `title`           | `string` | Main heading text       | `'Welcome to My App'`   |
| `subtext`         | `string` | Subtitle text           | `'Sign in to continue'` |
| `ctaText`         | `string` | Button text             | `'Continue'`            |
| `backgroundColor` | `string` | Background color        | `'#ffffff'`             |
| `buttonColor`     | `string` | Button background color | `'#007bff'`             |
| `buttonTextColor` | `string` | Button text color       | `'#ffffff'`             |
| `titleColor`      | `string` | Title text color        | `'#333333'`             |
| `subtextColor`    | `string` | Subtitle text color     | `'#666666'`             |
| `radius`          | `number` | Border radius in pixels | `12`                    |
| `fontFamily`      | `string` | Font family             | `'sans-serif'`          |
| `fontSize`        | `string` | Font size               | `'14px'`                |

### Error Codes And Recovery

| Error Message                          | What it Means                         | Recommended Action                |
| -------------------------------------- | ------------------------------------- | --------------------------------- |
| `"No matching passkey found"`          | User doesn't exist in Circuit         | User typo or registration         |
| `"Username is already taken"`          | Registration failed - username exists | Ask user for different username   |
| `"Invalid invite code"`                | Wrong or missing invite code          | Verify the invite code is correct |
| `"Authentication verification failed"` | Passkey verification failed           | Ask user to try again             |


# Circuit
Source: https://docs.circuit.org/introduction

Run any agent on your existing wallet.

Circuit lets you run agents on your existing wallet — automated strategies that trade, farm yield, and manage positions across chains, without giving up custody of your keys.

### Choose your path

<CardGroup>
  <Card title="I am a User" icon="wallet" href="/agent-users/get-started">
    Create an account, connect wallets, and run agents safely.
  </Card>

  <Card title="I am an Agent Developer" icon="code" href="/agent-developers/introduction">
    Build, test, and publish agents with the Circuit SDK and CLI.
  </Card>

  <Card title="I am an Integrator" icon="plug" href="/integrating-circuit-agents-in-your-app-wallet/authentication">
    Embed Circuit agents in your app or wallet with the Integration API.
  </Card>
</CardGroup>

<iframe />

### How it works

Agents run on Circuit's infrastructure and suggest transactions on your behalf. Your private keys live in a secure enclave, completely separate from agent code — agents can only *request* transactions, and signing happens outside the sandbox. Everything executes onchain, giving you a verifiable record of every action.

### What are you building?

<CardGroup>
  <Card title="Yield Strategies" icon="seedling" href="/agent-developers/examples/yield-agent">
    Deposit into Aave, Compound, or other DeFi protocols automatically.
  </Card>

  <Card title="Trading Agents" icon="chart-line" href="/agent-developers/examples/hyperliquid-agent">
    Trade perpetuals and spot on Hyperliquid with custom strategies.
  </Card>

  <Card title="Prediction Markets" icon="bullseye" href="/agent-developers/examples/polymarket-agent">
    Build agents that trade on Polymarket based on your own signals.
  </Card>
</CardGroup>

### Next

* [**Get Started**](agent-users/get-started) — Set up your account and run your first agent
* [**Agent Developers**](agent-developers/introduction) — Build and publish agents with the SDK and CLI
* [**Integration API**](integrating-circuit-agents-in-your-app-wallet/authentication) — Embed Circuit agents in your app or wallet
* [**AGENTS.md**](CLI-SDK-CONTEXT.txt) — AI assistant context for building Circuit agents