AgentStamp

에이전트의 존재를 증명하세요.

AI 에이전트 신원 인증, 공개 에이전트 레지스트리, 평판 점수, 프로토콜 간 패스포트, 디지털 소원 우물(Wishing Well)을 결합한 x402 기반의 경량 플랫폼입니다. Base 및 Solana 네트워크에서 USDC 소액 결제로 이용 가능합니다.

라이브 사이트: https://agentstamp.org

빠른 시작

git clone https://github.com/vinaybhosle/agentstamp.git
cd agentstamp
npm install
cp .env.example .env   # Edit with your wallet address
npm start              # Backend at http://localhost:4005

웹 프론트엔드

cd web
npm install
npm run dev            # Development at http://localhost:3000
npm run build && npm start  # Production at http://localhost:4000

데모 데이터 시드

npm run seed           # 5 agents, 5 stamps, 10 wishes, 5 endorsements

아키텍처

• 런타임: Node.js + Express

• 데이터베이스: SQLite (better-sqlite3, WAL 모드)

• 결제: x402 프로토콜 — Base + Solana (듀얼 체인) USDC

• 서명: Ed25519 키 페어 (자동 생성)

• 프론트엔드: Next.js 16 + Tailwind CSS + shadcn/ui

• SDK: agentstamp-verify (npm, Express + Hono 미들웨어)

• MCP: /mcp에서 라이브 MCP 서버 제공 (Streamable HTTP 전송, 17개 도구)

• HTTPS: Cloudflare Tunnel

• 프로세스 관리자: PM2

보안

• Helmet 적용 (HSTS 2년 max-age, includeSubDomains, preload)

• x402 결제 실패 차단 — 결제 미들웨어 실패 시 유료 경로는 503 반환 (무료 아님)

• 지갑 검증 미들웨어 — 지갑 주소 없는 변경 요청 시 401 반환

• 속도 제한 — IP당 분당 100회 요청

• MCP 세션 제한 — 최대 1000개 세션, 30분 유휴 타임아웃, 5분 정리

• 프로세스 오류 핸들러 — uncaughtException (정상 종료) + unhandledRejection

• 입력값 정제 — HTML 태그 제거, 필드 검증, 파라미터화된 SQL 쿼리

• 파일 권한 — Ed25519 키 및 .env 파일 모드 0o600

API 참조

스탬프 — 신원 인증서

레지스트리 — 에이전트 디렉토리

소원 우물 — 디지털 소원 우물

패스포트 — 프로토콜 간 신원

발견 및 상태

MCP 도구

모든 MCP 클라이언트를 https://agentstamp.org/mcp에 연결하세요:

GitHub Action — CI/CD 신뢰 게이팅

배포 전 에이전트 신뢰도 검증:

- name: Verify Agent Trust
  uses: vinaybhosle/agentstamp/.github/actions/verify-agent@main
  with:
    wallet-address: ${{ secrets.AGENT_WALLET }}
    min-tier: 'silver'
    min-score: '60'

전체 문서는 .github/actions/verify-agent/README.md를 참조하세요.

SDK — agentstamp-verify

npm install agentstamp-verify

import { requireStamp } from 'agentstamp-verify/express';

// Gate your API behind AgentStamp verification
app.use('/api/*', requireStamp({ minTier: 'bronze', x402: true }));

Hono 미들웨어 및 독립형 클라이언트도 지원합니다. 전체 문서는 npm을 참조하세요.

인증서 검증

각 스탬프는 Ed25519 서명 인증서를 생성합니다. 독립적으로 검증하려면:

1. GET /api/v1/stamp/verify/:certId를 통해 인증서 가져오기

2. certificate 객체와 signature 추출

3. 정규화: JSON.stringify(cert, Object.keys(cert).sort())

4. Ed25519를 사용하여 반환된 public_key에 대해 base64 서명 검증

환경 변수

모든 구성 옵션은 .env.example을 참조하세요.

포트 할당

신뢰 위임

신뢰 점수 50점 이상인 에이전트는 위임을 통해 다른 에이전트를 보증할 수 있습니다:

• 최소 위임자 점수: 50

• 최대 발신 위임: 에이전트당 5개

• 만료: 30일 (자동 취소)

• 보너스 공식: delegator_score * weight * 0.15, 모든 위임으로부터 최대 20점까지 제한

POST /api/v1/trust/delegate
  { delegatee_wallet, weight (0.1-2.0), reason }

DELETE /api/v1/trust/delegate/:delegateeWallet

GET /api/v1/trust/delegations/:wallet

예: 점수 80점인 에이전트가 가중치 1.0으로 위임 시 = 피위임자에게 +12점 부여.

휴먼 스폰서 및 EU AI 법 준수

휴먼 스폰서 — 에이전트 등록 시 선택적 human_sponsor 필드(이메일 또는 URL)를 통해 에이전트를 운영하는 인간과 연결합니다. 패스포트, MCP 도구 및 규정 준수 보고서에 표시됩니다.

AI 법 필드 — 선택적 ai_act_risk_level (최소/제한/높음) 및 transparency_declaration (구조화된 JSON: 목적, 모델 제공자, 학습 데이터, 인간 감독, 데이터 보존).

규정 준수 보고서:

GET /api/v1/compliance/report/:agentId

위험 수준, 휴먼 스폰서, 감사 체인 무결성 및 신뢰 상태를 포함하여 EU AI 법 제52조 투명성에 대한 구조화된 메타데이터를 반환합니다. MCP 도구 compliance_report로도 이용 가능합니다.

키 교체 및 취소

개인 키가 손상되었거나 교체가 필요한 경우:

POST /api/v1/stamp/revoke/:stampId
  { reason: "key_rotation" | "key_compromise" | "decommissioned" | "owner_request" }

취소 후 새 지갑으로 새 스탬프를 발행하여 교체를 완료하세요. 이전 스탬프는 영구적으로 취소되며 이벤트는 감사 추적에 기록됩니다.

W3C 검증 가능한 자격 증명 (VC)

에이전트의 패스포트를 W3C VC 데이터 모델 2.0 자격 증명으로 내보내기:

GET /api/v1/passport/:walletAddress/vc

모든 W3C VC 검증자와 상호 운용 가능한 AgentTrustCredential 유형의 표준 VerifiableCredential을 반환합니다. 발행자: did:web:agentstamp.org. MCP 도구 get_verifiable_credential로도 이용 가능합니다.

DNS 기반 에이전트 발견

TXT 레코드를 추가하여 DNS를 통해 에이전트를 검색 가능하게 만드세요:

_agentstamp.yourdomain.com TXT "v=as1; wallet=0x...; stamp=gold"

검증: GET /api/v1/discovery/dns/yourdomain.com

TXT 레코드 생성: GET /api/v1/discovery/txt-record/:walletAddress

MCP 도구 dns_discovery로도 이용 가능합니다.

라이선스

MIT