Orbofi Agent SDK

The Orbofi Agent SDK enables developers to build AI agents that can interact with blockchain applications. This SDK provides a simple interface for integrating AI-powered natural language understanding with blockchain transactions.

Features

• 🧠 Natural Language Understanding: Use AI to interpret user queries into actionable intent
• 🔌 Plugin System: Extend functionality with custom plugins for different blockchain operations
• 🌐 Blockchain Integration: Built-in support for multiple chains via Wagmi
• 💰 Token Operations: Native token and ERC20 token transfers, balance checking
• 🔄 DEX Integration: Token swaps on decentralized exchanges
• ⚛️ React Support: First-class React integration with hooks
• 🖥️ Next.js Support: App Router compatible adapter with SSR safety

Installation

npm install @orbofi/agent-sdk

Quick Start

import { 
  OrbofiSDK, 
  OpenAIClient, 
  WagmiClient,
  TokenTransferPlugin,
  DexSwapPlugin
} from '@orbofi/agent-sdk';

// Initialize the SDK
const sdk = new OrbofiSDK({
  aiClient: new OpenAIClient('your-openai-api-key'),
  blockchainClient: new WagmiClient(),
  plugins: [
    new TokenTransferPlugin(),
    new DexSwapPlugin()
  ]
});

// Connect wallet
await sdk.blockchain.connect();

// Process a natural language query
const txHash = await sdk.processQuery('Transfer 100 USDC to 0x123...456');
console.log(`Transaction hash: ${txHash}`);

Using with Existing Wagmi Configuration

The SDK is designed to work seamlessly with existing Wagmi setups:

import { 
  OrbofiSDK, 
  OpenAIClient, 
  WagmiClient,
  TokenTransferPlugin,
  DexSwapPlugin
} from '@orbofi/agent-sdk';
import { configureChains, createConfig } from '@wagmi/core';
import { mainnet, optimism } from '@wagmi/core/chains';
import { publicProvider } from '@wagmi/core/providers/public';
import { MetaMaskConnector } from '@wagmi/core/connectors/metaMask';

// Your existing Wagmi configuration
const { chains, publicClient } = configureChains(
  [mainnet, optimism], 
  [publicProvider()]
);

const wagmiConfig = {
  chains,
  providers: [publicClient],
  connectors: [new MetaMaskConnector({ chains })],
  autoConnect: true,
};

// Initialize with your existing Wagmi config
const sdk = new OrbofiSDK({
  aiClient: new OpenAIClient('your-openai-api-key'),
  blockchainClient: new WagmiClient(wagmiConfig),
  plugins: [
    new TokenTransferPlugin(),
    new DexSwapPlugin()
  ],
  wagmiConfig, // Optionally store the config in the SDK
});

// Process using your existing Wagmi setup
const txHash = await sdk.processQuery('Swap 0.1 ETH for DAI');
console.log(`Transaction hash: ${txHash}`);

React Integration

import { useSDK } from '@orbofi/agent-sdk/adapters/react';
import { 
  OpenAIClient, 
  WagmiClient,
  TokenTransferPlugin,
  DexSwapPlugin
} from '@orbofi/agent-sdk';
// Import from wagmi (user's existing Wagmi React setup)
import { useConfig, useAccount } from 'wagmi';

function App() {
  // Get user's existing Wagmi configuration
  const wagmiConfig = useConfig();
  const { address, isConnected: wagmiConnected } = useAccount();
  
  // Convert user's Wagmi config to our SDK format
  const adaptWagmiConfig = () => {
    return {
      chains: wagmiConfig.chains,
      providers: [wagmiConfig.publicClient],
      connectors: wagmiConfig.connectors,
      autoConnect: true,
    };
  };

  // Use our SDK with the user's existing Wagmi config
  const { 
    isConnected, 
    walletAddress, 
    connect, 
    disconnect, 
    processQuery 
  } = useSDK({
    aiClient: new OpenAIClient('your-openai-api-key'),
    blockchainClient: new WagmiClient(adaptWagmiConfig()),
    plugins: [
      new TokenTransferPlugin(),
      new DexSwapPlugin()
    ],
    wagmiConfig: adaptWagmiConfig(),
    autoConnect: true
  });

  const handleQuery = async () => {
    try {
      const txHash = await processQuery('Swap 0.1 ETH for DAI');
      console.log(`Transaction hash: ${txHash}`);
    } catch (error) {
      console.error('Error processing query:', error);
    }
  };

  return (
    <div>
      {isConnected ? (
        <>
          <p>Connected: {walletAddress}</p>
          <button onClick={disconnect}>Disconnect</button>
          <button onClick={handleQuery}>Swap 0.1 ETH for DAI</button>
        </>
      ) : (
        <button onClick={connect}>Connect Wallet</button>
      )}
    </div>
  );
}

Next.js Integration

The SDK includes a dedicated adapter for Next.js with App Router support:

// app/layout.tsx
'use client';

import { OrbofiSDKProvider } from '@orbofi/agent-sdk/adapters/nextjs';
import { OpenAIClient } from '@orbofi/agent-sdk/ai/openai';
import { WagmiClient } from '@orbofi/agent-sdk/blockchain/wagmi';
import { TokenTransferPlugin } from '@orbofi/agent-sdk/plugins/tokenTransfer';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

// Create a React Query client
const queryClient = new QueryClient();

// SDK Configuration
const sdkConfig = {
  aiClient: new OpenAIClient(process.env.NEXT_PUBLIC_OPENAI_API_KEY || ''),
  blockchainClient: new WagmiClient(),
  plugins: [new TokenTransferPlugin()],
  autoConnect: false,
};

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <QueryClientProvider client={queryClient}>
          <OrbofiSDKProvider options={sdkConfig}>
            {children}
          </OrbofiSDKProvider>
        </QueryClientProvider>
      </body>
    </html>
  );
}

In your page components:

// app/page.tsx
'use client';

import { useOrbofiSDK } from '@orbofi/agent-sdk/adapters/nextjs';
import { useState } from 'react';

export default function Page() {
  const [query, setQuery] = useState('');
  const [result, setResult] = useState('');
  
  const { 
    processQuery, 
    connect, 
    disconnect,
    isConnected,
    walletAddress
  } = useOrbofiSDK();
  
  const handleSubmit = async (e) => {
    e.preventDefault();
    try {
      const txHash = await processQuery(query);
      setResult(`Transaction hash: ${txHash}`);
    } catch (error) {
      setResult(`Error: ${error.message}`);
    }
  };
  
  return (
    <div>
      <h1>Orbofi SDK with Next.js</h1>
      
      {isConnected ? (
        <div>
          <p>Connected: {walletAddress}</p>
          <button onClick={disconnect}>Disconnect</button>
          <form onSubmit={handleSubmit}>
            <input 
              value={query}
              onChange={(e) => setQuery(e.target.value)}
              placeholder="Enter your query"
            />
            <button type="submit">Submit</button>
          </form>
          {result && <div>{result}</div>}
        </div>
      ) : (
        <button onClick={connect}>Connect Wallet</button>
      )}
    </div>
  );
}

Creating Custom Plugins

You can extend the SDK's functionality by creating custom plugins:

import { Plugin, Action, Transaction } from '@orbofi/agent-sdk';

export class StakingPlugin implements Plugin {
  name = 'staking';
  description = 'Stake tokens for rewards';

  async execute(action: Action): Promise<Transaction> {
    // Validate inputs
    const { tokenAddress, amount } = action.params;
    
    // ... plugin implementation
    
    return {
      to: stakingContractAddress,
      data: encodedData,
      chainId: action.params.chainId || 1,
    };
  }
}

// Register the plugin
sdk.registerPlugin(new StakingPlugin());

API Reference

Core SDK

OrbofiSDK

• constructor(options: SDKOptions): Initialize the SDK with options including:
  • aiClient: AI client implementation
  • blockchainClient: Blockchain client implementation
  • plugins: Array of plugins to register
  • wagmiConfig: Optional Wagmi configuration to use with blockchain client
• registerPlugin(plugin: Plugin): Register a new plugin
• interpretQuery(query: string): Interpret a natural language query
• executeAction(action: Action): Execute an action using the appropriate plugin
• executeTransaction(transaction: Transaction): Execute a blockchain transaction
• processQuery(query: string): Process a query end-to-end (interpret + execute)

AI Clients

OpenAIClient

• constructor(apiKey: string): Initialize with OpenAI API key
• interpret(query: string, plugins: Plugin[]): Interpret a query

Blockchain Clients

WagmiClient

• constructor(wagmiConfig?: WagmiConfig): Initialize with optional Wagmi configuration
• connect(): Connect to a wallet
• disconnect(): Disconnect the wallet
• execute(transaction: Transaction): Execute a transaction
• isConnected(): Check if connected
• getAddress(): Get connected address

Plugins

TokenTransferPlugin

• Enables token transfers via ERC20 contracts
• Uses viem for proper transaction data encoding
• Supports different token decimals (default: 18)
• Example usage:

// Initialize the plugin
const tokenTransferPlugin = new TokenTransferPlugin();

// Create an action
const action = {
  pluginName: 'tokenTransfer',
  params: {
    tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
    recipientAddress: '0x1234567890123456789012345678901234567890',
    amount: '100', // 100 USDC
    decimals: 6, // USDC has 6 decimals
    chainId: 1, // Ethereum mainnet
  },
};

// Execute the action to get the transaction
const transaction = await sdk.executeAction(action);

// Send the transaction
const txHash = await sdk.blockchain.execute(transaction);

NativeTransferPlugin

• Enables native token transfers (ETH, MATIC, etc.)
• Uses viem for proper transaction data encoding
• Supports gas customization
• Example usage:

// Initialize the plugin
const nativeTransferPlugin = new NativeTransferPlugin();

// Create an action
const action = {
  pluginName: 'nativeTransfer',
  params: {
    recipientAddress: '0x1234567890123456789012345678901234567890',
    amount: '0.1', // 0.1 ETH
    chainId: 1, // Ethereum mainnet
    // Optional gas parameters
    maxFeePerGas: '30', // 30 gwei
    maxPriorityFeePerGas: '2', // 2 gwei
  },
};

// Execute the action to get the transaction
const transaction = await sdk.executeAction(action);

// Send the transaction
const txHash = await sdk.blockchain.execute(transaction);

DexSwapPlugin

• Enables token swaps on decentralized exchanges (Uniswap V2 compatible)
• Supports ETH -> Token, Token -> ETH, and Token -> Token swaps
• Uses viem for proper transaction data encoding
• Configurable slippage protection
• Example usage:

// Initialize the plugin
const dexSwapPlugin = new DexSwapPlugin();

// Create an action
const action = {
  pluginName: 'dexSwap',
  params: {
    fromToken: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH
    toToken: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
    amount: '0.1', // 0.1 ETH
    slippage: '1', // 1% slippage
    chainId: 1, // Ethereum mainnet
    decimals: 18, // ETH has 18 decimals
  },
};

// Execute the action to get the transaction
const transaction = await sdk.executeAction(action);

// Send the transaction
const txHash = await sdk.blockchain.execute(transaction);

Services

AccountService

• Provides utility functions for querying blockchain data
• Check native token balances, token balances, and transaction counts
• Example usage:

// Initialize the service with RPC URLs (optional)
const accountService = new AccountService({
  1: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY',
});

// Check native token balance
const ethBalance = await accountService.getNativeBalance('0x1234...5678');
console.log(`ETH Balance: ${ethBalance} ETH`);

// Check token balance
const usdcBalance = await accountService.getTokenBalance(
  '0x1234...5678', // address
  '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC contract
  1 // Ethereum mainnet
);
console.log(`USDC Balance: ${usdcBalance} USDC`);

// Check balances for common tokens
const balances = await accountService.getCommonTokenBalances('0x1234...5678');
console.log(balances); // { Native: '1.5', USDC: '100', USDT: '50', ... }

// Estimate gas for a transaction
const gas = await accountService.estimateGas({
  to: '0x1234...5678',
  data: '0x',
  value: '1000000000000000000', // 1 ETH
});
console.log(`Estimated gas: ${gas.toString()}`);