Installation

Complete setup guide for the AGIRAILS SDK.

What You'll Learn

By the end of this guide, you'll have:

• Installed the AGIRAILS SDK
• Configured your development environment
• Obtained ETH and USDC (testnet or mainnet)
• Verified everything works

Time required: 10 minutes

---

Quick Reference

Component	Requirement
Node.js	16+
TypeScript	5.2+ (recommended)
ethers.js	v6 (auto-installed)
Python	3.9+ (AGIRAILS Python SDK)
Network	Base Mainnet or Base Sepolia

---

Step 1: Install SDK

Latest Version

The AGIRAILS SDK v2.2.0 is live on npm and PyPI with mainnet support.

npm install @agirails/sdk

Python?

Install AGIRAILS Python SDK from PyPI:

pip install agirails

See Quick Start for Python snippets.

ethers.js v6

AGIRAILS SDK uses ethers.js v6. If migrating from v5:

• ethers.utils.parseUnits() → ethers.parseUnits() or parseUnits()
• ethers.utils.formatUnits() → ethers.formatUnits() or formatUnits()
• new ethers.providers.JsonRpcProvider() → new ethers.JsonRpcProvider()
• See ethers v6 migration guide

From Source (Optional)

TypeScript

For development or latest features:

git clone https://github.com/agirails/sdk-js.git
cd sdk-js
npm install && npm run build && npm link

Then in your project:

npm link @agirails/sdk

Python

For development or latest features:

git clone https://github.com/agirails/sdk-python.git
cd sdk-python
pip install -e .

---

Step 2: Configure TypeScript

Add to tsconfig.json:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "resolveJsonModule": true
  }
}

---

Step 3: Environment Setup

Create .env:

.env

# Your wallet private key (starts with 0x)
PRIVATE_KEY=0x1234567890abcdef...

# RPC URL (optional - defaults to public Base Sepolia RPC)
RPC_URL=https://sepolia.base.org

Security

Never commit private keys to version control.

.gitignore

.env
.env.local

Load in your code:

import 'dotenv/config';

---

Step 4: Get Tokens

Option A: Testnet (Recommended for Development)

Get Base Sepolia ETH

ETH is required for gas fees:

1. Visit Coinbase Faucet
2. Connect your wallet
3. Request Base Sepolia ETH
4. Wait ~30 seconds

Get Mock USDC

Mint mock USDC tokens:

TypeScript

mint-usdc.ts

import { ethers, parseUnits } from 'ethers';
import 'dotenv/config';

const provider = new ethers.JsonRpcProvider('https://sepolia.base.org');
const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);

const usdc = new ethers.Contract(
  '0x444b4e1A65949AB2ac75979D5d0166Eb7A248Ccb',
  ['function mint(address to, uint256 amount) public'],
  wallet
);

// Mint 1000 USDC (6 decimals for USDC)
const tx = await usdc.mint(wallet.address, parseUnits('1000', 6));
await tx.wait();
console.log('Minted 1000 USDC');

Python

mint_usdc.py

import asyncio
import os
from dotenv import load_dotenv
from eth_account import Account
from web3 import Web3

load_dotenv()

async def mint_usdc():
    w3 = Web3(Web3.HTTPProvider("https://sepolia.base.org"))
    account = Account.from_key(os.environ["PRIVATE_KEY"])

    usdc = w3.eth.contract(
        address="0x444b4e1A65949AB2ac75979D5d0166Eb7A248Ccb",
        abi=[{"name": "mint", "type": "function", "inputs": [
            {"name": "to", "type": "address"},
            {"name": "amount", "type": "uint256"}
        ]}]
    )

    tx = usdc.functions.mint(account.address, 1_000 * 1_000_000).build_transaction({
        "from": account.address,
        "nonce": w3.eth.get_transaction_count(account.address),
        "gas": 120_000,
        "gasPrice": w3.eth.gas_price,
    })
    signed = account.sign_transaction(tx)
    tx_hash = w3.eth.send_raw_transaction(signed.rawTransaction)
    w3.eth.wait_for_transaction_receipt(tx_hash)
    print("Minted 1000 USDC:", tx_hash.hex())

if __name__ == "__main__":
    asyncio.run(mint_usdc())

No Public Mint?

If the Mock USDC contract doesn't have a public mint, contact us on Discord.

Option B: Mainnet (Production)

Transaction Limit

Mainnet transactions are limited to $1,000 until security audit is completed.

Get Base Mainnet ETH

ETH is required for gas fees (~$0.001 per transaction):

• Bridge from Ethereum: Base Bridge
• Buy directly: Coinbase, Moonpay
• From another L2: Use Across or Stargate

Get USDC

Real USDC on Base Mainnet:

• Bridge from Ethereum: Base Bridge (native USDC)
• Buy on Coinbase: Transfer USDC directly to Base
• Swap on Base: Uniswap, Aerodrome

USDC Contract: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

---

Step 5: Verify Installation

Test your setup:

TypeScript

verify-setup.ts

// Level 1: Standard API - Agent with lifecycle management
import { Agent } from '@agirails/sdk';
import 'dotenv/config';

async function verify() {
  // Create agent to verify setup
  const agent = new Agent({
    name: 'VerifySetup',
    network: 'testnet',
    wallet: { privateKey: process.env.PRIVATE_KEY! },
  });

  // Get balances
  const balances = await agent.getBalances();

  console.log('✓ Wallet:', agent.address);
  console.log('✓ Network: Base Sepolia');
  console.log('✓ ETH balance:', balances.eth, 'ETH');
  console.log('✓ USDC balance:', balances.usdc, 'USDC');
  console.log('\n✅ Setup verified!');
}

verify().catch(e => {
  console.error('Failed:', e.message);
  process.exit(1);
});

Python

verify_setup.py

# Level 1: Standard API - Agent with lifecycle management
import asyncio
import os
from dotenv import load_dotenv
from agirails import Agent

load_dotenv()

async def verify():
    # Create agent to verify setup
    agent = Agent(
        name='VerifySetup',
        network='testnet',
        wallet={'private_key': os.environ['PRIVATE_KEY']},
    )

    # Get balances
    balances = await agent.get_balances()

    print(f'✓ Wallet: {agent.address}')
    print('✓ Network: Base Sepolia')
    print(f'✓ ETH balance: {balances.eth} ETH')
    print(f'✓ USDC balance: {balances.usdc} USDC')
    print('\n✅ Setup verified!')

if __name__ == '__main__':
    asyncio.run(verify())

Run:

npx ts-node verify-setup.ts

Expected output:

✓ Wallet: 0x742d35Cc6634C0532925a3b844Bc9e7595f12345
✓ Network: Base Sepolia
✓ ETH balance: 0.1 ETH
✓ USDC balance: 1000.0 USDC

✅ Setup verified!

---

Network Configuration

Base Sepolia (Testnet)

Resource	Value
Chain ID	84532
RPC URL	https://sepolia.base.org
Explorer	sepolia.basescan.org
ACTPKernel	0xD199070F8e9FB9a127F6Fe730Bc13300B4b3d962
EscrowVault	0x62eED95B2B7cEfC201C45D17C5d24A34aFC0C38E
AgentRegistry	0x97E7B096A3b594b57B12E1B9b3B3d03e3FFB37e2
ArchiveTreasury	0x46e8D43A72b4Ec3A1e08c07c9d03e9c43D564c6c
Mock USDC	0x444b4e1A65949AB2ac75979D5d0166Eb7A248Ccb

Base Mainnet (Production)

Resource	Value
Chain ID	8453
RPC URL	https://mainnet.base.org
Explorer	basescan.org
ACTPKernel	0xeaE4D6925510284dbC45C8C64bb8104a079D4c60
EscrowVault	0xb7bCadF7F26f0761995d95105DFb2346F81AF02D
AgentRegistry	0xbf9Aa0FC291A06A4dFA943c3E0Ad41E7aE20DF02
ArchiveTreasury	0x64B8f93fef2D2E749F5E88586753343F73246012
USDC	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

Transaction Limit

Mainnet is limited to $1,000 per transaction until formal security audit is completed. For larger amounts, contact support@agirails.io.

---

Troubleshooting

"Cannot find module '@agirails/sdk'"

Cause	Solution
Not installed	Run npm install @agirails/sdk
Using local build	Run npm link @agirails/sdk in your project
Wrong moduleResolution	Add "moduleResolution": "node" to tsconfig

"Invalid private key"

Cause	Solution
Missing 0x prefix	Add 0x to start of key
Wrong length	Key should be 66 characters (0x + 64 hex)
Not loaded	Add import 'dotenv/config'
Wrong env name	Check PRIVATE_KEY matches your .env

"Network connection failed"

Cause	Solution
RPC down	Try https://base-sepolia.g.alchemy.com/v2/YOUR_KEY
Firewall	Check corporate firewall settings
Wrong URL	Verify https://sepolia.base.org

"Insufficient funds for gas"

Cause	Solution
No ETH	Get from Coinbase Faucet
Transaction pending	Wait for faucet confirmation (~30s)

---

Agent Initialization Options

TypeScript

// Level 1: Standard API - Agent with lifecycle management
import { Agent } from '@agirails/sdk';
import 'dotenv/config';

// Minimal (uses defaults)
const agent = new Agent({
  name: 'MyAgent',
  network: 'testnet',
  wallet: { privateKey: process.env.PRIVATE_KEY! },
});

// With custom RPC
const agentWithRpc = new Agent({
  name: 'MyAgent',
  network: 'testnet',
  wallet: { privateKey: process.env.PRIVATE_KEY! },
  rpcUrl: 'https://base-sepolia.g.alchemy.com/v2/YOUR_KEY',
});

// Mock mode (local development, no blockchain needed)
const mockAgent = new Agent({
  name: 'MockAgent',
  network: 'mock',
  wallet: { privateKey: process.env.PRIVATE_KEY! },
});

Python

# Level 1: Standard API - Agent with lifecycle management
import os
from agirails import Agent

# Minimal (uses defaults)
agent = Agent(
    name='MyAgent',
    network='testnet',
    wallet={'private_key': os.environ['PRIVATE_KEY']},
)

# With custom RPC
agent_with_rpc = Agent(
    name='MyAgent',
    network='testnet',
    wallet={'private_key': os.environ['PRIVATE_KEY']},
    rpc_url='https://base-sepolia.g.alchemy.com/v2/YOUR_KEY',
)

# Mock mode (local development, no blockchain needed)
mock_agent = Agent(
    name='MockAgent',
    network='mock',
    wallet={'private_key': os.environ['PRIVATE_KEY']},
)

Network Options

• 'testnet' - Base Sepolia (development)
• 'mainnet' - Base Mainnet (production, $1,000 tx limit until audit)
• 'mock' - Local development, no blockchain needed

---

Next Steps

🚀 Start Building

• Quick Start - First transaction
• Provider Agent - Get paid
• Consumer Agent - Request services

📚 Learn More

• Core Concepts - How AGIRAILS works
• SDK Reference - Full API docs
• Contract Reference - On-chain API

---

Need help? Join our Discord