Cambrian Agent Kit Ecosystem Tutorial

Overview

Cambrian Agent Kit is a developer SDK to build autonomous AI agents and agentic chatbots on Sei. It lets you interact with DeFi protocols (Takara, Silo, Citrex, Symphony), manage SEI tokens and NFTs, and integrate AI workflows. This tutorial shows how to set up the kit, run your first agent, and adapt it to real DeFi use cases. For details about how the kit works internally, see the Cambrian Agent Kit documentation.

Supported features

For blockchain agent development, you can use the kit to:

Manage ERC-20 and ERC-721 tokens on Sei
Interact with the Sei DeFi ecosystem
Swap tokens through the Symphony aggregator
Add and remove liquidity with DragonSwap
Lend and borrow with the Takara protocol
Stake and unstake SEI tokens with Silo
Build AI agents with LangChain and LangGraph

What this guide teaches you:

Install and configure the kit, and connect your wallet and API keys.
Understand the core concepts: agents, supported protocols, and how these components fit together.
Run end-to-end code examples to:
- Check your token and NFT balances.
- Swap tokens with Symphony.
- Stake and unstake SEI in Silo.
- Lend and borrow with Takara.
- Trade perpetuals with Citrex.
Adapt the kit for your own protocol or workflow.

Example use cases:

Autonomous DeFi agents: Agents that can automatically manage token positions, provide liquidity, or take part in lending
AI-assisted wallets: Conversational interfaces for blockchain operations
Financial assistant agents: AI agents that can analyze market conditions and execute trades
Portfolio management agents: Agents that manage crypto asset portfolios automatically

Hands-on tutorial

1. Prerequisites

Node.js and npm installed
A private key for your Sei wallet
An OpenAI API key (for AI integrations)
Enough SEI in your wallet to pay for gas

2. Project setup

git clone https://github.com/CambrianAgents/sei-agent-kit.git
cd sei-agent-kit
cp .env.example .env   # Fill in your keys!
npm install

Edit .env:

OPENAI_API_KEY=your_openai_api_key
SEI_PRIVATE_KEY=your_wallet_private_key
RPC_URL=https://evm-rpc.sei-apis.com

Never share your private key. Your private key controls your funds.

3. Running your first agent

npm run test

This is the command output and a sample chat with the Cambrian Agent:

npm run test

> sei-agent-kit@0.0.3 test
> tsx test/index.ts

  ███████╗███████╗██╗      █████╗  ██████╗ ███████╗███╗   ██╗████████╗    ██╗  ██╗██╗████████╗
  ██╔════╝██╔════╝██║     ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝    ██║ ██╔╝██║╚══██╔══╝
  ███████╗█████╗  ██║     ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║       █████╔╝ ██║   ██║
  ╚════██║██╔══╝  ██║     ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║       ██╔═██╗ ██║   ██║
  ███████║███████╗██║     ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║       ██║  ██╗██║   ██║
  ╚══════╝╚══════╝╚═╝     ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝       ╚═╝  ╚═╝╚═╝   ╚═╝

Starting chat with the Cambrian Agent... Type 'bye' to end.

You: Hey, I would like to swap some sei to usdc.

Cambrian Agent: Sure thing! How much SEI would you like to swap for USDC? Let me know, and I'll get the magic started! ✨

-----------------------------------

You: I would like to swap 0.2 sei for some usdc

Cambrian Agent:

-----------------------------------

Getting token address for USDC...
Swapping 0.2 0x0 to 0x3894085ef7ff0f0aedf52e2a2704928d1ec074f1...
Querying balance of SEI for 0xa0E377AEaF32024f949667f56e7fa4409AFE6b8D...

Cambrian Agent: {"status":"success","result":"0x638d08db41e9ed370504861b4d2ced693869c45136bfdba2d92e8aed43c080fa","fromToken":"SEI","toToken":"USDC","amount":"0.2"}

-----------------------------------

Cambrian Agent: Your swap of 0.2 SEI to USDC was successful! 🎉 The transaction hash is `0x638d08db41e9ed370504861b4d2ced693869c45136bfdba2d92e8aed43c080fa`. If you have any more magical swaps or questions, just let me know! 🪄

-----------------------------------

You: Give me my new balances after the previous transaction

Cambrian Agent:

-----------------------------------

Getting token address for SEI...
Getting token address for USDC...
Querying balance of 0x3894085ef7ff0f0aedf52e2a2704928d1ec074f1 for 0xa0E377AEaF32024f949667f56e7fa4409AFE6b8D...
Querying balance of 0x67da7010c6c231ad620e3940e707adb6c1a08f23 for 0xa0E377AEaF32024f949667f56e7fa4409AFE6b8D...

Cambrian Agent: {"status":"success","balance":"0","token":{"ticker":"SEI"}}

-----------------------------------

Cambrian Agent: After the swap, your new balances are:

- SEI: 0 SEI (Looks like you've spent it all!)
- USDC: 0.147866 USDC

If you need anything else, just give me a shout! 📢

-----------------------------------

You: bye

About the transaction:

SEI address: 0x0 represents the native SEI token in the agent kit.
Transaction hash: You can verify it on Seiscan.
Transaction fees: Fees are calculated automatically and deducted from your balance.

4. Explore core features & protocols

a) Check token balance with error handling

import { SeiAgentKit } from './src/agent';

async function checkBalanceWithErrorHandling() {
  try {
    const agent = new SeiAgentKit(process.env.SEI_PRIVATE_KEY, 'openai');

    // Check SEI balance
    const balance = await agent.getERC20Balance(); // SEI or specify contract address
    console.log('Your SEI Balance:', balance);

    // Validate balance before proceeding
    if (parseFloat(balance) < 0.01) {
      console.warn('⚠️ Low SEI balance. You may need more SEI for gas fees.');
    }
  } catch (error) {
    console.error('Error checking balance:', error.message);

    // Handle specific error types
    if (error.message.includes('insufficient funds')) {
      console.log('💡 Tip: Add more SEI to your wallet');
    } else if (error.message.includes('network')) {
      console.log('💡 Tip: Check your RPC connection');
    }
  }
}

b) Safe token swapping with Symphony

async function safeSwap() {
  try {
    const agent = new SeiAgentKit(process.env.SEI_PRIVATE_KEY, 'openai');

    // Validate inputs
    const amount = '1.0';
    const fromToken = '0x0'; // SEI
    const toToken = 'usdc_contract_address';

    // Check balance first
    const balance = await agent.getERC20Balance();
    if (parseFloat(balance) < parseFloat(amount)) {
      throw new Error('Insufficient balance for swap');
    }

    // Execute swap with error handling
    const tx = await agent.swap(amount, fromToken, toToken);
    console.log('Swap TX:', tx);

    // Verify transaction
    if (tx.status === 'success') {
      console.log('✅ Swap successful!');
      console.log('🔗 Transaction hash:', tx.result);
    } else {
      console.error('❌ Swap failed:', tx.error);
    }
  } catch (error) {
    console.error('Swap error:', error.message);

    // Handle common swap errors
    if (error.message.includes('slippage')) {
      console.log('💡 Tip: Try increasing slippage tolerance');
    } else if (error.message.includes('liquidity')) {
      console.log('💡 Tip: Insufficient liquidity for this pair');
    }
  }
}

Swap safety tips:

In the agent kit, use 0x0 as the address for the native SEI token.
Always set an appropriate slippage tolerance.
Monitor the price impact before large swaps.

c) Liquid staking with Silo protocol

async function stakingWithSilo() {
  try {
    const agent = new SeiAgentKit(process.env.SEI_PRIVATE_KEY, 'openai');

    // Stake SEI and receive iSEI
    const stakeAmount = '2.0';
    const stakeTx = await agent.stake(stakeAmount);
    console.log('Staked TX:', stakeTx);

    if (stakeTx.status === 'success') {
      console.log('✅ Successfully staked SEI!');
      console.log('📄 You received iSEI tokens representing your stake');
      console.log('💰 Your rewards will auto-compound over time');
    }

    // Later, unstake if needed
    const unstakeAmount = '1.0';
    const unstakeTx = await agent.unstake(unstakeAmount);
    console.log('Unstaked TX:', unstakeTx);
  } catch (error) {
    console.error('Staking error:', error.message);

    if (error.message.includes('minimum amount')) {
      console.log('💡 Tip: Check minimum staking amount requirements');
    }
  }
}

Silo staking details:

iSEI token: Represents your staked SEI plus auto-compounded rewards
No unbonding period: Immediate liquidity, unlike traditional staking
5% fee: Annual management fee of 5% on rewards
MEV benefits: Validators share MEV profits with stakers

d) Lending/borrowing with Takara protocol

async function takaraLending() {
  try {
    const agent = new SeiAgentKit(process.env.SEI_PRIVATE_KEY, 'openai');

    // Mint tTokens (supply liquidity)
    const mintTx = await agent.mintTakara('USDC', '10');
    console.log('Mint Takara:', mintTx);

    if (mintTx.status === 'success') {
      console.log('✅ Successfully supplied USDC to Takara');
      console.log('💰 You are now earning interest on your supply');
    }

    // Borrow against collateral
    const borrowTx = await agent.borrowTakara('USDC', '5');
    console.log('Borrow Takara:', borrowTx);

    if (borrowTx.status === 'success') {
      console.log('✅ Successfully borrowed USDC from Takara');
      console.log('⚠️ Remember to monitor your collateral ratio');
    }

    // Repay borrowed amount
    const repayTx = await agent.repayTakara('USDC', '5');
    console.log('Repay Takara:', repayTx);
  } catch (error) {
    console.error('Takara error:', error.message);

    if (error.message.includes('collateral')) {
      console.log('💡 Tip: Add more collateral to maintain healthy ratio');
    } else if (error.message.includes('liquidity')) {
      console.log('💡 Tip: Insufficient liquidity in the pool');
    }
  }
}

e) Perpetual trading with Citrex Markets

async function citrexTrading() {
  try {
    const agent = new SeiAgentKit(process.env.SEI_PRIVATE_KEY, 'openai');

    // Deposit margin
    const depositAmount = '10';
    const depositTx = await agent.citrexDeposit(depositAmount);
    console.log('Citrex Deposit:', depositTx);

    if (depositTx.status === 'success') {
      console.log('✅ Successfully deposited margin to Citrex');
      console.log('⚡ You can now trade perpetuals with up to 20x leverage');
    }

    // Check available products
    const products = await agent.citrexGetProducts();
    console.log('Available Products:', products);

    // Withdraw margin when done
    const withdrawTx = await agent.citrexWithdraw('5');
    console.log('Citrex Withdraw:', withdrawTx);
  } catch (error) {
    console.error('Citrex error:', error.message);

    if (error.message.includes('margin')) {
      console.log('💡 Tip: Ensure sufficient margin for your positions');
    } else if (error.message.includes('leverage')) {
      console.log('💡 Tip: Reduce leverage to lower risk');
    }
  }
}

For more advanced protocol integrations, see /tools/.

Error handling & troubleshooting

Common error types

Error handling examples:

// Robust error handling for all operations
async function robustAgentOperation() {
  const agent = new SeiAgentKit(process.env.SEI_PRIVATE_KEY, 'openai');

  try {
    // Operation code here
  } catch (error) {
    // Network errors
    if (error.code === 'NETWORK_ERROR') {
      console.log('🌐 Network issue - retrying in 5 seconds...');
      await new Promise((resolve) => setTimeout(resolve, 5000));
      // Implement retry logic
    }

    // Insufficient funds
    if (error.message.includes('insufficient funds')) {
      console.log('💰 Insufficient funds for this operation');
      const balance = await agent.getERC20Balance();
      console.log('Current balance:', balance);
    }

    // Gas estimation errors
    if (error.message.includes('gas')) {
      console.log('⛽ Gas estimation failed - transaction may fail');
      console.log('Try reducing transaction amount or increasing gas limit');
    }

    // Contract-specific errors
    if (error.message.includes('revert')) {
      console.log('📋 Smart contract reverted the transaction');
      console.log('Check transaction parameters and try again');
    }
  }
}

Transaction monitoring

async function monitorTransaction(txHash: string) {
  const maxRetries = 30; // 30 seconds max wait
  let retries = 0;

  while (retries < maxRetries) {
    try {
      // Check transaction status
      const receipt = await checkTransactionStatus(txHash);

      if (receipt.status === 'success') {
        console.log('✅ Transaction confirmed!');
        return receipt;
      } else if (receipt.status === 'failed') {
        console.log('❌ Transaction failed');
        return receipt;
      }

      // Wait and retry
      await new Promise((resolve) => setTimeout(resolve, 1000));
      retries++;
    } catch (error) {
      console.log(`⏳ Waiting for confirmation... (${retries}/${maxRetries})`);
      retries++;
      await new Promise((resolve) => setTimeout(resolve, 1000));
    }
  }

  console.log('⏰ Transaction timeout - check manually on Seiscan');
}

Troubleshooting guide

Issue	Cause	Solution
”Insufficient funds”	Low SEI balance	Add more SEI to your wallet
”Transaction failed”	Gas estimation error	Reduce the transaction amount
”Network error”	RPC connection issue	Check the RPC URL in `.env`
”Slippage too high”	Price moved during swap	Increase the slippage tolerance
”Invalid private key”	Incorrect key format	Check the private key format

Debug commands:

# Check network connection
curl -X POST https://evm-rpc.sei-apis.com \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

# Verify wallet balance
# Use Seiscan: https://seiscan.io/

5. Advanced features & customization

Multi-protocol strategy example

async function deFiStrategy() {
  const agent = new SeiAgentKit(process.env.SEI_PRIVATE_KEY, 'openai');

  try {
    // 1. Swap SEI for USDC via Symphony
    console.log('Step 1: Swapping SEI for USDC...');
    const swapTx = await agent.swap('10', '0x0', 'usdc_address');

    // 2. Supply USDC to Takara for lending
    console.log('Step 2: Supplying USDC to Takara...');
    const supplyTx = await agent.mintTakara('USDC', '5');

    // 3. Stake remaining SEI via Silo
    console.log('Step 3: Staking SEI via Silo...');
    const stakeTx = await agent.stake('5');

    // 4. Monitor positions
    console.log('Step 4: Monitoring positions...');
    const balance = await agent.getERC20Balance();

    console.log('✅ Multi-protocol strategy executed successfully!');
    console.log('📊 Final balance:', balance);
  } catch (error) {
    console.error('Strategy failed:', error.message);
    // Implement rollback logic if needed
  }
}

Monitoring & alerts:

// Set up monitoring for your agent
async function setupMonitoring() {
  const agent = new SeiAgentKit(process.env.SEI_PRIVATE_KEY, 'openai');

  // Monitor balance changes
  setInterval(async () => {
    const balance = await agent.getERC20Balance();
    if (parseFloat(balance) < 1.0) {
      console.warn('⚠️ Low balance alert:', balance);
      // Send alert to your monitoring system
    }
  }, 60000); // Check every minute

  // Monitor failed transactions
  agent.on('transactionFailed', (error) => {
    console.error('Transaction failed:', error);
    // Log to monitoring system
  });
}

Custom protocol integration

To extend the Cambrian Agent Kit for your own protocol, follow the Cambrian Agents Plugin Guide. This repository explains how to add plugins to the agent kit so that it can support your protocol.

​Overview

​Supported features

​What this guide teaches you:

​Hands-on tutorial

​1. Prerequisites

​2. Project setup

​3. Running your first agent

​4. Explore core features & protocols

​a) Check token balance with error handling

​b) Safe token swapping with Symphony

​c) Liquid staking with Silo protocol

​d) Lending/borrowing with Takara protocol

​e) Perpetual trading with Citrex Markets

​Error handling & troubleshooting

​Common error types

​Transaction monitoring

​Troubleshooting guide

​5. Advanced features & customization

​Multi-protocol strategy example

​Monitoring & alerts:

​Custom protocol integration

Overview

Supported features

What this guide teaches you:

Hands-on tutorial

1. Prerequisites

2. Project setup

3. Running your first agent

4. Explore core features & protocols

a) Check token balance with error handling

b) Safe token swapping with Symphony

c) Liquid staking with Silo protocol

d) Lending/borrowing with Takara protocol

e) Perpetual trading with Citrex Markets

Error handling & troubleshooting

Common error types

Transaction monitoring

Troubleshooting guide

5. Advanced features & customization

Multi-protocol strategy example

Monitoring & alerts:

Custom protocol integration