API Documentation

Overview

AgentsScan provides a way to register AI agents on-chain by issuing them ENS subnames, setting ENSIP-25 attestation text records, and making everything cryptographically verifiable. There are two ways to register an agent:

Quick Start

git clone https://gitlab.com/proskairos/agentsscan.git
cd agentsscan
npm install

# Relayer private key (funded with Sepolia ETH)
RELAYER_PRIVATE_KEY=0x_your_private_key_here

# WalletConnect Project ID (get from cloud.walletconnect.com)
NEXT_PUBLIC_WC_PROJECT_ID=your_project_id

npm run dev

Architecture

The system has three key addresses that you should understand before using the API:

Environment Setup

Before using the API flow, there is one on-chain prerequisite you must complete: approve the relayer wallet to create subnodes under your ENS name.

Approve the Relayer (One-time Setup)

The relayer needs permission to call setSubnodeOwner on your parent ENS name. You must call setApprovalForAll(relayerAddress, true) on the ENS Registry contract. This only needs to be done once per ENS name.

// Target: ENS Registry
// Address: 0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e
// Function: setApprovalForAll(address operator, bool approved)
//
// operator:  <your relayer wallet address>
// approved:  true

import { ethers } from "ethers";

const provider = new ethers.JsonRpcProvider(
  "https://ethereum-sepolia.publicnode.com"
);
const signer = new ethers.Wallet(PRIVATE_KEY, provider);

const ensRegistry = new ethers.Contract(
  "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e",
  ["function setApprovalForAll(address,bool)"],
  signer
);

// Approve relayer to create subnodes under your name
const tx = await ensRegistry.setApprovalForAll(
  RELAYER_ADDRESS,   // the relayer wallet address
  true
);
await tx.wait();
console.log("Approved! Relayer can now create subnodes.");

API Reference

POST /api/register

Register a new AI agent via the relayer. The relayer verifies your EIP-191 signature against the on-chain ENS owner, then executes all 5 on-chain operations.

Request Body

{
  "parentName":        "myname.eth",
  "sublabel":          "trader-bot",
  "agentWalletAddress": "0x1234...abcd",
  "signature":         "0xabcdef..."
}

Success Response (200)

{
  "success": true,
  "ensName": "trader-bot.myname.eth",
  "agentId": 1,
  "relayer": "0xRE...AYER",
  "transactions": {
    "setSubnodeOwner":  "0xabc...",
    "setResolver":       "0xdef...",
    "setAddr":           "0x123...",
    "registerAgent":     "0x456...",
    "setEnsip25Text":    "0x789..."
  }
}

Error Response (4xx / 5xx)

{
  "success": false,
  "error": "Missing required fields: parentName, sublabel, agentWalletAddress, signature"
}

Testing the Flow

Here is a complete step-by-step guide to test the API flow end to end. This assumes you already have a funded wallet with a Sepolia ENS name.

Step 1: Get a Sepolia ENS name

Go to app.ens.domains, connect your wallet, switch to Sepolia, and register any available .eth name. This will be your parentName.

Step 2: Fund the relayer wallet

Generate a new wallet (or use an existing one), set it as RELAYER_PRIVATE_KEY in .env.local, and fund it with Sepolia ETH from a faucet.

Step 3: Approve the relayer

Call setApprovalForAll(relayerAddress, true) on the ENS Registry from your ENS owner wallet. See the Environment Setup section for details.

Step 4: Construct the signature message

The EIP-191 message must follow this exact format. The relayer will verify this message against the on-chain ENS owner.

I authorize registering {sublabel}.{parentName}

// Example:
I authorize registering trader-bot.myname.eth

Step 5: Sign the message

Sign the message from your ENS owner wallet using any Web3 library. Here are examples for both wagmi and ethers.js:

import { signMessage } from "wagmi/actions";

const parentName = "myname.eth";
const sublabel = "trader-bot";
const message = `I authorize registering ${sublabel}.${parentName}`;

const signature = await signMessage({ message });
// signature => "0xabcdef..."

import { ethers } from "ethers";

const signer = new ethers.Wallet(PRIVATE_KEY);
const message = "I authorize registering trader-bot.myname.eth";

const signature = await signer.signMessage(message);
// signature => "0xabcdef..."

Step 6: Send the API request

With the signature in hand, make a POST request to the relayer endpoint. The server will verify your signature, check ENS ownership, and execute all 5 on-chain operations.

const response = await fetch("/api/register", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    parentName:         "myname.eth",
    sublabel:           "trader-bot",
    agentWalletAddress: "0xYourAgentWalletAddress",
    signature:          "0xYourEip191Signature",
  }),
});

const data = await response.json();

if (data.success) {
  console.log("Agent registered!", data.ensName);
  console.log("Agent ID:", data.agentId);
  console.log("Transactions:", data.transactions);
} else {
  console.error("Failed:", data.error);
}

curl -X POST https://your-domain.com/api/register \
  -H "Content-Type: application/json" \
  -d '{
    "parentName": "myname.eth",
    "sublabel": "trader-bot",
    "agentWalletAddress": "0xYourAgentWallet",
    "signature": "0xYourEip191Sig"
  }'

Deployed Contracts

All contracts are deployed on Sepolia testnet. These addresses are configured in src/lib/wagmi.ts.

On-chain Steps

Registering an agent requires exactly 5 on-chain transactions, executed in order. Here is what each step does and why the order matters.

// ENS Registry: setSubnodeOwner(node, label, owner)
// node   = namehash("myname.eth")
// label  = labelhash("trader-bot")
// owner  = relayerAddress (API) or agentWallet (UI)

// ENS Registry: setResolver(node, resolver)
// node     = namehash("trader-bot.myname.eth")
// resolver = 0xE99638b40E4Fff0129D56f03b55b6bbC4BBE49b5

// Public Resolver: setAddr(node, addr)
// node = namehash("trader-bot.myname.eth")
// addr = 0xYourAgentWalletAddress

// Agent Registry: registerAgent(string _ensName)
// _ensName = "trader-bot.myname.eth"
// Returns: uint256 agentId (via event)

// Public Resolver: setText(node, key, value)
// node  = namehash("trader-bot.myname.eth")
// key   = "agent-registration[0x67D2...0AC8][1]"
// value = "true"