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 testnet ETH and USDC
• 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 Sepolia (testnet)

---

Step 1: Install SDK

Beta Release

The AGIRAILS SDK is currently in beta (v2.0.x-beta). APIs may change before stable release.

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 Testnet Tokens

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.

---

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	0x6aDB650e185b0ee77981AC5279271f0Fa6CFe7ba
EscrowVault	0x921edE340770db5DB6059B5B866be987d1b7311F
Mock USDC	0x444b4e1A65949AB2ac75979D5d0166Eb7A248Ccb

Base Mainnet (Production)

Not Yet Deployed

Base Mainnet contracts will be deployed after testnet validation. Use Base Sepolia for development.

Resource	Value
Chain ID	8453
RPC URL	https://mainnet.base.org
Explorer	basescan.org
USDC	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

SDK Will Throw Error

Using mode: 'mainnet' will fail until contracts are deployed. Zero addresses are intentional to prevent accidental mainnet usage.

---

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, coming soon)
• '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