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-sdk

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
Python

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

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:

Visit Coinbase Faucet
Connect your wallet
Request Base Sepolia ETH
Wait ~30 seconds

Get Mock USDC

Mint mock USDC tokens:

TypeScript
Python

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');

mint_usdc.py
import os
from dotenv import load_dotenv
from agirails_sdk import ACTPClient, Network

load_dotenv()

client = ACTPClient(network=Network.BASE_SEPOLIA, private_key=os.environ["PRIVATE_KEY"])
usdc = client.usdc
tx = usdc.functions.mint(client.address, 1_000 * 1_000_000).build_transaction(
    client._tx_meta(gas=120_000)
)
receipt = client._build_and_send(tx)
print("Minted 1000 USDC", receipt["transactionHash"].hex())

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
Python

verify-setup.ts
import { ACTPClient } from '@agirails/sdk';
import { ethers, formatEther, formatUnits } from 'ethers';
import 'dotenv/config';

async function verify() {
  const client = await ACTPClient.create({
    network: 'base-sepolia',
    privateKey: process.env.PRIVATE_KEY!
  });

  const address = await client.getAddress();
  const config = client.getNetworkConfig();
  const provider = client.getProvider();

  // Check balances
  const ethBalance = await provider.getBalance(address);
  const usdcContract = new ethers.Contract(
    config.contracts.usdc,
    ['function balanceOf(address) view returns (uint256)'],
    provider
  );
  const usdcBalance = await usdcContract.balanceOf(address);

  console.log('✓ Wallet:', address);
  console.log('✓ Network: Base Sepolia');
  console.log('✓ ACTPKernel:', config.contracts.actpKernel);
  console.log('✓ EscrowVault:', config.contracts.escrowVault);
  console.log('✓ ETH balance:', formatEther(ethBalance), 'ETH');
  console.log('✓ USDC balance:', formatUnits(usdcBalance, 6), 'USDC');
  console.log('\n✅ Setup verified!');
}

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

verify_setup.py
import os
from dotenv import load_dotenv
from agirails_sdk import ACTPClient, Network

load_dotenv()

client = ACTPClient(network=Network.BASE_SEPOLIA, private_key=os.environ["PRIVATE_KEY"])
usdc = client.usdc

eth_balance = client.w3.eth.get_balance(client.address)
usdc_balance = usdc.functions.balanceOf(client.address).call()

print("✓ Wallet:", client.address)
print("✓ Network: Base Sepolia")
print("✓ ACTPKernel:", client.config.actp_kernel)
print("✓ EscrowVault:", client.config.escrow_vault)
print("✓ ETH balance:", client.w3.from_wei(eth_balance, 'ether'), "ETH")
print("✓ USDC balance:", usdc_balance / 1_000_000, "USDC")
print("\n✅ Setup verified!")

Run:

npx ts-node verify-setup.ts

Expected output:

✓ Wallet: 0x742d35Cc6634C0532925a3b844Bc9e7595f12345
✓ Network: Base Sepolia
✓ ACTPKernel: 0x6aDB650e185b0ee77981AC5279271f0Fa6CFe7ba
✓ EscrowVault: 0x921edE340770db5DB6059B5B866be987d1b7311F
✓ 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 network: 'base-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)

SDK Initialization Options

TypeScript
Python

import { ACTPClient } from '@agirails/sdk';

// Minimal (uses defaults)
const client = await ACTPClient.create({
  network: 'base-sepolia',
  privateKey: process.env.PRIVATE_KEY!
});

// With custom RPC
const client = await ACTPClient.create({
  network: 'base-sepolia',
  privateKey: process.env.PRIVATE_KEY!,
  rpcUrl: 'https://base-sepolia.g.alchemy.com/v2/YOUR_KEY'
});

// With external signer (e.g., from wallet connection)
const client = await ACTPClient.create({
  network: 'base-sepolia',
  signer: externalSigner // ethers.Signer from wallet
});

from agirails_sdk import ACTPClient, Network
import os

# Minimal
client = ACTPClient(
    network=Network.BASE_SEPOLIA,
    private_key=os.environ["PRIVATE_KEY"],
)

# With custom RPC
client = ACTPClient(
    network=Network.BASE_SEPOLIA,
    private_key=os.environ["PRIVATE_KEY"],
    rpc_url="https://base-sepolia.g.alchemy.com/v2/YOUR_KEY",
)

Read-Only Mode Not Supported in V1

The SDK currently requires a signer for initialization. True read-only access (for querying transaction state without a private key) is planned for a future release. For now, use a throwaway private key if you only need to read data.

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

Quick Reference​

Step 1: Install SDK​

From Source (Optional)​

Step 2: Configure TypeScript​

Step 3: Environment Setup​

Step 4: Get Testnet Tokens​

Get Base Sepolia ETH​

Get Mock USDC​

Step 5: Verify Installation​

Network Configuration​

Base Sepolia (Testnet)​

Base Mainnet (Production)​

Troubleshooting​

"Cannot find module '@agirails/sdk'"​

"Invalid private key"​

"Network connection failed"​

"Insufficient funds for gas"​

SDK Initialization Options​

Next Steps​