@circuitorg/agent-sdk 1.2.1 → 1.2.4

package/README.md

@@ -13,6 +13,7 @@ A simplified TypeScript SDK for building automated agents to deploy on Circuit.
   - [🚀 Quick Start](#-quick-start)
     - [Install the SDK](#install-the-sdk)
     - [Create Your First Agent](#create-your-first-agent)
+      - [Required Asset setup](#required-asset-setup)
   - [🎯 Core Concepts](#-core-concepts)
     - [The AgentContext Object](#the-agentcontext-object)
     - [Run/Stop Function Requirements](#runstop-function-requirements)
@@ -23,6 +24,12 @@ A simplified TypeScript SDK for building automated agents to deploy on Circuit.
   - [📈 Polymarket Prediction Markets](#-polymarket-prediction-markets)
     - [Place Market Orders](#place-market-orders)
     - [Redeem Positions](#redeem-positions)
+  - [Hyperliquid Perpetuals Trading](#hyperliquid-perpetuals-trading)
+    - [Account Information](#account-information)
+    - [Place Orders](#place-orders)
+    - [Order Management](#order-management)
+    - [Transfer Between Accounts](#transfer-between-accounts)
+  - [📊 Transaction History](#-transaction-history)
   - [🚀 Sign \& Send Transactions](#-sign--send-transactions)
     - [Ethereum (any EVM chain)](#ethereum-any-evm-chain)
     - [Solana](#solana)
@@ -65,9 +72,27 @@ Every agent receives a single `AgentContext` object that provides:
 - `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)
+- `agent.transactions()` - Get transaction history with asset changes
 
 **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.
 
+
+#### Required Asset setup
+> Note: For native tokens, use the following null addresses for solana/ethereum
+```toml
+// Requiring 1 SOL
+[[requiredAssets]]
+network = "solana"
+address = "11111111111111111111111111111111"
+minimumAmount = "1000000000"
+
+// Requiring 1 ETH
+[[requiredAssets]]
+network = "ethereum:<chainId>"
+address = "0x0000000000000000000000000000000000000000"
+minimumAmount = "1000000000000000000"
+```
+
 ```typescript
 import { Agent, AgentContext } from "@circuitorg/agent-sdk";
 
@@ -121,6 +146,7 @@ Every agent function receives a single `AgentContext` object that contains:
 - `agent.swidge` - Cross-chain swap operations
 - `agent.signAndSend()` - Sign and broadcast transactions
 - `agent.signMessage()` - Sign messages on EVM
+- `agent.transactions()` - Get transaction history with asset changes
 
 ### Run/Stop Function Requirements
 
@@ -215,6 +241,8 @@ Built-in Swidge integration for seamless cross-chain token swaps and bridges.
 ### 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
 
+> **Bulk Execution:** `execute()` accepts both single quotes and arrays. Pass an array to execute multiple swaps in parallel: `await agent.swidge.execute([quote1.data, quote2.data])` returns an array of results.
+
 ```typescript
 async function run(agent: AgentContext): Promise<void> {
   // 1. Get quote
@@ -305,6 +333,151 @@ async function stop(agent: AgentContext): Promise<void> {
 }
 ```
 
+## Hyperliquid Perpetuals Trading
+
+Trade perpetual futures on Hyperliquid DEX with leverage.
+
+### Account Information
+
+```typescript
+async function run(agent: AgentContext): Promise<void> {
+  // Check balances
+  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}`);
+  }
+
+  // View open positions
+  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(`Unrealized PnL: $${pos.unrealizedPnl}`);
+    }
+  }
+}
+```
+
+### Place Orders
+
+```typescript
+async function run(agent: AgentContext): Promise<void> {
+  // Market order
+  const order = await agent.platforms.hyperliquid.placeOrder({
+    symbol: "BTC-USD",
+    side: "buy",
+    size: 0.0001,
+    price: 110000,  // Acts as slippage limit for market orders
+    market: "perp",
+    type: "market"
+  });
+
+  if (order.success && order.data) {
+    await agent.log(`Order ${order.data.orderId}: ${order.data.status}`);
+  } else {
+    await agent.log(order.error, { error: true });
+  }
+}
+```
+
+### Order Management
+
+```typescript
+async function run(agent: AgentContext): Promise<void> {
+  // Get open orders
+  const openOrders = await agent.platforms.hyperliquid.openOrders();
+
+  // Get specific order details
+  const order = await agent.platforms.hyperliquid.order("12345");
+
+  // Cancel an order
+  const result = await agent.platforms.hyperliquid.deleteOrder("12345", "BTC-USD");
+
+  // View historical orders
+  const history = await agent.platforms.hyperliquid.orders();
+
+  // Check order fills
+  const fills = await agent.platforms.hyperliquid.orderFills();
+}
+```
+
+### Transfer Between Accounts
+
+```typescript
+async function run(agent: AgentContext): Promise<void> {
+  // 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");
+  }
+}
+```
+
+## 📊 Transaction History
+
+Get a list of asset changes for all confirmed transactions during your session. This is useful for tracking what assets have moved in and out of the agent's wallet.
+
+> **Note:** The system needs to index new transactions, so there may be a slight delay between when you execute a transaction and when the resulting asset changes are returned in this method. Make sure you are taking that into consideration if dealing with assets the agent just transacted with.
+
+```typescript
+async function run(agent: AgentContext): Promise<void> {
+  // Get all transaction history for this session
+  const result = await agent.transactions();
+
+  if (result.success && result.data) {
+    await agent.log(`Found ${result.data.length} asset changes`);
+
+    // Filter for outgoing transfers
+    const outgoing = result.data.filter(
+      (change) => change.from === agent.sessionWalletAddress
+    );
+    await agent.log(`Outgoing transfers: ${outgoing.length}`);
+
+    // Calculate total USD value (where price data is available)
+    const totalUsd = result.data
+      .filter((c) => c.tokenUsdPrice)
+      .reduce((sum, c) => {
+        const amount = parseFloat(c.amount);
+        const price = parseFloat(c.tokenUsdPrice!);
+        return sum + amount * price;
+      }, 0);
+    await agent.log(`Total USD value: $${totalUsd.toFixed(2)}`);
+
+    // View specific transaction details
+    for (const change of result.data) {
+      await agent.log(`${change.network}: ${change.from} → ${change.to}`);
+      await agent.log(`  Amount: ${change.amount} ${change.tokenType}`);
+      if (change.token) {
+        await agent.log(`  Token: ${change.token}`);
+      }
+      await agent.log(`  Tx: ${change.transactionHash}`);
+      await agent.log(`  Time: ${change.timestamp}`);
+    }
+  } else {
+    await agent.log(result.error || "Failed to fetch transactions", { error: true });
+  }
+}
+```
+
+**AssetChange Structure:**
+
+Each asset change in the response contains:
+- `network` - Network identifier (e.g., `"ethereum:1"`, `"solana"`)
+- `transactionHash` - Transaction hash
+- `from` - Sender address
+- `to` - Recipient address
+- `amount` - Amount transferred (as string to preserve precision)
+- `token` - Token contract address (`null` for native tokens)
+- `tokenId` - Token ID for NFTs (`null` for fungible tokens)
+- `tokenType` - Token type (e.g., `"native"`, `"ERC20"`, `"ERC721"`)
+- `tokenUsdPrice` - Token price in USD at time of transaction (`null` if unavailable)
+- `timestamp` - Transaction timestamp
+
 ## 🚀 Sign & Send Transactions
 
 ### Ethereum (any EVM chain)