에이전트 등록 및 신원

에이전트의 신원을 온체인에 등록하고, Basename을 발급받고, SIWA(Sign In With Agent)로 서비스에 인증합니다

에이전트가 서비스를 호출할 때 그 서비스는 실제로 내 에이전트인지 어떻게 알 수 있을까요? 에이전트가 응답을 받을 때 응답이 정당한지 어떻게 확인할 수 있을까요? 등록과 신원 검증이 두 가지 문제를 모두 해결합니다.

모의 데모

등록이 필요한 이유

• 검색 가능성 — 다른 에이전트와 서비스가 공개 레지스트리를 조회하여 에이전트를 찾을 수 있습니다
• SIWA 인증 — 서비스가 등록 정보를 사용하여 요청이 실제로 에이전트에서 왔는지 검증합니다
• 평판 — 평판 레지스트리에 다른 에이전트가 상호작용 전에 조회할 수 있는 신뢰 신호가 축적됩니다

에이전트를 위한 Basename 발급

Basename은 에이전트에게 지갑 주소로 해석되는 사람이 읽을 수 있는 신원(예: myagent.base.eth)을 부여합니다. base.org/names에서 등록하세요.

ERC-8004 레지스트리에 등록

ERC-8004 표준은 에이전트가 이름, 설명, 엔드포인트, 공개 키 등 신원 정보를 게시하는 온체인 NFT 레지스트리입니다.

UI로 등록

8004scan.io를 사용하여 코드 없이 웹 인터페이스를 통해 에이전트를 등록하고 탐색합니다.

SDK로 등록

Agent0 SDK를 사용하여 에이전트를 프로그래밍 방식으로 등록하고 온체인 프로필을 관리합니다.

레지스트리 항목에는 에이전트의 이름과 설명, 에이전트에 접근할 수 있는 엔드포인트, 에이전트의 신원을 암호학적 자격증명에 연결하는 키 쌍이 포함됩니다.

정규 레지스트리 주소는 8004scan.io에서 확인할 수 있습니다.

ERC-8004 더 알아보기 →

런타임에서 신원 검증 (ERC-8128)

등록은 에이전트의 존재를 세상에 알립니다. ERC-8128 표준은 에이전트가 모든 요청에서 자신이 진짜임을 증명할 수 있게 합니다:

1. 에이전트 등록

   에이전트는 ERC-8004 레지스트리에 신원과 공개 키를 등록합니다. 이는 일회성 설정 단계입니다.

2. 각 요청에 서명

   에이전트가 서비스를 호출할 때 개인 키를 사용하여 요청에 서명합니다. 이렇게 하면 특정 요청에 고유한 암호학적 서명이 생성됩니다.

3. 서비스가 서명을 검증

   서비스는 레지스트리에서 에이전트의 공개 키를 조회한 다음 서명을 확인합니다. 일치하면 요청이 등록된 에이전트에서 왔음을 알 수 있습니다.

이는 양방향으로 작동합니다 — 에이전트도 레지스트리에서 서비스의 서명을 확인하여 서비스 응답이 정당한지 검증할 수 있습니다.

ERC-8128 사양 →

Sign In With Agent (SIWA)

SIWA는 ERC-8004 등록과 ERC-8128 서명을 단일 SDK로 묶습니다 — “Google로 로그인”이 OAuth를 하나의 통합으로 묶는 것과 유사합니다.

가장 단순한 통합 경로를 위해 SIWA부터 시작하세요. 등록과 검증에 대한 세밀한 제어가 필요한 경우에만 ERC-8004와 ERC-8128을 직접 사용하세요.

에이전트 측 통합

SIWA SDK를 설치합니다:

Terminal

npm install @buildersgarden/siwa

지갑 공급자에 맞는 서명자를 선택합니다. SIWA는 개인 키, Bankr, Circle, Openfort, Privy, 스마트 컨트랙트 계정을 지원합니다:

TypeScript

import { createLocalAccountSigner } from "@buildersgarden/siwa/signer";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const signer = createLocalAccountSigner(account);

서비스에서 nonce를 요청한 다음 SIWA 메시지에 서명하고 제출합니다:

TypeScript

import { signSIWAMessage } from "@buildersgarden/siwa";

// 1단계: 서비스에서 nonce 요청
const nonceResponse = await fetch("https://api.example.com/siwa/nonce", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ address: await signer.getAddress() }),
});
const { nonce, issuedAt } = await nonceResponse.json();

// 2단계: SIWA 메시지에 서명
const { message, signature } = await signSIWAMessage(
  {
    domain: "api.example.com",
    uri: "https://api.example.com/siwa",
    agentId: 42, // ERC-8004 토큰 ID
    agentRegistry: "eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432",
    chainId: 8453,
    nonce,
    issuedAt,
  },
  signer
);

// 3단계: 검증 제출 및 영수증 수신
const verifyResponse = await fetch("https://api.example.com/siwa/verify", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ message, signature }),
});
const { receipt } = await verifyResponse.json();

영수증을 사용하여 ERC-8128로 후속 요청에 서명합니다:

TypeScript

import { signAuthenticatedRequest } from "@buildersgarden/siwa/erc8128";

const request = new Request("https://api.example.com/action", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ action: "transfer" }),
});

const signedRequest = await signAuthenticatedRequest(request, receipt, signer, 8453);
const response = await fetch(signedRequest);

서버 측 검증

SIWA 인증 에이전트를 수락하는 서비스는 두 가지 엔드포인트를 구현합니다: nonce 발급 엔드포인트와 서명 검증 엔드포인트.

TypeScript

import { verifySIWA, createSIWANonce } from "@buildersgarden/siwa";
import { createReceipt } from "@buildersgarden/siwa/receipt";
import { createPublicClient, http } from "viem";
import { base } from "viem/chains";

const client = createPublicClient({ chain: base, transport: http() });

// POST /siwa/nonce
const { nonce, issuedAt } = await createSIWANonce({ address, agentId, agentRegistry }, client);

// POST /siwa/verify
const result = await verifySIWA(message, signature, "api.example.com", nonceValid, client);
if (result.success) {
  const { receipt } = createReceipt({ address: result.address, agentId: result.agentId });
  return { receipt };
}

SIWA는 Express, Next.js, Hono, Fastify용 드롭인 미들웨어를 제공합니다. 프레임워크별 예시, 재생 방지, x402 결제 통합은 SIWA 문서를 참조하세요.

영상 튜토리얼

관련 항목

ERC-8004 레지스트리

Base에서 등록된 에이전트와 레지스트리 주소를 탐색하고 검증합니다.

x402 프로토콜

x402 프로토콜을 사용하여 스테이블코인으로 API 접근 비용을 지불합니다.