# 402-LAB

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/Kairose-master/handsel-mandate  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/402-lab

## Description
Budget-capped x402 buyer: delegate USDC in plain words, agent discovers and pays per call.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "402-lab": {
    "command": "npx",
    "args": ["-y","402-lab"]
  }
}
```

## Documentation & README

# 402-LAB — 바이브코딩 제품을 에이전트에게 판매

**라이브:** https://handsel-mandate-demo.vercel.app (Base 메인넷, 실제 USDC). 지금 파는 상품은 국세청 사업자등록 상태 조회, 호출당 0.02 USDC, x402 Bazaar 등재. [이용 안내](https://github.com/Kairose-master/handsel-mandate/blob/HEAD/docs/terms.md).

세 부분으로 되어 있습니다.

- **판매자 쪽** `demo/` — 공식 x402 SDK로 만든 결제 게이트. 우리 상품(`demo/tools/nts.js`)을 팔고, 판매자의 기존 API 앞에도 그대로 세울 수 있습니다(`demo/upstream.js`, Seller Studio 내보내기 + `UPSTREAM_SECRET`). 402 응답에 Bazaar 발견 메타데이터가 포함됩니다. [운영·배포·확인 절차](https://github.com/Kairose-master/handsel-mandate/blob/HEAD/docs/public-demo.md)
- **구매자 쪽** `mcp/` — 402-LAB MCP 서버. "1달러 안에서"라고 위임하면 Claude Desktop·Cursor·크롬 확장이 x402 Bazaar에서 상품을 찾아 예산 안에서만 결제하고 결과만 돌려줍니다. 상한·건당 한도·네트워크·판매자 허용 목록을 서버가 강제합니다. `npm run mcp`. [설정과 권한 모델](https://github.com/Kairose-master/handsel-mandate/blob/HEAD/docs/mcp.md)
- **홍보·운영** — [홍보 문안과 영상 제작](https://github.com/Kairose-master/handsel-mandate/blob/HEAD/docs/launch-copy.md), [판매 신청서](https://github.com/Kairose-master/handsel-mandate/issues/new?template=sell-your-tool.yml).

빠른 시작: `npm ci && npm test`, `npm run demo`(로컬 시뮬레이션, 키 없음), `npm run mcp`(구매자 지갑).

**구매자 MCP 설치 (저장소 없이)**

[![Add to Cursor](https://img.shields.io/badge/Add%20to-Cursor-blue)](cursor://anysphere.cursor-deeplink/mcp/install?name=402-lab&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImdpdGh1YjpLYWlyb3NlLW1hc3Rlci9oYW5kc2VsLW1hbmRhdGUiXSwiZW52Ijp7IkJVWUVSX1BSSVZBVEVfS0VZIjoiMHhfUkVQTEFDRV9NRSIsIk5FVFdPUksiOiJlaXAxNTU6ODQ1MzIiLCJNQU5EQVRFX01BWF9VU0RDIjoiMSJ9fQ==)

```json
{ "mcpServers": { "402-lab": { "command": "npx", "args": ["-y", "github:Kairose-master/handsel-mandate"],
  "env": { "BUYER_PRIVATE_KEY": "0x...", "NETWORK": "eip155:84532", "MANDATE_MAX_USDC": "1" } } } }
```

Claude Desktop은 `npm run build:mcpb`로 만든 `dist/402-lab.mcpb`를 더블클릭해 설치합니다(키는 설치 화면에서 입력). 레지스트리·Smithery·mcp.so·Cursor 디렉터리·x402 에코시스템 제출 파일과 절차는 [docs/directories.md](https://github.com/Kairose-master/handsel-mandate/blob/HEAD/docs/directories.md)에 있습니다.

첫 성공 기준은 외부 판매자의 도구를 외부 구매자가 실제로 쓰는 것입니다. 지금까지 정산은 내부 지갑 2건이며 구매자 유입이나 매출을 보장하지 않습니다.

---

## Handsel Mandate — 브라우저 위임 프로토타입

아래는 402-LAB의 바탕이 된 온체인 위임 경로입니다. `runtime/buyer.js`는 고정 판매자 엔드포인트에 연결되고, 이제 Base Sepolia와 별도 Base 메인넷 컨트랙트 아티팩트를 지원합니다. **메인넷 아티팩트는 아직 배포·설치·보안 검토되지 않았으며 공개 라이브 결제 서비스와의 실제 호환성도 확인되지 않았습니다.** MCP 구매자 경로와는 별도입니다.

## Seller Studio · 판매자용 초안

바이브 코딩으로 만든 도구의 상품 설명·호출 예제·가격을 정리하고, x402 연동 설정을 내보내는 로컬 스튜디오를 추가했습니다. `node scripts/seller-studio.js` 실행 후 `http://127.0.0.1:4173`을 여세요. 의존성 설치 없이 실행됩니다. 상품 미리보기·예산 제한 모의 구매·JSON 다운로드를 지원합니다. 실제 API 호출·결제·Bazaar 등록·공개 판매는 수행하지 않습니다. [범위와 다음 연동 단계](https://github.com/Kairose-master/handsel-mandate/blob/HEAD/docs/seller-studio.md).

사람이 예산·허용 도구·만료를 지정하고 브라우저 에이전트가 그 범위 안에서 모의 구매하는 Chrome MV3 확장 초안입니다.

**v0.5: 온체인 제한 권한 + BlockFlow + x402.** Coinbase Smart Account에 네트워크별 `MandateValidator`를 컨트랙트 소유자로 설치합니다. 사람이 승인한 총예산·건당 한도·수령인·만료·에이전트·BlockFlow 바인딩을 체인에 기록하고, 에이전트가 결제 금액을 먼저 예약한 경우에만 해당 EIP-3009 결제를 허용합니다. 메인넷은 `allowMainnet: true`와 owner CLI의 `--confirm-mainnet`이 모두 있어야 활성화됩니다.

새 Session 모드에는 소유자 키가 없으며 에이전트는 임의 전송·새 위임 발급을 할 수 없습니다. 회수가 체인에 확정되면 미결제 예약도 무효화됩니다. 영수증은 RPC의 USDC Transfer + AuthorizationUsed nonce와 대조합니다. Sepolia 경로도 공개 체인 설치·정산은 아직 실행하지 않았습니다. 메인넷 포트도 배포·보안 검토 전입니다. [설치·검증 범위](https://github.com/Kairose-master/handsel-mandate/blob/HEAD/docs/session-payments.md)를 확인하세요. 이전 full-owner 모드는 기존 설정에서만 남아 있으며 동일한 보안 보장을 제공하지 않습니다.

x402 서명은 예산 예약 전에 [DAMBI 호환 사전 정책 게이트](https://github.com/Kairose-master/handsel-mandate/blob/HEAD/docs/dambi-integration.md)를 통과해야 합니다. 에이전트 실행에서는 `allow / evaluated / enforcing` 판정만 허용합니다.

## 설치

1. 이 저장소를 clone 또는 Download ZIP으로 받습니다.
2. Chrome `chrome://extensions` → 개발자 모드 → 압축해제된 확장 프로그램 로드 → `extension/` 선택.
3. 도구 모음의 Handsel 아이콘을 누르면 사이드패널이 열립니다. 확장 옵션에서도 같은 화면을 열 수 있습니다.
4. 위임장의 목표·총예산·건당 한도·기간·허용 도구를 확인하고 활성화합니다.
5. 데모 에이전트 실행: 검색 0.03 + 문서 추출 0.05 모의 USDC를 사용하고 영수증을 남깁니다.
6. 총예산 0.05, 건당 0.05로 설정하면 검색 후 추출이 차단됩니다. 첫 호출은 남으며 작업 전체가 원자적이지 않습니다.

## 별도 에이전트 확장 연결

`examples/agent-extension/`도 압축해제 로드합니다. 그 확장 ID를 Handsel 연결란에 저장한 뒤 새 위임장을 활성화하세요. 데모 확장 팝업에 Handsel 확장 ID를 입력하면 extension-to-extension 메시지로 구매를 요청합니다.

지원 API: `status`, `catalog`, `purchase` (`mandateId`, `requestId`, `serviceId`). 응답은 `{ok,result}` 또는 `{ok:false,error}`입니다. 연결된 확장 하나만 접근 가능합니다. 연결 변경은 기존 위임을 회수합니다. 외부 에이전트는 위임 생성·연결 변경·권한 확대를 할 수 없습니다.

브라우저 내장 AI나 Aside류 제품에 자동 연결되는 것은 아닙니다. 해당 제품이 확장 메시지/API 연결을 지원해야 어댑터를 붙일 수 있습니다. 일반 웹페이지에 지출 API를 공개하지 않습니다.

## 테스트

Node 22+에서 `npm ci` 후 `npm test`. BlockFlow 통합 테스트까지 실행하려면 BlockFlow 저장소를 `../BlockFlow`에 clone하거나 `BLOCKFLOW_ROOT=/absolute/path/to/BlockFlow npm test`를 사용합니다. 테스트는 실제 BlockFlow 컴파일, Coinbase Smart Account의 EIP-1271 래핑 서명, x402 payload의 AA payer 주소를 확인합니다. Chrome/체인 실제 설치 검증은 아래 체크리스트로 별도 수행합니다.

- [ ] 아이콘 클릭 → 사이드패널 열림
- [ ] 생성 → 데모 구매 → 재시작 후 예산/영수증 유지
- [ ] 만료/회수/건당/총예산 초과 차단
- [ ] 연결되지 않은 데모 확장 호출 거절
- [ ] 연결 후 데모 확장 호출 성공
- [ ] 두 패널 동시 호출에도 총예산 초과 없음

## 구현 경계

- 정수 micro-USDC로 금액 계산, service worker의 직렬 큐로 상태 갱신, request ID로 중복 차감 방지.
- 서비스 가격은 고정 로컬 카탈로그에서 읽습니다. 외부 요청이 가격을 지정할 수 없습니다.
- 목표의 의미나 API 품질은 검증하지 않습니다. 자연어를 금융 권한으로 자동 컴파일하지 않습니다.
- 내보낸 JSON은 **서명되지 않은 데모 기록**이며 법률상 위임장 또는 온체인 권한이 아닙니다.
- 저장소의 코드/영수증은 공개되지 않고 확장 로컬 저장소에만 기록됩니다. 동기화/원격 분석 없음.

## 통합 구조

`위임 입력 → BlockFlow 검증·산출물 바인딩 → 사람이 온체인 grant → 에이전트 reserve → EIP-1271 x402 결제 → RPC 영수증 대조` 순서입니다. 컴파일러 커밋·작업트리·정책·컨트랙트 바이트코드·소유자 슬롯을 검사하고 불일치하면 차단합니다.

BlockFlow는 워크플로 구조를 검증합니다. 예산 제약은 별도로 작성한 `MandateValidator`가 집행하며, BlockFlow가 임의 BPMN 전체를 지출 모듈로 자동 변환하는 것은 아닙니다. endpoint와 자연어 목표는 온체인 결제 의미로 강제되지 않습니다.

## 다음 단계

남은 검증은 실제 Base Sepolia USDC와 facilitator를 이용한 배포·정산, 별도 보안 검토, 사람 지갑 승인 UI입니다. 현재 승인은 로컬 human-only CLI이고 구매마다 예약 가스가 발생합니다. 임의 UserOperation에 대한 session 권한이나 범용 ERC-7579 모듈을 주장하지 않습니다.

References: [Chrome Side Panel](https://developer.chrome.com/docs/extensions/reference/api/sidePanel), [Messaging](https://developer.chrome.com/docs/extensions/develop/concepts/messaging), [x402 Bazaar](https://docs.x402.org/extensions/bazaar).