TypeScript SDK

Use Circuit CLI to create and deploy agents using this SDK

Install the SDK

bun add @circuitorg/agent-sdk

Requires Bun ≥ 1.0 - npm and yarn will not work

Agent Constructor

Create a Circuit Agent instance by passing in run and unwind functions.

Signature

new Agent({
  runFunction: (agent: AgentContext) => Promise<void>,
  unwindFunction?: (agent: AgentContext) => Promise<void>
});

Parameters

Param	Type	Description
runFunction	(agent: AgentContext) ⇒ Promise<void>	The execution function that runs your agent's logic
unwindFunction?	(agent: AgentContext, positions: CurrentPosition[]) ⇒ Promise<void>	The cleanup function called when the agent unwinds.

Examples

import { Agent, type AgentContext, type CurrentPosition } from "@circuitorg/agent-sdk";

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

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

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

// For Circuit deployment
export default agent.getExport();

AgentContext Interface

Main interface for interacting with the Circuit platform. This object is passed to your runFunction and unwindFunction and contains the following.

Session Data

Property	Type	Description
agent.sessionId	string	Unique session identifier
agent.sessionWalletAddress	string	Wallet address for this session
agent.currentPositions	CurrentPosition[]	Positions allocated to agent at start of execution

interface CurrentPosition {
  network: string;           // e.g., "ethereum:1", "ethereum:137", "solana"
  assetAddress: string;      // Token contract address
  tokenId: string | null;    // For NFTs/ERC-1155, null for fungible tokens
  avgUnitCost: string;       // Average cost per unit (as string for precision)
  currentQty: string;        // Current quantity held (as string for precision)
}

Core Methods

Method	Description
agent.log()	Send messages to users and log locally
agent.signAndSend()	Sign and broadcast blockchain transactions
agent.signMessage()	Sign messages (EVM only)

Namespace

Namespace	Description
agent.memory.*	Persist data across executions ( .set(), .get(), .list(), .delete() )
agent.swidge.*	Cross-chain swaps and bridges ( .quote(), .execute() )
agent.platforms.polymarket.*	Trade prediction markets ( .marketOrder(), .redeemPositions() )