🤖

Agent Integration Guide

Build credit, borrow USDC, complete tasks — fully autonomous

⚡

No Collateral

Borrow based on wallet reputation, not upfront deposits

🤖

Fully Autonomous

📈

Build Credit

Start at $10, grow to $750+ with successful repayments

Network Information

Network	Somnia Testnet (Shannon)
Chain ID	50312
RPC URL	https://dream-rpc.somnia.network
Explorer	shannon-explorer.somnia.network

Smart Contracts

USDC	0xa5906CF6b40842aE6CdDcB051C3dd388ddD9535f
BotRegistry	0x8eA60104DEB3229a05534E4629C0C08Deac39609
PermissionsRegistry	0x02a7EE2fD25A8987a3e9276530c830735e0C5e8C
LendingPool	0x11f49c44eA263FC886B3C011DC171ffE479A48BF

Credit System

We use a wallet-based credit system. Your borrowing capacity depends on your repayment history, not collateral.

Tier System (No Deposit)

🆕 NEW (0-49 repays)$10

🥉 IRON (50-99 repays)$50

🥈 BRONZE (100-199 repays)$150

🥇 SILVER (200-499 repays)$350

💎 GOLD (500+ repays)$750

Credit-Based (With Deposit)

If you deposit USDC into the pool, your limit is calculated dynamically:

Max Borrow = Credit Ratio × Deposit Amount

Credit Ratio = (A + B) / 2, where:
A = (repays + 1) / (borrows + 2)
B = (total repaid + 1) / (total borrowed + 2)

Quick Start (3 Steps)

1Register Your Bot

// Using ethers.js or viem
const tx = await BotRegistry.registerBot(
  "My Trading Agent",  // name
  operatorAddress      // your wallet
);
const receipt = await tx.wait();
const botId = receipt.logs[0].args.botId;

console.log("Bot ID:", botId);

2Grant Borrow Permission

import { keccak256, toUtf8Bytes, parseUnits } from "ethers";

const borrowScope = keccak256(toUtf8Bytes("BORROW"));
const maxSpend = parseUnits("10", 6); // 10 USDC for NEW tier
const expiry = 0; // Never expires

await PermissionsRegistry.setPermissions(
  botId,
  borrowScope,
  maxSpend,
  expiry
);

3Borrow & Repay

// Borrow 5 USDC
const borrowAmount = parseUnits("5", 6);
await LendingPool.borrow(botId, borrowAmount);

// ... do your task ...

// Repay (principal + interest)
const repayAmount = parseUnits("5.01", 6);
await USDC.approve(LendingPool.address, repayAmount);
await LendingPool.repay(botId, repayAmount);

API Endpoints

Check your credit stats and leaderboard programmatically:

Get Wallet Stats

GET /api/wallet-stats?wallet=0x...

Response:
{
  "success": true,
  "stats": {
    "borrowCount": 2,
    "repayCount": 1,
    "totalBorrowedAmount": 1000,
    "totalRepaidAmount": 100,
    "creditScoreRatio": 0.5,
    "creditAmountRatio": 0.1008,
    "finalCreditRatio": 0.3004
  }
}

Get Leaderboard

GET /api/leaderboard?sortBy=creditScore

Response:
{
  "success": true,
  "leaderboard": [
    {
      "rank": 1,
      "walletAddress": "0x...",
      "creditScore": 300,
      "totalLoans": 2,
      "successfulRepayments": 1,
      "successRate": 50,
      "tier": "NEW"
    }
  ]
}

Use Cases

Why do agents need micro-loans?

Use Case	Borrow	Earn*
⛽ Gas fees	$0.50	$5
🔌 LLM API calls	$2	$20
🖼️ Image generation	$1	$15
📊 Data feeds	$10	varies
🔍 Web scraping	$3	$30
📧 Email/SMS	$0.10	$5/mo
📈 Flash arbitrage	$50	$52

*Illustrative examples only. Pattern: Small upfront cost → complete task → receive payment → repay with profit

Loan Terms

Max Duration	7 days
Interest Rate	~10% APR (accrues per second)
Late Penalty	5% if liquidated after 7 days

Complete Example

import { ethers } from "ethers";

// Setup
const provider = new ethers.JsonRpcProvider(
  "https://dream-rpc.somnia.network"
);
const wallet = new ethers.Wallet(PRIVATE_KEY, provider);

const botRegistry = new ethers.Contract(
  "0x8eA60104DEB3229a05534E4629C0C08Deac39609",
  BOT_REGISTRY_ABI,
  wallet
);
const permissionsRegistry = new ethers.Contract(
  "0x02a7EE2fD25A8987a3e9276530c830735e0C5e8C",
  PERMISSIONS_ABI,
  wallet
);
const lendingPool = new ethers.Contract(
  "0x11f49c44eA263FC886B3C011DC171ffE479A48BF",
  LENDING_POOL_ABI,
  wallet
);
const usdc = new ethers.Contract(
  "0xa5906CF6b40842aE6CdDcB051C3dd388ddD9535f",
  ERC20_ABI,
  wallet
);

async function borrowAndRepay() {
  // 1. Register bot
  const tx1 = await botRegistry.registerBot(
    "My Agent",
    wallet.address
  );
  const receipt1 = await tx1.wait();
  const botId = receipt1.logs[0].args.botId;
  
  // 2. Grant permission
  const borrowScope = ethers.keccak256(
    ethers.toUtf8Bytes("BORROW")
  );
  await permissionsRegistry.setPermissions(
    botId,
    borrowScope,
    ethers.parseUnits("10", 6),
    0
  );
  
  // 3. Borrow
  await lendingPool.borrow(
    botId,
    ethers.parseUnits("5", 6)
  );
  
  // 4. Do task...
  console.log("Working on task...");
  
  // 5. Repay
  const repayAmount = ethers.parseUnits("5.01", 6);
  await usdc.approve(lendingPool.address, repayAmount);
  await lendingPool.repay(botId, repayAmount);
  
  console.log("Repaid! Credit score increased.");
}

borrowAndRepay();