@circuitorg/agent-sdk 1.2.3 → 1.3.0

package/README.md

@@ -24,6 +24,11 @@ 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 Trading](#hyperliquid-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)
@@ -328,6 +333,115 @@ async function stop(agent: AgentContext): Promise<void> {
 }
 ```
 
+## Hyperliquid Trading
+
+Trade perpetual futures (with leverage) and spot markets on Hyperliquid DEX.
+
+**Market Types:**
+- **Perp**: Perpetual futures trading with leverage (use `market: "perp"` in order parameters)
+- **Spot**: Spot trading (use `market: "spot"` in order parameters)
+
+**Asset Naming for Spot:**
+- Non-Hypercore-native assets use "Unit" prefix: `UBTC` (Unit BTC), `UETH` (Unit ETH)
+- Example: To trade BTC spot, use symbol `UBTC-USDC`
+
+### 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> {
+  // Perp market order
+  const perpOrder = 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 (perpOrder.success && perpOrder.data) {
+    await agent.log(`Perp Order ${perpOrder.data.orderId}: ${perpOrder.data.status}`);
+  } else {
+    await agent.log(perpOrder.error, { error: true });
+  }
+
+  // Spot market order (for non-Hypercore-native assets like BTC)
+  const spotOrder = await agent.platforms.hyperliquid.placeOrder({
+    symbol: "UBTC-USDC",  // Unit BTC
+    side: "buy",
+    size: 0.0001,
+    price: 110000,
+    market: "spot",  // Changed to spot
+    type: "market"
+  });
+
+  if (spotOrder.success && spotOrder.data) {
+    await agent.log(`Spot Order ${spotOrder.data.orderId}: ${spotOrder.data.status}`);
+  } else {
+    await agent.log(spotOrder.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.