@circuitorg/agent-sdk 1.1.7 → 1.2.0

package/README.md

@@ -1,20 +1,45 @@
-# Circuit Agent SDK - Typescript
+# Circuit Agent SDK - TypeScript
 
-> **Clean, type-safe TypeScript SDK for building cross-chain agents on the circuit platform**
+> **Clean, unified, type-safe TypeScript SDK for building cross-chain agents on Circuit**
 
-A TypeScript SDK for building automated agents to deploy on Circuit. Features a simple API surface with just **2 core methods** plus **platform integrations** with full type safety.
+A simplified TypeScript SDK for building automated agents to deploy on Circuit. Agents receive a single `AgentContext` object containing everything they need - request data, SDK methods, and unified logging. No boilerplate, no return values to manage, just write your logic.
 
 > **💡 Best used with [Circuit Agents CLI](https://github.com/circuitorg/agents-cli)** - Deploy, manage, and test your agents with ease
 
-## ✨ Features
-
-- **🎯 Simple API**: 2 core methods (`sendLog()`, `signAndSend()`) + platform integrations
-- **🔒 Type Safety**: Network parameter determines valid request shapes automatically
-- **🚀 Cross-Chain**: Unified interface for EVM and Solana networks
-- **🌉 Cross-Chain Swaps**: Built-in Swidge integration for seamless token swaps and bridges
-- **📈 Polymarket Integration**: Trade prediction markets with `sdk.polymarket.*` methods
+## 📑 Table of Contents
+
+- [Circuit Agent SDK - TypeScript](#circuit-agent-sdk---typescript)
+  - [📑 Table of Contents](#-table-of-contents)
+  - [🚀 Quick Start](#-quick-start)
+    - [Install the SDK](#install-the-sdk)
+    - [Create Your First Agent](#create-your-first-agent)
+  - [🎯 Core Concepts](#-core-concepts)
+    - [The AgentContext Object](#the-agentcontext-object)
+    - [Run/Stop Function Requirements](#runstop-function-requirements)
+  - [📝 Unified Logging with agent.log()](#-unified-logging-with-agentlog)
+  - [💾 Session Memory Storage](#-session-memory-storage)
+  - [🌉 Cross-Chain Swaps with Swidge](#-cross-chain-swaps-with-swidge)
+    - [Get and execute a quote](#get-and-execute-a-quote)
+  - [📈 Polymarket Prediction Markets](#-polymarket-prediction-markets)
+    - [Place Market Orders](#place-market-orders)
+    - [Redeem Positions](#redeem-positions)
+  - [🚀 Sign \& Send Transactions](#-sign--send-transactions)
+    - [Ethereum (any EVM chain)](#ethereum-any-evm-chain)
+    - [Solana](#solana)
+  - [⚡ Error Handling](#-error-handling)
+  - [🛠️ Deployment](#️-deployment)
+    - [What You Write](#what-you-write)
+    - [Deploy to Circuit](#deploy-to-circuit)
+    - [Test Locally](#test-locally)
+  - [🧪 Manual Instantiation (Testing)](#-manual-instantiation-testing)
+  - [📚 Working Examples](#-working-examples)
+    - [`demo-agent.ts`](#demo-agentts)
+    - [`examples/kitchen-sink.ts`](#exampleskitchen-sinkts)
+  - [🎯 Key Takeaways](#-key-takeaways)
+  - [📖 Additional Resources](#-additional-resources)
 
 ## 🚀 Quick Start
+
 ### Install the SDK
 ```bash
 npm install @circuitorg/agent-sdk
@@ -24,867 +49,449 @@ yarn add @circuitorg/agent-sdk
 bun add @circuitorg/agent-sdk
 ```
 
-### Sample SDK Usage
->**NOTE:** The fastest, and recommended, way to get started is to setup an agent via the circuit [CLI](https://github.com/circuitorg/agents-cli)'s 'circuit agent init' command. This will setup a sample agent directory with the necessary agent wireframe, and configure the cli to allow you for easy testing and deployment. You just simply need to add in your secret formula to the execution and stop functions. 
+### Create Your First Agent
 
-```typescript
-import { AgentSdk } from "@circuitorg/agent-sdk";
+Every agent receives a single `AgentContext` object that provides:
 
-// Initialize the sdk
-const sdk = new AgentSdk({
-  sessionId: 123,
-});
-```
+**Session Data:**
+- `agent.sessionId` - Unique session identifier
+- `agent.sessionWalletAddress` - The wallet address for this session
+- `agent.currentPositions` - Assets allocated to the agent at the start of this execution
 
-## 🎯 Core SDK API (Only 2 Methods!)
+**Available Methods:**
+- `agent.log()` - Send messages to users and log locally
+- `agent.memory` - Persist data across executions (`.set()`, `.get()`, `.list()`, `.delete()`)
+- `agent.platforms.polymarket` - Trade prediction markets (`.marketOrder()`, `.redeemPositions()`)
+- `agent.swidge` - Cross-chain swaps and bridges (`.quote()`, `.execute()`)
+- `agent.signAndSend()` - Execute custom built transactions on any supported chain
+- `agent.signMessage()` - Sign messages (EVM only)
 
-### 1. Add Logs to Timeline
+**Important:** `currentPositions` reflects your allocated assets at the **start** of each execution. To avoid failed transactions, you should be tracking intra-run position changes based on transactions the agent makes during the execution. Circuit will provide updated positions on the next execution request.
 
 ```typescript
-await sdk.sendLog({ 
-  type: "observe", 
-  shortMessage: "Starting swap operation" 
-});
-```
-
-### 2. Sign & Send Transactions
-
-#### Ethereum (any EVM chain)
+import { Agent, AgentContext } from "@circuitorg/agent-sdk";
+
+async function run(agent: AgentContext): Promise<void> {
+  /**
+   * Main agent logic - receives AgentContext with everything needed.
+   * No return value - errors are caught automatically.
+   */
+  // Access session data
+  await agent.log(`Starting execution for session ${agent.sessionId}`);
+  await agent.log(`Wallet: ${agent.sessionWalletAddress}`);
+  await agent.log(`Managing ${agent.currentPositions.length} allocated positions`);
+
+  // Use SDK methods
+  await agent.memory.set("last_run", Date.now().toString());
+
+  // Your agent logic here - track position changes within this execution
+  // Circuit will provide updated positions on the next run
+}
 
-```typescript
-// Native ETH transfer
-await sdk.signAndSend({
-  network: "ethereum:1", // Chain ID in network string
-  request: {
-    toAddress: "0x742d35cc6634C0532925a3b8D65e95f32B6b5582" as `0x${string}`,
-    data: "0x" as `0x${string}`,
-    value: "1000000000000000000" // 1 ETH in wei
-  },
-  message: "Sending 1 ETH"
-});
+async function stop(agent: AgentContext): Promise<void> {
+  /**Cleanup when agent is stopped.*/
+  await agent.log("Cleaning up resources");
+  await agent.memory.delete("temp_data");
+}
 
-// Contract interaction
-await sdk.signAndSend({
-  network: "ethereum:42161", // Arbitrum
-  request: {
-    toAddress: "0xTokenContract..." as `0x${string}`,
-    data: "0xa9059cbb..." as `0x${string}`, // encoded transfer()
-    value: "0"
-  }
+// Boilerplate - This should never change unless you want to change the names of your run and stop functions
+const agent = new Agent({
+  runFunction: run,
+  stopFunction: stop
 });
-```
-
-#### Solana
 
-```typescript
-await sdk.signAndSend({
-  network: "solana",
-  request: {
-    hexTransaction: "010001030a0b..." // serialized VersionedTransaction
-  }
-});
+export default agent.getExport();
 ```
 
+## 🎯 Core Concepts
 
-## 🌉 Cross-Chain Swaps with Swidge
+### The AgentContext Object
 
-The SDK includes built-in Swidge integration for seamless cross-chain token swaps and bridges.
+Every agent function receives a single `AgentContext` object that contains:
 
-Swidge provides a unified interface that handles both **swapping** (exchanging tokens within the same network) and **bridging** (moving tokens across different networks) through a single, easy-to-use API. Whether you're doing a simple token swap on Ethereum or bridging assets across chains, the same quote-and-execute pattern works for everything.
+**Request Data:**
+- `agent.sessionId` - Unique session identifier
+- `agent.sessionWalletAddress` - Wallet address for this session
+- `agent.currentPositions` - Current positions allocated to this agent
 
-### 3. Cross-Chain Swaps & Bridges
+**SDK Methods:**
+- `agent.log()` - Unified logging (console + backend)
+- `agent.memory` - Session-scoped key-value storage
+- `agent.platforms.polymarket` - Prediction market operations
+- `agent.swidge` - Cross-chain swap operations
+- `agent.signAndSend()` - Sign and broadcast transactions
+- `agent.signMessage()` - Sign messages on EVM
 
-#### Get a Quote
+### Run/Stop Function Requirements
 
-```typescript
-// 🌉 Bridge USDC: Polygon → Arbitrum
-const bridgeQuote = await sdk.swidge.quote({
-  from: { network: "ethereum:137", address: request.sessionWalletAddress },
-  to: { network: "ethereum:42161", address: request.sessionWalletAddress },
-  amount: "50000000", // $50 USDC (6 decimals)
-  fromToken: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174", // USDC on Polygon
-  toToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",   // USDC on Arbitrum
-  slippage: "2.0", // 2% slippage for cross-chain (default: 0.5%)
-  priceImpact: "1.0" // 1% max price impact (default: 0.5%)
-});
+1. **Signature**: `async function myFunction(agent: AgentContext): Promise<void>`
+2. **Return**: Always return `void` (or no return statement)
+3. **Errors**: You should surface any relevant errors via `agent.log('error message', { error: true })`. All errors from built-in SDK functions will be caught gracefully and provided in the return data for you to handle as necessary.
 
-// 🔄 Swap USDC → ETH on same chain (using defaults)
-const swapQuote = await sdk.swidge.quote({
-  from: { network: "ethereum:42161", address: request.sessionWalletAddress },
-  to: { network: "ethereum:42161", address: request.sessionWalletAddress },
-  amount: "100000000", // $100 USDC (6 decimals)
-  fromToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", // USDC
-  // toToken omitted = native ETH (default behavior)
-  // slippage defaults to "0.5", priceImpact defaults to "0.5"
-});
-
-if (quote.success) {
-  console.log(`💰 You'll receive: ${quote.data.assetReceive.amountFormatted}`);
-  console.log(`💸 Total fees: ${quote.data.fees.map(f => f.name).join(", ")}`);
-} else if (quote.error) {
-  // Check for specific error types
-  if (quote.error === QUOTE_RESULT.WALLET_NOT_FOUND) {
-    console.log("👛 Wallet not found");
-  } else if (quote.error === QUOTE_RESULT.WALLET_MISMATCH) {
-    console.log("🔐 Wallet address doesn't match session");
-  } else {
-    console.log("❓ Quote not available for this swap");
-  }
-}
-```
+## 📝 Unified Logging with agent.log()
 
-#### Execute a Swap
+Use `agent.log()` to communicate with your users and debug your agent. Every message appears in your terminal, and by default also shows up in the Circuit UI for your users to see. Simply pass `debug: true` to skip sending the message to the user.
 
 ```typescript
-// 1️⃣ Get a quote first
-let quoteRequest = {
-  from: { network: "ethereum:42161", address: request.sessionWalletAddress },
-  to: { network: "ethereum:1", address: request.sessionWalletAddress },
-  amount: "100000000", // $100 USDC
-  fromToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", // USDC on Arbitrum
-  priceImpact: "0.1", // Conservative price impact setting
-  slippage: "5.0"
-};
+async function run(agent: AgentContext): Promise<void> {
+  // Standard log: Shows to user in Circuit UI
+  await agent.log("Processing transaction");
+
+  // Error log: Shows to user in Circuit UI (as an error)
+  const result = await agent.memory.get("key");
+  if (!result.success) {
+    await agent.log(result.error_message || result.error, { error: true });
+  }
 
-let quote = await sdk.swidge.quote(quoteRequest);
+  // Debug log: Only you see this in your terminal
+  await agent.log("Internal state: processing...", { debug: true });
 
-// 2️⃣ Handle quote failures with retry logic
-if (quote.error === QUOTE_RESULT.NO_QUOTE_PROVIDED) {
-  console.log(`❓ Quote not available, increasing price impact and retrying...`)
-  // Retry with more permissive parameters
-  quoteRequest.priceImpact = "10.0";
-  quoteRequest.slippage = "10.0";
-  quote = await sdk.swidge.quote(quoteRequest);
-}
+  // Logging objects
+  // Objects are pretty-printed to console and serialized/truncated for backend
+  await agent.log({ wallet: agent.sessionWalletAddress, status: "active" });
 
-// 3️⃣ Execute the swap if quote succeeded
-if (quote.success && quote.data) {
-  console.log(`💰 Expected to receive: ${quote.data.assetReceive.amountFormatted}`);
-  console.log(`💸 Fees: ${quote.data.fees.map(f => `${f.name}: ${f.amountFormatted}`).join(", ")}`);
-
-  const result = await sdk.swidge.execute(quote.data);
-
-  if (result.success && result.data) {
-    console.log(`🎉 Status: ${result.data.status}`);
-
-    if (result.data.status === "success") {
-      console.log(`📤 Sent: ${result.data.in.txs[0]}`);
-      console.log(`📥 Received: ${result.data.out.txs[0]}`);
-      console.log("✅ Cross-chain swap completed!");
-    } else if (result.data.status === "failure") {
-      console.log("❌ Transaction failed");
-    } else if (result.data.status === "refund") {
-      console.log("↩️ Transaction was refunded");
-    } else if (result.data.status === "delayed") {
-      console.log("⏰ Transaction is delayed");
-    }
-  } else {
-    console.log(`❌ Execute failed: ${result.error}`);
+  // Check if message reached the user
+  const logResult = await agent.log("Important message");
+  if (!logResult.success) {
+    // Rare - usually means Circuit UI is unreachable
   }
-} else {
-  console.log(`❌ Quote failed after retry: ${quote.error}`);
-  return { success: false };
 }
 ```
 
-### Swidge API Reference
+**What Your Users See:**
 
-#### `sdk.swidge.quote(request: SwidgeQuoteRequest): Promise<SwidgeQuoteResponse>`
+| Code | You See (Terminal) | User Sees (Circuit UI) |
+|------|-------------------|----------------------|
+| `agent.log("msg")` | ✅ In your terminal | ✅ In Circuit UI |
+| `agent.log("msg", { error: true })` | ✅ As error in terminal | ✅ As error in Circuit UI |
+| `agent.log("msg", { debug: true })` | ✅ In terminal | ❌ Hidden from user |
+| `agent.log("msg", { error: true, debug: true })` | ✅ As error in terminal | ❌ Hidden from user |
 
-Get pricing and routing information for token swaps between networks or within the same network.
+## 💾 Session Memory Storage
 
-**Parameters:**
-```typescript
-{
-  from: { network: SwidgeNetwork, address: string },
-  to: { network: SwidgeNetwork, address: string },
-  amount: string,                    // Amount in token's smallest unit
-  fromToken?: string,                // Source token contract (omit for native tokens)
-  toToken?: string,                  // Destination token contract (omit for native tokens)
-  slippage?: string,                 // Slippage tolerance % (default: "0.5")
-  priceImpact?: string               // Max price impact % (default: "0.5")
-}
-```
+Store and retrieve data for your agent's session with simple operations. Memory is **automatically scoped to your session ID**, and for now is simple string storage. You will need to handle serialization of whatever data you want to store here.
 
-**Returns:**
 ```typescript
-{
-  success: boolean,
-  data?: {
-    engine: "relay",
-    assetSend: {
-      network: SwidgeNetwork,
-      address: string,
-      token: string | null,
-      amount: string,
-      amountFormatted: string,
-      amountUsd: string,
-      // ... additional fields
-    },
-    assetReceive: {
-      network: SwidgeNetwork,
-      address: string,
-      token: string | null,
-      amount: string,
-      amountFormatted: string,
-      amountUsd: string,
-      // ... additional fields
-    },
-    priceImpact: {
-      usd?: string,
-      percentage?: string
-    },
-    fees: Array<{
-      name: string,
-      amount?: string,
-      amountFormatted?: string,
-      amountUsd?: string
-    }>,
-    steps: Array<SwidgeUnsignedStep>  // Transaction steps to execute
-  },
-  error?: string,
-  errorDetails?: {
-    message: string,
-    status?: number,
-    statusText?: string
+async function run(agent: AgentContext): Promise<void> {
+  // Set a value
+  const result = await agent.memory.set("lastSwapNetwork", "ethereum:42161");
+  if (!result.success) {
+    await agent.log(result.error_message || result.error, { error: true });
   }
+
+  // Get a value
+  const getResult = await agent.memory.get("lastSwapNetwork");
+  if (getResult.success && getResult.data) {
+    const network = getResult.data.value;
+    await agent.log(`Using network: ${network}`);
+  } else {
+    await agent.log("No saved network found");
+  }
+
+  // List all keys
+  const listResult = await agent.memory.list();
+  if (listResult.success && listResult.data) {
+    await agent.log(`Found ${listResult.data.count} keys: ${listResult.data.keys}`);
+  }
+
+  // Delete a key
+  await agent.memory.delete("tempData");
 }
 ```
 
-**Error Handling with QUOTE_RESULT:**
-
-The SDK exports a `QUOTE_RESULT` constant that provides type-safe error checking with full IntelliSense support:
+**All memory operations return responses with `.success` and `.error_message`:**
 
 ```typescript
-import { QUOTE_RESULT } from "@circuitorg/agent-sdk";
-
-// Use QUOTE_RESULT constants instead of hardcoded strings
-if (quote.error === QUOTE_RESULT.WALLET_NOT_FOUND) {
-  // Handle wallet not found
-} else if (quote.error === QUOTE_RESULT.WALLET_MISMATCH) {
-  // Handle wallet mismatch
+const result = await agent.memory.set("key", "value");
+if (!result.success) {
+  await agent.log(`Failed to save: ${result.error_message}`, { error: true });
 }
 ```
 
-**Possible Error Responses:**
-- `QUOTE_RESULT.FOUND` - Success case (not an error)
-- `QUOTE_RESULT.NO_QUOTE_PROVIDED` - Generic API error
-- `QUOTE_RESULT.WALLET_NOT_FOUND` - Wallet address not found
-- `QUOTE_RESULT.WALLET_MISMATCH` - From wallet does not match session wallet
-
-#### `sdk.swidge.execute(quoteData: SwidgeExecuteRequest): Promise<SwidgeExecuteResponse>`
+## 🌉 Cross-Chain Swaps with Swidge
 
-Execute a cross-chain swap or bridge using a complete quote from `sdk.swidge.quote()`.
+Built-in Swidge integration for seamless cross-chain token swaps and bridges.
 
-Pass the entire `quote.data` object returned from `quote()` - the SDK handles all transaction signing, broadcasting, and cross-chain coordination.
+### Get and execute a quote
+> Note: It is important to always validate quotes before executing. Circuit will always do its best to return a quote, and as of now, will only filter out quotes with price impacts exceeding 100% to ensure maximum flexibility. It is on the agent to makes sure a quote is valid, given its own parameters
 
-**Parameters:**
 ```typescript
-// The complete quote.data object from sdk.swidge.quote()
-{
-  engine: "relay",
-  assetSend: SwidgeQuoteAsset,
-  assetReceive: SwidgeQuoteAsset,
-  priceImpact: SwidgePriceImpact,
-  fees: SwidgeFee[],
-  steps: SwidgeUnsignedStep[]  // Contains transaction details for each step
-}
-```
+async function run(agent: AgentContext): Promise<void> {
+  // 1. Get quote
+  const quote = await agent.swidge.quote({
+    from: { network: "ethereum:8453", address: agent.sessionWalletAddress },
+    to: { network: "ethereum:137", address: agent.sessionWalletAddress },
+    amount: "1000000000000000",  // 0.001 ETH
+    toToken: "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
+    slippage: "2.0",
+    priceImpact: "100.0"
+  });
 
-**Returns:**
-```typescript
-{
-  success: boolean,
-  data?: {
-    status: "success" | "failure" | "refund" | "delayed",
-    in: {
-      network: string,
-      txs: string[]  // Transaction hashes for sending side
-    },
-    out: {
-      network: string,
-      txs: string[]  // Transaction hashes for receiving side
-    },
-    lastUpdated: number  // Timestamp of last status update
-  },
-  error?: string,
-  errorDetails?: {
-    message: string,
-    status?: number,
-    statusText?: string
+  if (!quote.success) {
+    await agent.log(`Quote failed: ${quote.error_message}`, { error: true });
+    return;
+  }
+
+  if (quote.data && Math.abs(parseFloat(quote.data.priceImpact.percentage)) > 10) {
+    await agent.log(`Warning: Price impact is too high: ${quote.data.priceImpact.percentage}%`, { error: true, debug: true });
+  } else if (quote.data) {
+    await agent.log(`You'll receive: ${quote.data.assetReceive.amountFormatted}`);
+    await agent.log(`Fees: ${quote.data.fees.map(f => f.name).join(', ')}`);
+
+    // 2. Execute the swap
+    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!");
+        await agent.log(`In tx: ${result.data.in.txs}`);
+        await agent.log(`Out tx: ${result.data.out.txs}`);
+      } else if (result.data.status === "failure") {
+        await agent.log("❌ Swap failed", { error: true });
+      }
+    } else {
+      await agent.log(result.error_message || result.error, { error: true });
+    }
   }
 }
 ```
 
-**Execution Flow:**
-1. SDK signs and broadcasts transactions from the `steps` array
-2. Monitors cross-chain execution progress
-3. Returns final status once complete (never returns "pending" or "waiting")
-
-**Status Meanings:**
-- `"success"` - All transactions completed successfully
-- `"failure"` - One or more transactions failed
-- `"refund"` - Transaction was refunded (e.g., due to timeout or failure)
-- `"delayed"` - Transaction is taking longer than expected but still processing
-
-
 ## 📈 Polymarket Prediction Markets
 
-The SDK includes built-in Polymarket integration for trading prediction markets on Polygon.
-
-### 4. Polymarket Trading
+Trade prediction markets on Polygon.
 
-#### Get Positions
-
-Fetch all current positions for the session wallet:
+### Place Market Orders
+> Note: Right now, polymarket's API accepts different decimal precision for buys and sells, this will result in dust positions if you are selling out of a position before expiry. Once expired, dust can be cleaned up during the redeem step.
 
 ```typescript
-const positions = await sdk.polymarket.positions();
-
-if (positions.success && positions.data) {
-  console.log(`Total value: $${positions.data.totalValue}`);
-  
-  for (const position of positions.data.positions) {
-    console.log(`${position.question} (${position.outcome})`);
-    console.log(`  Shares: ${position.formattedShares}`);
-    console.log(`  Value: $${position.valueUsd}`);
-    console.log(`  P&L: $${position.pnlUsd} (${position.pnlPercent}%)`);
+async function run(agent: AgentContext): Promise<void> {
+  // Buy order - size is USD amount to spend
+  const buyOrder = await agent.platforms.polymarket.marketOrder({
+    tokenId: "86192057611122246511563653509192966169513312957180910360241289053249649036697",
+    size: 3,  // Spend $3
+    side: "BUY"
+  });
+
+  if (buyOrder.success && buyOrder.data) {
+    await agent.log(`Order ID: ${buyOrder.data.orderInfo.orderId}`);
+    await agent.log(`Price: $${buyOrder.data.orderInfo.priceUsd}`);
+    await agent.log(`Total: $${buyOrder.data.orderInfo.totalPriceUsd}`);
+  } else {
+    await agent.log(buyOrder.error_message || buyOrder.error, { error: true });
   }
+
+  // Sell order - size is number of shares to sell
+  const sellOrder = await agent.platforms.polymarket.marketOrder({
+    tokenId: "86192057611122246511563653509192966169513312957180910360241289053249649036697",
+    size: 5.5,  // Sell 5.5 shares
+    side: "SELL"
+  });
 }
 ```
 
-#### Place Market Orders
-
-Execute buy or sell market orders:
+### Redeem Positions
 
 ```typescript
-// Buy order - size is USD amount to spend
-const buyOrder = await sdk.polymarket.marketOrder({
-  tokenId: "123456789...",  // Market token ID
-  size: 10,                  // Spend $10 to buy shares
-  side: "BUY"
-});
+async function stop(agent: AgentContext): Promise<void> {
+  /**Redeem all settled positions.*/
+  const redemption = await agent.platforms.polymarket.redeemPositions();
 
-// Sell order - size is number of shares to sell
-const sellOrder = await sdk.polymarket.marketOrder({
-  tokenId: "123456789...",
-  size: 5.5,                 // Sell 5.5 shares
-  side: "SELL"
-});
-
-if (buyOrder.success && buyOrder.data) {
-  console.log(`Order Success: ${buyOrder.data.success}`);
-  console.log(`Order ID: ${buyOrder.data.orderInfo.orderId}`);
-  console.log(`Filled at $${buyOrder.data.orderInfo.priceUsd} per share`);
-  console.log(`Total cost: $${buyOrder.data.orderInfo.totalPriceUsd}`);
+  if (redemption.success && redemption.data) {
+    const successful = redemption.data.filter(r => r.success);
+    await agent.log(`Redeemed ${successful.length} positions`);
+  } else {
+    await agent.log(redemption.error_message || redemption.error, { error: true });
+  }
 }
 ```
 
-#### Redeem Positions
+## 🚀 Sign & Send Transactions
 
-Claim winnings from settled positions:
+### Ethereum (any EVM chain)
 
 ```typescript
-// Redeem all redeemable positions
-const redemption = await sdk.polymarket.redeemPositions();
-
-if (redemption.success && redemption.data) {
-  for (const result of redemption.data) {
-    if (result.success) {
-      console.log(`✅ Redeemed: ${result.position.question}`);
-      console.log(`   TX: ${result.transactionHash}`);
+async function run(agent: AgentContext): Promise<void> {
+  // Self-send demo - send a small amount to yourself
+  const response = await agent.signAndSend({
+    network: "ethereum:1",
+    request: {
+      toAddress: agent.sessionWalletAddress,  // Send to self
+      data: "0x",
+      value: "100000000000000"  // 0.0001 ETH
+    },
+    message: "Self-send demo"
+  });
+
+  if (response.success) {
+    await agent.log(`Transaction sent: ${response.txHash}`);
+    if (response.transactionUrl) {
+      await agent.log(`View: ${response.transactionUrl}`);
     }
+  } else {
+    await agent.log(response.error_message || response.error, { error: true });
   }
 }
-
-// Redeem specific positions by token IDs
-const specificRedemption = await sdk.polymarket.redeemPositions({
-  tokenIds: ["123456", "789012"]
-});
 ```
 
-### Polymarket API Reference
-
-#### `sdk.polymarket.positions(): Promise<PolymarketPositionsResponse>`
-
-Get all current positions for the session wallet.
+### Solana
 
-**Returns:**
 ```typescript
-{
-  success: boolean,
-  data?: {
-    totalValue: number,
-    positions: Array<{
-      contractAddress: string,
-      tokenId: string,
-      question: string,
-      outcome: string,
-      formattedShares: string,
-      shares: string,
-      valueUsd: string,
-      priceUsd: string,
-      averagePriceUsd: string,
-      pnlUsd: string,
-      pnlPercent: string,
-      isRedeemable: boolean,
-      endDate: string,
-      // ... additional fields
-    }>
-  },
-  error?: string,
-  errorDetails?: { message: string, status?: number, statusText?: string }
+async function run(agent: AgentContext): Promise<void> {
+  const response = await agent.signAndSend({
+    network: "solana",
+    request: {
+      hexTransaction: "010001030a0b..."  // serialized VersionedTransaction
+    }
+  });
+
+  if (response.success) {
+    await agent.log(`Transaction: ${response.txHash}`);
+  } else {
+    await agent.log(response.error_message || response.error, { error: true });
+  }
 }
 ```
 
-#### `sdk.polymarket.marketOrder(request): Promise<PolymarketMarketOrderResponse>`
-
-Place a buy or sell market order.
+## ⚡ Error Handling
 
-⚠️ **Important**: The `size` parameter meaning differs by order side:
-- **BUY**: `size` is the USD amount to spend (e.g., 10 = $10 worth of shares)
-- **SELL**: `size` is the number of shares/tokens to sell (e.g., 10 = 10 shares)
+**All SDK methods return response objects with `.success` and `.error_message`:**
 
-**Parameters:**
-```typescript
-{
-  tokenId: string,  // Market token ID for the position
-  size: number,     // For BUY: USD amount. For SELL: Number of shares
-  side: "BUY" | "SELL"
-}
-```
 
-**Returns:**
-```typescript
-{
-  success: boolean,
-  data?: {
-    success: boolean,  // Whether the order was successfully submitted
-    orderInfo: {
-      orderId: string,
-      side: string,
-      size: string,
-      priceUsd: string,
-      totalPriceUsd: string,
-      txHashes: string[]
-    }
-  },
-  error?: string,
-  errorDetails?: { message: string, status?: number, statusText?: string }
-}
-```
+**Uncaught Exceptions:**
 
-#### `sdk.polymarket.redeemPositions(request?): Promise<PolymarketRedeemPositionsResponse>`
+If your function throws an uncaught exception, the Agent SDK automatically:
+1. Logs the error to console (visible in local dev and cloud logs)
+2. Updates the job in the circuit backend with status='failed' and logs the error.
 
-Redeem settled positions to claim winnings.
-
-**Parameters (optional):**
 ```typescript
-{
-  tokenIds?: string[]  // Specific token IDs to redeem (default: all redeemable positions)
-}
-```
+async function run(agent: AgentContext): Promise<void> {
+  // This typo will be caught and logged automatically
+  await agent.memmory.set("key", "value");  // TypeError
 
-**Returns:**
-```typescript
-{
-  success: boolean,
-  data?: Array<{
-    success: boolean,
-    position: { /* Full position details */ },
-    transactionHash: string | null
-  }>,
-  error?: string,
-  errorDetails?: { message: string, status?: number, statusText?: string }
+  // No need for try/catch around everything!
 }
 ```
 
-### Complete Polymarket Example
+## 🛠️ Deployment
 
-```typescript
-const executionFunction: ExecutionFunctionContract = async (request) => {
-  const sdk = new AgentSdk({ sessionId: request.sessionId });
-
-  try {
-    // Get current positions
-    const positions = await sdk.polymarket.positions();
-    
-    if (!positions.success || !positions.data) {
-      throw new Error(`Failed to get positions: ${positions.error}`);
-    }
+### What You Write
 
-    // Find specific position
-    const targetPosition = positions.data.positions.find(
-      p => p.tokenId === "YOUR_TOKEN_ID"
-    );
-
-    if (targetPosition && Number(targetPosition.formattedShares) > 0) {
-      // Sell position
-      const sellOrder = await sdk.polymarket.marketOrder({
-        tokenId: targetPosition.tokenId,
-        size: Number(targetPosition.formattedShares),
-        side: "SELL"
-      });
-
-      if (sellOrder.success && sellOrder.data?.orderInfo) {
-        await sdk.sendLog({
-          type: "observe",
-          shortMessage: `Sold ${targetPosition.outcome} for $${sellOrder.data.orderInfo.totalPriceUsd}`
-        });
-      }
-    }
+Your agent code should look like this - just define your functions and add the boilerplate at the bottom:
 
-    return { success: true };
-  } catch (error) {
-    await sdk.sendLog({
-      type: "error",
-      shortMessage: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`
-    });
-    return { success: false, error: error instanceof Error ? error.message : "Unknown error" };
-  }
-};
+```typescript
+import { Agent, AgentContext } from "@circuitorg/agent-sdk";
 
-const stopFunction: StopFunctionContract = async (request) => {
-  const sdk = new AgentSdk({ sessionId: request.sessionId });
+async function run(agent: AgentContext): Promise<void> {
+  await agent.log("Hello from my agent!");
+  // Your agent logic here
+}
 
-  try {
-    // Redeem all settled positions on stop
-    const redemption = await sdk.polymarket.redeemPositions();
+async function stop(agent: AgentContext): Promise<void> {
+  await agent.log("Cleaning up...");
+  // Optional cleanup logic
+}
 
-    if (redemption.success && redemption.data) {
-      const successful = redemption.data.filter(r => r.success);
-      await sdk.sendLog({
-        type: "observe",
-        shortMessage: `✅ Redeemed ${successful.length} positions`
-      });
-    }
+// ============================================================================
+// BOILERPLATE - Don't modify, this handles local testing AND Circuit deployment
+// ============================================================================
+const agent = new Agent({
+  runFunction: run,
+  stopFunction: stop
+});
 
-    return { success: true };
-  } catch (error) {
-    return { success: false, error: error instanceof Error ? error.message : "Unknown error" };
-  }
-};
+export default agent.getExport();
 ```
 
+That's it! The boilerplate code automatically handles the rest
 
-## 🔧 Examples
-
-### Barebones Agent
->This is the wireframe structure all agents need to have (executionFunction, stopFunction, and export default agent.getWorkerExport()). The main thing an agent dev needs to focus on is the execution logic, and any cleanup logic that would need to be ran whenever a user decides to stop an agent session.
-
-```typescript
-import { Agent, AgentSdk, ExecutionFunctionContract, StopFunctionContract } from "@circuitorg/agent-sdk";
-
-// Agent execution function using the new AgentSdk v1.0 API
-const executionFunction: ExecutionFunctionContract = async (request) => {
-  console.log(`🚀 Agent execution called for session ${request.sessionId}`);
-  
-  const sdk = new AgentSdk({
-    sessionId: request.sessionId,
-  });
+### Deploy to Circuit
 
-  try {
-    // Get user's wallet address (use vitalik.eth for demo if no address provided)
-    const userAddress = request.sessionWalletAddress
-    
-    await sdk.sendLog({ 
-      type: "observe", 
-      shortMessage: `🚀 Agent SDK v1.0 demo - Hello ${userAddress}`
-    });
-  
-    return { success: true};
-  } catch (error) {
-    await sdk.sendLog({ 
-      type: "error", 
-      shortMessage: `Agent execution error: ${error instanceof Error ? error.message : 'Unknown error'}` 
-    });
-    return { success: false, error: error instanceof Error ? error.message : "Unknown error" };
-  }
-};
+```bash
+circuit publish
+```
+> See the circuit cli docs for more details
 
-const stopFunction: StopFunctionContract = async (request) => {
-  const sdk = new AgentSdk({ 
-    sessionId: request.sessionId,
-    testing: true 
-  });
-  
-  try {
-    await sdk.sendLog({ 
-      type: "observe", 
-      shortMessage: "🛑 Agent stopping with new SDK v1.0" 
-    });
-    return { success: true };
-  } catch (error) {
-    return { success: false, error: error instanceof Error ? error.message : "Unknown error" };
-  }
-};
 
-// DONT MODIFY BELOW THIS
-const agent = new Agent({ executionFunction, stopFunction });
+### Test Locally
 
-// Export the agent for Cloudflare Workers
-export default agent.getWorkerExport();
+## 🧪 Manual Instantiation (Testing)
 
-```
+For testing in scripts or Node.js REPL, you can manually create an `AgentContext`:
 
-
-### Sample self sender
->This demonstrates a very basic structure of fetching balances and sending 1% of that amount to yourself. It highlights what stage in the transaction process you will "hand off" the transaction to the circuit infrastructure for signing and sending (broadcasting).
 ```typescript
-import {
-  Agent,
-  AgentSdk,
-  ExecutionFunctionContract,
-  StopFunctionContract,
-} from "@circuitorg/agent-sdk";
-import { encodeFunctionData, parseAbi } from "viem";
-
-export type BalanceResponse = {
-  /** Raw amount as string (wei, lamports, or token units) */
-  amount: string;
-  /** Number of decimals for the asset */
-  decimals: number;
-  /** Whether this is a token (true) or native asset (false) */
-  isToken: boolean;
+import { AgentContext } from "@circuitorg/agent-sdk";
+
+// Create agent context with test data
+// Tip: Get a real session ID and wallet from running 'circuit run -m local -x execute'
+const SESSION_ID = 123; // <your-session-id>
+const WALLET_ADDRESS = "your-wallet-address";
+
+// Create sample position data - helpful for testing your agents treatment of different scenarios
+// for example if you want to test some re-balancing logic, you can build a sample set of positions here
+// In production, or when using the cli, these will be live values for the session
+const SAMPLE_POSITION = {
+  network: "ethereum:137",
+  assetAddress: "0x4d97dcd97ec945f40cf65f87097ace5ea0476045",
+  tokenId: "86192057611122246511563653509192966169513312957180910360241289053249649036697",
+  avgUnitCost: "0.779812797920499100",
+  currentQty: "41282044"
 };
 
-export async function getEvmTokenBalance(params: {
-  address: string;
-  token: string;
-  rpcUrl: string;
-}): Promise<BalanceResponse> {
-  // balanceOf(address) - ERC-20 standard
-  const data = `0x70a08231${params.address
-    .replace(/^0x/, "")
-    .padStart(64, "0")}`;
-
-  const balanceCall = {
-    jsonrpc: "2.0",
-    id: 1,
-    method: "eth_call",
-    params: [{ to: params.token, data }, "latest"],
-  } as const;
-
-  const balanceRes = await fetch(params.rpcUrl, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify(balanceCall),
-  });
-
-  const balanceJson = (await balanceRes.json()) as { result?: string };
-  const balHex = balanceJson.result || "0x0";
-  const amount = BigInt(balHex);
-
-  // decimals() - ERC-20 standard
-  const decimalsCall = {
-    jsonrpc: "2.0",
-    id: 2,
-    method: "eth_call",
-    params: [{ to: params.token, data: "0x313ce567" }, "latest"],
-  } as const;
-
-  const decimalsRes = await fetch(params.rpcUrl, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify(decimalsCall),
-  });
+const agent = new AgentContext({
+  sessionId: SESSION_ID,
+  sessionWalletAddress: WALLET_ADDRESS,
+  currentPositions: [SAMPLE_POSITION]
+});
 
-  const decimalsJson = (await decimalsRes.json()) as { result?: string };
-  const decimals = decimalsJson.result
-    ? Number(BigInt(decimalsJson.result))
-    : 18;
+// Use it just like in production!
+await agent.log("Testing agent functionality!");
+await agent.memory.set("test_key", "test_value");
 
-  return {
-    amount: amount.toString(),
-    decimals,
-    isToken: true,
-  };
+const result = await agent.memory.get("test_key");
+if (result.success && result.data) {
+  console.log(`Value: ${result.data.value}`);
 }
+```
 
-const toSubscript = (num: number): string => {
-  const map: Record<string, string> = {
-    "0": "₀",
-    "1": "₁",
-    "2": "₂",
-    "3": "₃",
-    "4": "₄",
-    "5": "₅",
-    "6": "₆",
-    "7": "₇",
-    "8": "₈",
-    "9": "₉",
-  };
-  return String(num)
-    .split("")
-    .map((c) => map[c] ?? c)
-    .join("");
-};
+**Key Points:**
+- Use real session IDs from the CLI for proper testing
+- All SDK methods work the same way as in production
 
-const formatTokenAmount = (
-  amount: bigint,
-  decimals: number,
-  subscriptDecimals: number = 4,
-  standardDecimals: number = 6
-): string => {
-  const sign = amount < 0n ? "-" : "";
-  const s = (amount < 0n ? -amount : amount).toString();
-
-  const hasFraction = decimals > 0;
-  const integerPart =
-    s.length > decimals ? s.slice(0, s.length - decimals) : "0";
-  const fractional = hasFraction
-    ? s.length > decimals
-      ? s.slice(s.length - decimals)
-      : s.padStart(decimals, "0")
-    : "";
-
-  const groupedInt = integerPart.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
-
-  if (!hasFraction) return sign + groupedInt;
-  if (/^0+$/.test(fractional)) return sign + groupedInt;
-
-  const leadingZeros = fractional.match(/^0+/)?.[0].length ?? 0;
-
-  if (leadingZeros >= 3) {
-    // Use subscript notation for numbers with 3+ leading zeros
-    const rest = fractional.slice(leadingZeros);
-    const truncatedRest = rest.slice(0, subscriptDecimals);
-    const compressedFrac = `0${toSubscript(leadingZeros)}${truncatedRest}`;
-    return `${sign}${groupedInt}.${compressedFrac}`;
-  }
+## 📚 Working Examples
 
-  // For 0-2 leading zeros, use standard decimal formatting
-  const truncatedFrac = fractional.slice(0, standardDecimals);
-  const trimmedFrac = truncatedFrac.replace(/0+$/, ""); // Remove trailing zeros
+The SDK includes complete working examples to help you get started:
 
-  if (trimmedFrac === "") return sign + groupedInt;
-  return `${sign}${groupedInt}.${trimmedFrac}`;
-};
+### [`demo-agent.ts`](./examples/demo-agent.ts)
+An agent demonstrating all main features of the sdk:
+- Memory operations (set, get, list, delete)
+- Polymarket integration (market orders, position redemption)
+- Swidge
+- Self sending using sign and send
+- Unified logging patterns
 
-// Agent execution function using the new AgentSdk v1.0 API
-const executionFunction: ExecutionFunctionContract = async (request) => {
-  console.log(`🚀 Agent execution called for session ${request.sessionId}`);
+This is a great starting point for building your own agent.
 
-  const sdk = new AgentSdk({
-    sessionId: request.sessionId,
-  });
-
-  try {
-    await sdk.sendLog({
-      type: "observe",
-      shortMessage:
-        "🚀 Starting Agent SDK v1.0 comprehensive demo -- live test",
-    });
-
-    const PEPE_ARB = "0x25d887Ce7a35172C62FeBFD67a1856F20FaEbB00" as `0x${string}`;
-    const pepeBalance = await getEvmTokenBalance({
-      rpcUrl: "https://arb-mainnet.g.alchemy.com/v2/<YOUR_API_KEY>",
-      address: request.sessionWalletAddress,
-      token: PEPE_ARB,
-    });
-
-    const pepeBalanceFormatted = formatTokenAmount(
-      BigInt(pepeBalance.amount),
-      pepeBalance.decimals
-    );
-
-    await sdk.sendLog({
-      type: "observe",
-      shortMessage: `PEPE Balance (Arbitrum): ${pepeBalanceFormatted} PEPE`,
-    });
-
-
-    const abi = parseAbi([
-      "function transfer(address to, uint256 value) returns (bool)",
-    ]);
-    const demoAmount = BigInt(pepeBalance.amount) / 100n;
-
-    const data = encodeFunctionData({
-      abi,
-      functionName: "transfer",
-      args: [request.sessionWalletAddress as `0x${string}`, demoAmount],
-    });
-
-    // Demo custom contract call
-    await sdk.signAndSend({
-      network: "ethereum:42161",
-      request: {
-        toAddress: PEPE_ARB,
-        data: data,
-        value: "0", // No ETH value for token transfers
-      },
-      message: "Custom PEPE transfer demo",
-    });
-
-
-    await sdk.sendLog({
-      type: "observe",
-      shortMessage:
-        "✅ Agent SDK v1.0 comprehensive demo completed successfully!",
-    });
-
-    return { success: true };
-  } catch (error) {
-    console.error("💥 Agent execution error:", error);
-
-    await sdk.sendLog({
-      type: "error",
-      shortMessage: `Agent execution error: ${
-        error instanceof Error ? error.message : "Unknown error"
-      }`,
-    });
-
-    // Optional - Return detailed error information for the CLI to display
-    return {
-      success: false,
-      error: error instanceof Error ? error.message : "Unknown error",
-      errorDetails: {
-        name: error instanceof Error ? error.name : "Unknown",
-        message: error instanceof Error ? error.message : String(error),
-        stack: error instanceof Error ? error.stack : undefined,
-        timestamp: new Date().toISOString(),
-        sessionId: request.sessionId,
-        agentSlug: (globalThis as any).CIRCUIT_AGENT_SLUG || "unknown",
-        errorType: "AGENT_EXECUTION_ERROR",
-      },
-    };
-  }
-};
+### [`examples/kitchen-sink.ts`](./examples/kitchen-sink.ts)
+A comprehensive script showing all SDK features:
+- Manual AgentContext instantiation for testing
+- All memory operations with examples
+- Cross-chain swaps with Swidge (quotes, execution, price impact checks)
+- Polymarket operations (buy/sell orders, redemptions)
+- Custom transactions with signAndSend
+- Logging patterns (standard, error, debug)
 
-const stopFunction: StopFunctionContract = async (request) => {
-  const sdk = new AgentSdk({
-    sessionId: request.sessionId,
-    testing: true,
-  });
+Run this script to experiment with the SDK before deploying your agent.
 
-  try {
-    await sdk.sendLog({
-      type: "observe",
-      shortMessage: "🛑 Agent stopping with new SDK v1.0",
-    });
-    return { success: true };
-  } catch (error) {
-    console.error("💥 Agent stop error:", error);
-
-    return {
-      success: false,
-      error: error instanceof Error ? error.message : "Unknown error",
-      errorDetails: {
-        name: error instanceof Error ? error.name : "Unknown",
-        message: error instanceof Error ? error.message : String(error),
-        stack: error instanceof Error ? error.stack : undefined,
-        timestamp: new Date().toISOString(),
-        sessionId: request.sessionId,
-        agentSlug: (globalThis as any).CIRCUIT_AGENT_SLUG || "unknown",
-      },
-    };
-  }
-};
+## 🎯 Key Takeaways
 
-// Create the agent
-const agent = new Agent({ executionFunction, stopFunction });
+1. **Single Interface**: Everything you need is in the `AgentContext` object
+2. **No Return Values**: Functions return `void` - uncaught errors are handled automatically by circuit
+3. **Unified Logging**: `agent.log()` with simple `debug` and `error` flags
+4. **Check `.success`**: All SDK methods return response objects with `.success` and `.error_message`
 
-// Export the agent for both Bun local development and Cloudflare Workers
-export default agent.getWorkerExport();
+## 📖 Additional Resources
 
-```
+- [Circuit CLI](https://github.com/circuitorg/agents-cli) - Deploy and manage agents
+- [`demo-agent.ts`](./examples/demo-agent.ts) - Production-ready agent template
+- [`examples/kitchen-sink.ts`](./examples/kitchen-sink.ts) - Comprehensive SDK demo