Overview & Conventions

This page covers the global conventions used across the Circuit Agent SDK (TypeScript + Python)

---

Network Identifiers

All methods use consistent network identifiers:

• EVM networks: "ethereum:chainId"

  • Examples: "ethereum:1" (Mainnet), "ethereum:137" (Polygon), "ethereum:42161" (Arbitrum)

• Solana: "solana"

• Hyperliquid: "hypercore:perp"

You'll see these in:

• Swaps & bridges (Swidge)

• Transactions / signing

• Positions

• Platform integrations

---

Native Tokens

Native tokens are handled slightly differently depending on the surface:

• In some SDK methods (e.g., Swidge 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	0x0000000000000000000000000000000000000000
ethereum:137	POL (formerly MATIC)	0x0000000000000000000000000000000000000000
ethereum:42161	ETH	0x0000000000000000000000000000000000000000
ethereum:10	ETH	0x0000000000000000000000000000000000000000
ethereum:8453	ETH	0x0000000000000000000000000000000000000000
ethereum:43114	AVAX	0x0000000000000000000000000000000000000000
solana	SOL	11111111111111111111111111111111
hypercore:perp	USDC (Perps)	0x0000000000000000000000000000000000000000

Note: Some SDK methods may accept empty strings for native token addresses, but position data uses the canonical null addresses above. For consistency, compare against null addresses when working with currentPositions / getCurrentPositions() results.

---

SDK Response Pattern

All SDK methods return a response object with a consistent shape:

• success: boolean

• data: present on success (varies by method)

• error / errorMessage / errorDetails: present on failure (fields vary slightly by language)

  • Note: errorMessage and errorDetails will be removed in the next breaking update, only use the error field for new agents.

How to Use Responses

Always check success before using data. Log failures with error: true / error=True for visibility (see Logging).

TypeScript

const result = await agent.getCurrentPositions();

if (result.success && result.data) {
  // Safe to use result.data
} else {
  await agent.log(result.error || result.errorMessage || "Request failed", { error: true });
}

Python

---

Error Handling

• Uncaught exceptions in your agent's run / unwind are caught by the SDK; the execution is marked failed and the error is logged.

• You generally do not need to wrap SDK method calls in try/catch / try/except. And instead leverage the built in success + data + error fields.

• Use try/catch / try/except for:

  • Your own parsing / calculations

  • External API calls

  • Custom recovery logic

For deeper guidance and patterns, see Error Handling.

---

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 (i.e $1.5 USDC would be "1.5"). You will also need to consider Hyperliquid's restrictions on tick and lot sizing when placing orders.

• Keep them as strings to preserve precision for large values.

---

Agent Positions Concepts

There are two concepts to know:

• agent.currentPositions: snapshot at the start of execution.

• getCurrentPositions() / get_current_positions(): fetch "live" positions, but note that indexing can lag by chain and may not reflect transactions immediately.

Note: For Hyperliquid agents you will need to use our built-in balances/positions methods to fetch those directly from their API, please see Hyperliquid more details.

If you need near-real-time updates right after sending transactions, track deltas in memory during the execution cycle, building on the initial agent.curentPositions

See Positions

---

Agent Session Memory

Memory is session-scoped key/value storage:

• Keys are namespaced by agent/session.

• Memory persists across execution cycles within the same session.

• Values must be strings (serialize JSON/numbers before storing).

See Memory

---

Where to Go Next

• Logging - How to emit user-visible logs vs debug logs

• Custom Transactions/Signing - Lowest level transaction signing and execution

• Swidge - Swaps + bridges conventions and workflow

• Positions - How balances and pending transactions work

• Error Handling - Deeper patterns and examples

• Circuit integrations, such as Hyperliquid and Polymarket