Skip to content

Quickstart

From zero to registered agents on a live blockchain.

Prerequisites

Requirement Minimum Version Check Command
Node.js 18+ node --version
npm 9+ npm --version
Python 3.10+ (optional, for SDK) python3 --version

Local Development (No Testnet Needed)

Run npm run local to start a local Hardhat node with unlimited ETH. This deploys contracts and starts all services automatically -- no faucets, no testnet ETH, no waiting. Everything resets when you stop it. Skip directly to Step 6 after running this command.

Step 1: Install

cd agentenregister
npm install

Step 2: Generate Wallet Keys

npm run setup:keys

This creates two wallets and saves their private keys to .env:

  • Deployer -- deploys contracts, becomes the contract owner
  • Relayer -- pays gas for gasless agent registrations

To see your wallet addresses at any time:

npm run addresses

Protect your keys

The .env file contains private keys. Never commit it to version control. It is already listed in .gitignore.

Step 3: Fund Wallets with Base Sepolia ETH

You need approximately 0.01 ETH in each wallet. Testnet ETH is free.

The recommended approach. Fully automated with retries.

  1. Get free API keys at https://portal.cdp.coinbase.com

  2. Add credentials to .env:

    CDP_API_KEY_ID=your-key-id
CDP_API_KEY_SECRET=your-key-secret
CDP_WALLET_SECRET=your-wallet-secret

  3. Claim testnet ETH:

    # 0.01 ETH to both deployer and relayer
npm run claim

# 0.02 ETH to both (more claims)
npm run claim -- --claims 400

# Fund relayer only (for ongoing operations)
npm run claim:relayer

Get your addresses with npm run addresses, then paste them into any of these faucets:

Note

Some faucets require a minimum mainnet balance or social verification. Try multiple faucets if one does not work.

Step 4: Deploy Contracts

npm run setup:deploy

This deploys both the MinimalForwarder and Agentenregister contracts to Base Sepolia and saves their addresses to .env.

Verify deployment

After deployment, confirm the contracts are live:

node -e "
const{ethers}=require('ethers');require('dotenv').config();
const p=new ethers.JsonRpcProvider('https://sepolia.base.org');
const r=new ethers.Contract(process.env.REGISTRY_ADDRESS,
  ['function nextAgentId() view returns (uint256)',
   'function owner() view returns (address)'],p);
(async()=>{
  console.log('Registry:', process.env.REGISTRY_ADDRESS);
  console.log('Forwarder:', process.env.FORWARDER_ADDRESS);
  console.log('Owner:', await r.owner());
  console.log('Agents registered:', Number(await r.nextAgentId())-1);
})();"

Already deployed?

If you want to connect to the existing COAI Research deployment instead of deploying your own, set these in .env:

REGISTRY_ADDRESS=0x2EFaB5B3BEf49E56a6Ce1dcB1A39EF63C312EA23
FORWARDER_ADDRESS=0x70c2fdD0CDada6b43195981928D76f5D32AE29e5
RPC_URL=https://sepolia.base.org

Step 5: Start Services

npm start

This starts the relayer (port 3001) and API (port 3000) concurrently.

Terminal 1 -- Relayer (pays gas for agents):

npm run relayer

Output:

Agentenregister Relayer running on https://relay.theagentregistry.org
   Relayer wallet:  0x626...
   Balance:         0.044 ETH
   Daily gas budget: 0.05 ETH

Terminal 2 -- API (public query layer):

npm run api

Output:

Agentenregister API running on https://api.theagentregistry.org
   GET /api/v1/stats              -- Registry statistics
   GET /api/v1/agent/:id          -- Agent record
   GET /api/v1/agent/:id/lineage  -- Lineage tree
   GET /api/v1/agent/:id/revenue  -- Revenue history
   GET /api/v1/kya/:wallet        -- KYA compliance check

Verify both services are running:

curl https://api.theagentregistry.org/health
curl https://relay.theagentregistry.org/status

Step 6: Register an Agent

The agent needs only a private key -- zero ETH required.

from sdk.agentenregister import AgentRegistry

registry = AgentRegistry.from_env()

agent_id = registry.register(
    haftungsperson="0xYOUR_WALLET",
    agent_wallet="0xAGENT_WALLET",
    capabilities=["web_browsing", "content_creation"],
    operational_scope="Content creation and publishing",
    constitution_text="Law I: Do no harm.",
)
print(f"Agent #{agent_id} registered!")

import { AgentRegistry } from "@agentenregister/sdk";

const registry = new AgentRegistry({
  chain: "base_sepolia",
  registryAddress: "0x2EFaB5B3BEf49E56a6Ce1dcB1A39EF63C312EA23",
  privateKey: "0x...",
  relayerUrl: "https://relay.theagentregistry.org",
});

const agentId = await registry.register({
  haftungsperson: "0xYOUR_WALLET",
  agentWallet: "0xAGENT_WALLET",
  capabilities: ["web_browsing", "content_creation"],
  operationalScope: "Content creation and publishing",
  constitutionText: "Law I: Do no harm.",
});

console.log(`Agent #${agentId} registered!`);

For the full EIP-712 signing flow using curl, see the Relayer API Reference and the Scientific Deployment Guide.

What just happened?

The agent signed an EIP-712 message locally (free). The relayer verified the signature and submitted the transaction to the blockchain, paying ~$0.005 in gas. The agent is now registered on-chain with a unique ID.

Step 7: Query the Registry

# Get agent details
curl https://api.theagentregistry.org/api/v1/agent/1

{
  "agent": {
    "agentId": 1,
    "creator": "0x4b192fD5c4f24cE23000B49f31CF3d7484Ccf252",
    "haftungsperson": "0x4b192fD5c4f24cE23000B49f31CF3d7484Ccf252",
    "agentWallet": "0x4b192fD5c4f24cE23000B49f31CF3d7484Ccf252",
    "operationalScope": "Scientific test agent #1",
    "generation": 0,
    "selfModifying": false,
    "registeredAt": "2026-02-22T19:02:18.000Z",
    "status": "Active"
  },
  "children": [],
  "compliance": {
    "isActive": true,
    "attestationCurrent": true
  }
}

# KYA check (what infrastructure providers call)
curl https://api.theagentregistry.org/api/v1/kya/0xAGENT_WALLET_ADDRESS

{
  "wallet": "0xAGENT_WALLET_ADDRESS",
  "isRegistered": true,
  "isCompliant": true,
  "agent": {
    "agentId": 1,
    "haftungsperson": "0x...",
    "operationalScope": "...",
    "status": "Active"
  }
}

# Registry-wide statistics
curl https://api.theagentregistry.org/api/v1/stats

Step 8: Run Tests

# Full test suite (68 tests)
npm test

# With coverage report
npm run test:coverage

# Live integration tests against Base Sepolia
npm run test:live

Cost Summary

Operation Cost to Agent Cost to Relayer (Base L2)
Register $0.00 ~$0.005
Attest compliance $0.00 ~$0.001
Report revenue $0.00 ~$0.002
Query registry $0.00 $0.00 (view function)

The relayer serves approximately 1,000 agents for ~$5/month on Base L2.

What's Next?